@unbrained/pm-cli 2026.8.26 → 2026.8.28

package/.agents/skills/pm-extensions/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: pm-extensions
+description: Manages pm-cli package and extension lifecycle — explore, install, activate, author, diagnose, and release-safe validation. Use when building, integrating, or troubleshooting pm packages, extensions, and extension-provided commands.
+license: MIT
+compatibility: Requires pm package/extension commands and local project/global extension directories.
+metadata:
+  owner: unbrained
+  domain: pm-cli
+  scope: extension-workflow
+---
+
+# pm Packages and Extensions Skill
+
+Extensions are how pm becomes specific to a project without forking it. They
+register commands, item types, importers, exporters, search providers, and
+profiles over the same substrate.
+
+## Load Order
+
+| Tier | Load                                              | Cost      | When                          |
+| ---- | ------------------------------------------------- | --------- | ----------------------------- |
+| 0    | This file                                         | ~650 tok  | Always.                       |
+| 1    | `pm package explore --project`                    | ~0.5-2k   | See what is installed.        |
+| 1    | `pm package doctor --detail deep`                 | ~1-3k     | Diagnose activation failures. |
+| 2    | `pm contracts --runtime-only --availability-only` | ~1-2k     | What this install exposes.    |
+| 3    | `references/*.md` below                           | ~0.3-1k   | Procedure detail.             |
+| 4    | `docs/EXTENSIONS.md`, `docs/EXTENSION_LIFECYCLE.md` | varies  | Only when routed there.       |
+
+Optional deep routing that never goes stale:
+
+```bash
+pm install guide-shell --project
+pm guide extensions
+```
+
+## Non-Negotiables
+
+- Author identity is detected automatically. **Never pass `--author`, never set
+  `PM_AUTHOR`.**
+- Declare the minimum capability set; anything undeclared is not granted.
+- Never mirror a public SDK type inside a package — import it or derive it.
+- Inspect before mutating; verify exposure after.
+
+## Before Creating A Package
+
+Check whether an existing package already owns the capability. Extending a
+published package is almost always correct; a near-duplicate package is the
+most expensive mistake in an ecosystem.
+
+```bash
+pm package explore --project
+pm package explore --global
+pm contracts --runtime-only --availability-only
+```
+
+## Lifecycle Loop
+
+```bash
+pm package explore --project              # inspect state first
+pm package manage --detail summary
+pm package doctor --detail deep
+pm install <package> --project            # then mutate
+pm contracts --command <extension-command> --flags-only
+pm package doctor --detail deep           # verify after
+```
+
+Order matters: inspect, mutate, verify exposure, record evidence on the linked
+pm item. Deactivation and uninstall are reversible only if you recorded what
+they removed.
+
+## Authoring
+
+Author with `defineExtension` and declared capabilities. A capability the
+manifest does not declare is not granted at activation, which is what keeps a
+third-party extension from silently widening its own reach.
+
+```bash
+pm contracts --command package --flags-only
+pm contracts --schema-only
+```
+
+Packages ship TypeScript entries and are loaded through native type stripping,
+so there is no separate build step for a package's own sources. Installed npm
+extensions are not tracked in the host repository; only the managed-extension
+manifest is.
+
+## Verification
+
+```bash
+pm package doctor --detail deep
+pm contracts --runtime-only --availability-only
+pm health --check-only
+pm validate --check-resolution
+```
+
+An extension is correctly integrated when `pm contracts` reports its commands
+and actions as available and `pm <command> --help --json` returns a complete
+flag contract for each one.
+
+## References
+
+| Need                              | Load                                                | Cost     |
+| --------------------------------- | ---------------------------------------------------- | -------- |
+| Lifecycle recipes                  | [Extension lifecycle](references/LIFECYCLE.md)       | ~450 tok |
+| Failure diagnosis playbook         | [Troubleshooting](references/TROUBLESHOOTING.md)     | ~300 tok |
+| Authoring an extension end to end  | [Authoring](references/AUTHORING.md)                 | ~900 tok |

package/.agents/skills/pm-extensions/references/AUTHORING.md

@@ -0,0 +1,95 @@
+# Authoring An Extension
+
+The procedure, with routes into the detail rather than a copy of it.
+
+## Route To A Section
+
+```bash
+grep -n "^## " docs/EXTENSIONS.md
+sed -n '<start>,<end>p' docs/EXTENSIONS.md
+```
+
+| Topic                          | Heading in docs/EXTENSIONS.md |
+| ------------------------------ | ----------------------------- |
+| Where packages come from        | `## Package Sources`          |
+| Package manifest fields         | `## Package Manifest`         |
+| Directory layout                | `## Extension Layout`         |
+| Extension manifest fields       | `## Extension Manifest`       |
+| Capability and governance policy| `## Governance Policy`        |
+| Name collisions                 | `## Registration Collisions`  |
+| Runtime APIs available          | `## Runtime APIs`             |
+| Lifecycle commands              | `## Lifecycle Commands`       |
+| Upgrades                        | `## Upgrade Workflow`         |
+| Runnable examples               | `## Runnable Examples`        |
+
+Author-time contracts live in
+[docs/EXTENSION_AUTHOR_CONTRACTS.md](../../../../docs/EXTENSION_AUTHOR_CONTRACTS.md)
+and lifecycle detail in
+[docs/EXTENSION_LIFECYCLE.md](../../../../docs/EXTENSION_LIFECYCLE.md).
+
+## Shape
+
+An extension exports `activate(api)` and registers through the `register*`
+family, or declares itself with `defineExtension` and a blueprint. Both forms
+end in the same registration, so choose declarative authoring when the surface
+is static and imperative activation when registration depends on runtime state.
+
+Registrable surfaces:
+
+- Commands and command actions
+- Custom item types and their fields
+- Statuses with declared lifecycle roles
+- Importers and exporters
+- Search providers
+- Project profiles
+- Templates
+
+## Capabilities Are Declared, Not Assumed
+
+The manifest declares what the extension may do. Anything undeclared is not
+granted at activation. Declare the minimum, then verify:
+
+```bash
+pm package doctor --detail deep
+pm contracts --runtime-only --availability-only
+```
+
+A declared version bound must be one the loader actually enforces — a bound
+written in a field nothing reads is worse than no bound, because it reads as a
+guarantee.
+
+## Sources
+
+Extensions come from npm, GitHub, a bundled package, or a local directory, and
+the same source works from all four. Package runtime modules use ordinary
+static ESM imports from the published SDK entrypoints; they do not locate copied
+source files through environment variables or generate loader shims.
+
+Never mirror a public SDK type inside a package. Import it, or derive its shape
+with `typeof`. A hand-copied signature becomes immutable consumer code the
+moment the package publishes.
+
+## Author Loop
+
+```bash
+pm package init <name>                       # scaffold
+# ...implement extensions/*.ts...
+pm install <path-or-name> --project          # install locally
+pm package doctor --detail deep              # activation diagnostics
+pm contracts --command <your-command> --flags-only
+pm <your-command> --help --json              # the contract a consumer will read
+```
+
+Record the work on a pm item as you go: link the package sources with
+`pm files`, the docs with `pm docs`, and a runnable check with `pm test`.
+
+## Release Safety
+
+```bash
+pm package doctor --detail deep
+pm contracts --runtime-only --availability-only
+pm health --check-only
+```
+
+An extension that changes what a shared command emits is changing a contract,
+not adding a feature. Treat the contract snapshot as the review artifact.

package/.agents/skills/pm-extensions/references/LIFECYCLE.md

@@ -0,0 +1,40 @@
+# Extension Lifecycle Recipes
+
+## Inspect Current State
+
+```bash
+pm package explore --project
+pm package manage --detail summary
+pm package doctor --detail deep
+```
+
+## Install and Activate
+
+```bash
+pm install <target> --project
+pm package activate <target> --project
+pm package doctor --detail summary
+```
+
+## Adopt Existing Extensions
+
+```bash
+pm package adopt <name> --project
+pm package adopt-all --project
+pm package manage --detail summary
+```
+
+## Deactivate / Uninstall
+
+```bash
+pm package deactivate <target> --project
+pm package uninstall <target> --project
+pm package doctor --detail deep
+```
+
+## Contract Checks
+
+```bash
+pm contracts --runtime-only --availability-only
+pm contracts --command package --flags-only
+```

package/.agents/skills/pm-extensions/references/TROUBLESHOOTING.md

@@ -0,0 +1,25 @@
+# Extension Troubleshooting
+
+## Common Diagnostic Sequence
+
+1. `pm extension explore --project`
+2. `pm extension manage --detail summary`
+3. `pm extension doctor --detail deep --trace`
+4. `pm contracts --runtime-only --availability-only`
+
+## Symptoms and Checks
+
+- **Command not visible**
+  - Confirm extension is managed and active.
+  - Confirm capability includes `commands`.
+  - Check `pm contracts` action availability.
+
+- **Schema mismatch**
+  - Confirm capability includes `schema`.
+  - Re-run doctor with `--detail deep --trace`.
+  - Validate runtime-only contracts output.
+
+- **Unexpected behavior after updates**
+  - Check registration precedence with manage/doctor.
+  - Run with `--no-extensions` to isolate core behavior.
+  - Re-activate extension after fixing manifest or entry path.

package/.agents/skills/pm-sdk/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: pm-sdk
+description: Implements pm-cli integrations on the published @unbrained/pm-cli SDK entrypoints and runtime contracts. Use when authoring extensions, embedding pm in another tool, building a domain on pm primitives, or keeping a wrapper aligned with command/action schema changes.
+license: MIT
+compatibility: Requires Node.js and access to pm contracts output for runtime parity checks.
+metadata:
+  owner: unbrained
+  domain: pm-cli
+  scope: sdk-integration
+---
+
+# pm SDK Skill
+
+The SDK is the implementation; the CLI and the MCP server are thin consumers of
+it. Anything the CLI can do is reachable from the published surface, and an
+integration should never import repository internals to get it.
+
+## Load Order
+
+| Tier | Load                                            | Cost      | When                                  |
+| ---- | ----------------------------------------------- | --------- | ------------------------------------- |
+| 0    | This file                                       | ~700 tok  | Always.                               |
+| 1    | `pm contracts --summary`                        | ~2.6k     | The command/action surface.           |
+| 1    | `sdk/public-surface.json`                       | query it  | Exact exported symbols and signatures.|
+| 2    | `pm contracts --command <cmd> --full --json`    | ~1-4k     | One command's complete contract.      |
+| 3    | `references/*.md` below                         | ~0.3-1k   | Procedure detail.                     |
+| 4    | `docs/SDK.md` **by section only**               | 45k whole | Never read whole; grep to a heading.  |
+
+Optional deep routing that never goes stale:
+
+```bash
+pm install guide-shell --project
+pm guide sdk
+pm guide tokens --depth brief
+```
+
+## Entrypoints
+
+Import the narrowest entrypoint that owns the capability. Startup cost is
+proportional to what you import.
+
+| Export                                    | Capability family                                        |
+| ----------------------------------------- | -------------------------------------------------------- |
+| `@unbrained/pm-cli/sdk/core`              | Items, schema, profile, transactions, runtime primitives  |
+| `@unbrained/pm-cli/sdk/query`             | List and search engines, filtering, pagination, rendering |
+| `@unbrained/pm-cli/sdk/graph`             | Relationship stores, traversal, analytics, remediation    |
+| `@unbrained/pm-cli/sdk/governance`        | Validation, health, gc, transaction cleanup               |
+| `@unbrained/pm-cli/sdk/merge`             | VCS-neutral tracker merge contracts                       |
+| `@unbrained/pm-cli/sdk/authoring`         | Extension blueprints, builders, manifests                 |
+| `@unbrained/pm-cli/sdk/contracts`         | Static command/action contracts, expected-error protocol  |
+| `@unbrained/pm-cli/sdk/runtime`           | Embedded command execution, package runtime helpers       |
+| `@unbrained/pm-cli/sdk/testing`           | Package and extension assertion/invocation helpers        |
+| `@unbrained/pm-cli/sdk`                   | Compatibility aggregate over every supported export       |
+| `@unbrained/pm-cli/sdk/public-surface.json` | Machine-readable surface snapshot shipped with the package |
+| `@unbrained/pm-cli/cli`                   | Executable entry (`runPmCli`), not a typed library API    |
+
+Query the shipped surface instead of guessing a symbol name:
+
+```bash
+jq -r '.entrypoints["./sdk/graph"].symbols[].name' \
+  node_modules/@unbrained/pm-cli/sdk/public-surface.json | head -40
+```
+
+## Non-Negotiables
+
+- Never import from `src/core/...` or any unpublished module path. The boundary
+  is gated and a private import fails the build.
+- Never mirror an SDK type in your own package. Import it or derive it with
+  `typeof`; a hand-copied signature becomes immutable consumer code.
+- Treat `pm contracts` output as the source of truth for flags, actions, and
+  availability. Snapshot it in a test so drift fails rather than surprises.
+- Author identity is detected automatically. Pass an author only for a
+  deliberate identity override.
+
+## Integration Loop
+
+1. Capture the runtime surface: `pm contracts --schema-only`,
+   `pm contracts --runtime-only --availability-only`.
+2. Map payload fields to contract keys — do not assume the CLI flag spelling
+   equals the SDK option key.
+3. Implement against the narrowest entrypoint.
+4. Add a regression test that fails when a required contract field drifts.
+5. Verify the packed artifact, not just the working tree.
+
+## Surface Compatibility
+
+The published surface is a reviewed artifact. Additive changes are recorded;
+removals and signature changes require an explicit acknowledgement with a
+reason that stays in the snapshot.
+
+```bash
+pnpm sdk:surface:check
+pnpm sdk:surface:update
+pnpm sdk:surface:update -- --acknowledge-breaking "<release rationale>"
+```
+
+Every package export that declares a `types` path must carry a classification,
+so a new public entrypoint cannot ship ungoverned.
+
+## References
+
+| Need                                        | Load                                                    | Cost     |
+| ------------------------------------------- | -------------------------------------------------------- | -------- |
+| Step-by-step integration checklist           | [Integration checklist](references/INTEGRATION_CHECKLIST.md) | ~400 tok |
+| Prompt templates                             | [Prompts](references/PROMPTS.md)                          | ~200 tok |
+| Which entrypoint owns which capability       | [Surface map](references/SURFACE_MAP.md)                  | ~900 tok |
+| Building a non-PM domain on pm primitives    | [Domain modeling](references/DOMAIN_MODELING.md)          | ~900 tok |

package/.agents/skills/pm-sdk/references/DOMAIN_MODELING.md

@@ -0,0 +1,78 @@
+# Modeling A Domain On pm Primitives
+
+pm's primitives are not specific to software project management. A record with
+a type, a status lifecycle, typed relationships, an append-only history, and
+bounded reads describes many domains. This reference is the procedure for
+building one.
+
+## The Primitive Set
+
+| Primitive            | What it gives the domain                                  |
+| -------------------- | ---------------------------------------------------------- |
+| Item type            | The nouns of the domain                                     |
+| Status + lifecycle role | The state machine each noun moves through               |
+| Typed relationship   | The verbs between nouns, with direction and inverse         |
+| Custom fields        | Domain attributes with declared types                       |
+| Append-only history  | Immutable proof of every transition, restorable to any version |
+| Assurance gate       | The domain's invariants, declared as data                   |
+| Projection + budget  | Bounded reads that stay usable as the corpus grows          |
+| Extension            | Domain-specific commands over the same substrate            |
+
+## Procedure
+
+1. **Name the nouns as item types.**
+
+   ```bash
+   pm schema add-type --name Experiment --description "One training run"
+   pm contracts --schema-only
+   ```
+
+2. **Give each type its lifecycle.** A status without a declared lifecycle role
+   is orphaned from every work-selection surface, so declare the role.
+
+3. **Name the verbs as relationship kinds.** Prefer the built-in typed kinds
+   where the meaning matches — `implements`, `verifies`, `discovered_from`,
+   `supersedes`, `incident_from`, `blocked_by`, `parent`. Reach for `related`
+   only when the relationship genuinely has no direction.
+
+4. **Declare invariants rather than writing checker scripts.** A floor, a
+   ceiling, or a monotone property over the record is expressible as an
+   assurance measurement plus an assertion, evaluated by the SDK and bound to a
+   trigger. See `pm guide assurance`.
+
+5. **Ship domain verbs as an extension**, not as a fork. Extensions register
+   commands, item types, importers, exporters, search providers, and profiles
+   through `defineExtension` and declared capabilities.
+
+6. **Prove it from the published surface only.** If the domain needs something
+   the published SDK cannot express, that is a gap in the SDK, not a reason to
+   import internals.
+
+## Workflow Shapes This Already Serves
+
+- **Tracker** — the default shape: work items, lifecycle, evidence.
+- **Evaluation and benchmark** — cases as items, runs as history entries,
+  scores as recorded verdicts, invariants as gates.
+- **RL and sim-to-RL environment** — an episode is a bounded observation, an
+  action is a recorded mutation, the trajectory is the history stream read in
+  order, and the reward is a declared predicate over recorded state.
+- **Incident and change management** — `incident_from` and `supersedes` carry
+  causality; history carries the audit trail.
+- **Content-addressed or temporal domains** — items as versions, `supersedes`
+  as lineage, point-in-time reads as the query.
+
+The property that makes all of these work is the same one: every mutation is
+recorded immutably and every read can be bounded, so the record is both proof
+and context.
+
+## Checks Before Calling A Domain Pack Done
+
+```bash
+pm contracts --schema-only --json | jq '.schema.types'
+pm validate --check-lifecycle --check-resolution
+pm graph audit --json | jq '.profile.edges_by_kind'
+pm assurance run <your-gate> --trigger ci --dry-run --json
+```
+
+A domain pack is complete when a new agent can be handed the workspace and the
+contracts, with no prose, and still act correctly.

package/.agents/skills/pm-sdk/references/INTEGRATION_CHECKLIST.md

@@ -0,0 +1,31 @@
+# SDK Integration Checklist
+
+## Contract Capture
+
+```bash
+pm contracts --schema-only --json
+pm contracts --runtime-only --availability-only --json
+pm contracts --command <command> --flags-only --json
+```
+
+## Implementation Rules
+
+- Use `@unbrained/pm-cli/sdk` exports only.
+- Do not import internal runtime modules from `src/core/...`.
+- Keep action/flag mappings derived from `pm contracts` outputs.
+- Handle extension-unavailable states through availability metadata.
+
+## Validation
+
+```bash
+pnpm build
+node scripts/run-tests.mjs test -- <targeted sdk/integration tests>
+node scripts/run-tests.mjs coverage
+```
+
+## Release Readiness
+
+```bash
+node scripts/release/docs-skills-gate.mjs
+node scripts/release/run-gates.mjs --telemetry-mode best-effort
+```

package/.agents/skills/pm-sdk/references/PROMPTS.md

@@ -0,0 +1,13 @@
+# SDK Prompt Templates
+
+## Runtime Contract Mapping
+
+`Map this integration request to pm contracts output first, then generate implementation steps keyed to command flags and action schema fields.`
+
+## Extension Capability Design
+
+`Design extension capabilities for <feature> using defineExtension. Include only needed capabilities and provide a verification command list for activation and contracts checks.`
+
+## Wrapper Parity Check
+
+`Audit wrapper action/command mapping parity against current pm contracts output and report any missing or stale fields with patch recommendations.`

package/.agents/skills/pm-sdk/references/SURFACE_MAP.md

@@ -0,0 +1,82 @@
+# SDK Surface Map
+
+Where each capability lives, and how to reach the detail without loading
+[docs/SDK.md](../../../../docs/SDK.md) whole (~45k tokens).
+
+## Route To A Section, Not To The File
+
+```bash
+grep -n "^## \|^### " docs/SDK.md          # heading index, ~40 lines
+sed -n '<start>,<end>p' docs/SDK.md        # read one section
+```
+
+| Topic                                    | Heading in docs/SDK.md            |
+| ---------------------------------------- | --------------------------------- |
+| Install and package resolution            | `## Install`                      |
+| Entrypoints and import cost               | `## Import Surfaces`              |
+| Surface snapshot and breaking-change gate | `### Public-surface compatibility`|
+| The full export inventory                 | `## Public Exports`               |
+| Building a custom project tool            | `### Build an entire custom project tool` |
+| Building a non-PM domain                  | `### Build a non-PM temporal domain` |
+| Plan workflows                            | `### Plan workflows`              |
+| History, restore, rich item reads         | `### Immutable history and rich item reads` |
+| Linked resources and dependency governance| `### Linked resources and dependency governance` |
+| Output budgets and discovery              | `### Agent output budgets and discovery` |
+| Static and runtime contracts              | `## Static And Runtime Contracts` |
+| Atomic workspace transactions             | `### Atomic workspace transactions` |
+| Schema evolution                          | `### Schema evolution and workspace history` |
+| Query execution                           | `### Query execution`             |
+| Context relevance and evaluation          | `### Context relevance and evaluation` |
+| Extension capability requirements         | `## Capability Requirements`      |
+| Declarative authoring and blueprints      | `## Declarative Authoring`        |
+| Testing helpers                           | `## Testing Helpers`              |
+| Custom item types                         | `## Custom Item Type`             |
+| Importers and exporters                   | `## Importer / Exporter`          |
+| Search providers                          | `## Search Provider`              |
+
+## Query The Shipped Surface
+
+`sdk/public-surface.json` ships inside the package, so an integration can read
+the exact surface it compiled against without locating repository files.
+
+```bash
+SURFACE=node_modules/@unbrained/pm-cli/sdk/public-surface.json
+
+# Which entrypoints exist and how they are classified
+jq -r '.entrypoints | to_entries[] | "\(.key)\t\(.value.classification)"' "$SURFACE"
+
+# Does a symbol exist, and where
+jq -r --arg n createItem '.entrypoints | to_entries[]
+  | select(.value.symbols[]?.name == $n) | .key' "$SURFACE"
+
+# The exact signature the package compiled against
+jq -r --arg n createItem '.entrypoints["./sdk"].symbols[]
+  | select(.name == $n) | .signature' "$SURFACE"
+
+# Stable error-code vocabulary
+jq -r '.error_codes[]' "$SURFACE" | head -30
+```
+
+Classifications carry intent:
+
+- `supported` — stable authoring surface.
+- `contract_data` — generated contract tables.
+- `advanced_export` — reachable but not the recommended path.
+- `aggregate_alias` — republishes another entrypoint's declarations verbatim.
+- `executable_entry` — the CLI runtime entry, not a typed library API.
+
+## Other Contract Artifacts
+
+| Artifact                                   | Answers                                        |
+| ------------------------------------------ | ---------------------------------------------- |
+| `pm contracts --summary --json`             | Commands, intents, per-command token ceilings   |
+| `pm contracts --command <c> --full --json`  | Flags, exit vocabulary, output contract         |
+| `pm contracts --schema-only`                | Item schema, types, statuses, fields            |
+| `pm contracts --runtime-only --availability-only` | What this installation actually exposes   |
+| `pm contracts --json --full \| jq '.mcp_tools'` | The MCP tool surface                        |
+| `pm contracts --json --full \| jq '.relationship_kind_contracts'` | Edge kinds and inverses   |
+| `docs/generated/AGENT_COMMAND_SURFACE.md`   | Command visibility tiers                        |
+
+`contracts --json --full` is large enough that the default budget omits it.
+Pass `--output-budget unbounded` when scripting it, and never into an agent's
+own context unfiltered — pipe it through `jq` first.