@unbrained/pm-cli 2026.6.24 → 2026.6.30

package/packages/pm-governance-audit/extensions/governance-audit/manifest.json

@@ -1,7 +1,7 @@
 {
   "name": "builtin-governance-audit",
   "version": "0.1.0",
-  "entry": "./index.js",
+  "entry": "./index.ts",
   "priority": 0,
   "trusted": true,
   "sandbox_profile": "restricted",
@@ -15,7 +15,7 @@
   },
   "capabilities": ["commands", "schema", "hooks"],
   "manifest_version": 1,
-  "pm_min_version": "2026.5.0",
+  "pm_min_version": "2026.6.24",
   "activation": {
     "commands": ["comments-audit", "dedupe-audit", "dedupe-merge", "normalize"]
   }

package/packages/pm-governance-audit/extensions/governance-audit/runtime.ts

@@ -1,6 +1,6 @@
 import path from "node:path";
 import { pathToFileURL } from "node:url";
-import type { GlobalOptions } from "../../../../src/sdk/runtime.js";
+import type { GlobalOptions } from "@unbrained/pm-cli/sdk/runtime";
 
 const PM_PACKAGE_ROOT_ENV = "PM_CLI_PACKAGE_ROOT";
 

package/packages/pm-guide-shell/extensions/guide-shell/index.ts

@@ -2,7 +2,7 @@ import type {
   CommandDefinition,
   ExtensionApi,
   ServiceOverrideContext,
-} from "../../../../src/sdk/index.js";
+} from "@unbrained/pm-cli/sdk";
 import {
   renderGuideShellPackageOutput,
   runCompletionPackage,
@@ -10,7 +10,7 @@ import {
   runCompletionTagsPackage,
   runCompletionTypesPackage,
   runGuidePackage,
-} from "./runtime.js";
+} from "./runtime.ts";
 
 export const manifest = {
   name: "builtin-guide-shell",

package/packages/pm-guide-shell/extensions/guide-shell/manifest.json

@@ -1,7 +1,7 @@
 {
   "name": "builtin-guide-shell",
   "version": "0.1.0",
-  "entry": "./index.js",
+  "entry": "./index.ts",
   "priority": 0,
   "trusted": true,
   "sandbox_profile": "strict",
@@ -15,7 +15,7 @@
   },
   "capabilities": ["commands", "schema", "services"],
   "manifest_version": 1,
-  "pm_min_version": "2026.5.0",
+  "pm_min_version": "2026.6.24",
   "activation": {
     "commands": ["completion", "completion-statuses", "completion-tags", "completion-types", "guide"]
   }

package/packages/pm-guide-shell/extensions/guide-shell/runtime.ts

@@ -1,6 +1,6 @@
 import path from "node:path";
 import { pathToFileURL } from "node:url";
-import type { GlobalOptions, ServiceOverrideContext } from "../../../../src/sdk/index.js";
+import type { GlobalOptions, ServiceOverrideContext } from "@unbrained/pm-cli/sdk";
 
 const PM_PACKAGE_ROOT_ENV = "PM_CLI_PACKAGE_ROOT";
 

package/packages/pm-kanban/README.md

@@ -0,0 +1,97 @@
+# @unbrained/pm-kanban
+
+> Tracker: pm-a7o4 (epic pm-ugqx — extension & package platform maturity).
+
+First-party **archetype exemplar** for pm. Where
+[`pm-command-kit`](../pm-command-kit) shows the `commands` capability, this package
+shows how to ship a *complete project-management archetype* — a profile plus its
+live schema — as an installable pm package, using **public SDK primitives only**.
+
+It adds a fourth archetype, **Kanban continuous flow**, alongside the three
+core-baked profiles (`agile`, `ops`, `research`) without modifying core.
+
+## What it demonstrates
+
+| Surface | What the exemplar does |
+| --- | --- |
+| `api.registerItemTypes([...])` | Registers the `Card` flow item type (`folder: cards`, alias `kanban-card`) as a GLOBAL schema contribution. |
+| `api.registerItemFields([...])` | Registers the flow fields `wip_limit` (number), `class_of_service` (string), and `impediment` (string). |
+| `api.registerProfile(kanbanProfile)` | Registers the complete archetype — types, custom statuses (`doing`, `verifying`), fields, the `Card` workflow, offline search config, a `card` create template, and package recommendations — so `pm profile apply kanban` stages it idempotently, alongside the core `agile`/`ops`/`research` archetypes. |
+
+## Install
+
+```bash
+pm install kanban --project
+```
+
+Installing the package activates its schema. Because item types and fields are
+**global** contributions that built-in commands must see, `manifest.json`
+deliberately declares no `activation.commands`: pm activates the package under its
+conservative tier for every command, so the `Card` type is immediately usable.
+
+## Usage
+
+```bash
+pm schema list                       # Card appears under extension item types
+pm create "Wire up checkout" --type Card --field wip_limit=3 --field class_of_service=expedite
+pm list --type Card
+```
+
+Extension-registered fields are set with the repeatable `--field name=value`
+option (`pm create --help` lists it), keeping custom flow metadata on the item
+without minting a bespoke flag per field.
+
+### Staging the full archetype
+
+The live schema (types/fields) is applied on install. Because the package also
+registers `kanbanProfile` as a project profile, the remaining dimensions — custom
+statuses, the `Card` workflow, search config, and the `card` template — are staged
+in one idempotent command, exactly like a built-in archetype:
+
+```bash
+pm profile list                  # kanban appears, labelled [builtin-kanban-profile]
+pm profile show kanban           # full composition of the archetype
+pm profile apply kanban          # stage every dimension (idempotent; re-runs are no-ops)
+```
+
+SDK consumers can also compute the idempotent diff programmatically:
+
+```ts
+import { planProfileApplication } from "@unbrained/pm-cli/sdk";
+import { kanbanProfile } from "@unbrained/pm-kanban/extensions/kanban/index.ts";
+
+const plan = planProfileApplication(kanbanProfile, currentState);
+// plan.types / plan.statuses / plan.fields / plan.workflows / plan.config / plan.templates
+```
+
+## Package anatomy
+
+```text
+packages/pm-kanban/
+├── package.json                  # pm resources: aliases, extensions, catalog, docs
+├── README.md
+└── extensions/kanban/
+    ├── manifest.json             # capabilities, trusted, sandbox_profile, permissions
+    └── index.ts                  # TypeScript source (type-only SDK imports)
+```
+
+Key conventions for authors:
+
+- The extension ships **only TypeScript** (ADR pm-m1uz). `index.ts` imports
+  *types only* from the published `@unbrained/pm-cli/sdk` specifier; type-only
+  imports are erased, so the module loads without resolving the SDK at
+  module-evaluation time when the package is copied into an installed tracker.
+- The module's `manifest.capabilities` literal must match `manifest.json` exactly.
+  Schema registrations (`registerItemTypes`/`registerItemFields`/`registerMigration`)
+  declare the `schema` capability.
+- A schema package **omits `activation.commands`** so its global item types and
+  fields load for every command. (A package that also owns commands or importers
+  lists those command paths in `activation.commands` for lazy activation.)
+- This extension is pure compute (no fs/network/env/process access), so the
+  manifest declares `"trusted": true`, `"sandbox_profile": "strict"`, and all six
+  permission keys (`fs_read`, `fs_write`, `network`, `env_read`, `env_write`,
+  `process_spawn`) as `false`.
+- Unit tests validate every registration with public SDK helpers:
+  `assertRegisteredItemType` and `assertRegisteredItemField` (via
+  `createExtensionTestHarness`); the profile is exercised with
+  `planProfileApplication`.

package/packages/pm-kanban/extensions/kanban/index.ts

@@ -0,0 +1,191 @@
+/**
+ * pm-kanban — first-party exemplar for shipping a complete project-management
+ * *archetype* as an installable pm package, built on public SDK primitives only.
+ *
+ * Where {@link ../../../pm-command-kit | pm-command-kit} is the exemplar for the
+ * `commands` capability, this package is the exemplar for the `schema` capability
+ * *and* the project-profile model: it ships a self-contained "Kanban
+ * continuous-flow" archetype that complements the three core-baked profiles
+ * (agile/ops/research) without modifying core.
+ *
+ * Two surfaces, two consumers:
+ *
+ * 1. **Live schema** — `activate` registers the archetype's domain schema through
+ *    the public registration API (`registerItemTypes`/`registerItemFields`).
+ *    These are GLOBAL contributions, so the manifest
+ *    deliberately declares no `activation.commands`: pm activates the package
+ *    under its conservative tier for every command, making the `Card` type and
+ *    flow fields available to `pm create`, `pm list --type Card`, and `pm validate`
+ *    the moment the package is installed.
+ * 2. **Profile spec** — {@link kanbanProfile} is a {@link ProjectProfileDefinition}
+ *    describing the *complete* archetype (item types, custom statuses, fields, the
+ *    `Card` workflow, offline search config, a starter template, and package
+ *    recommendations). `activate` registers it through `api.registerProfile`, so
+ *    once the package is installed it resolves by name through `pm profile list`,
+ *    `pm profile show kanban`, and `pm profile apply kanban` — staging the
+ *    non-schema dimensions (statuses/config/templates) idempotently exactly like a
+ *    core archetype, with no consumer code required.
+ *
+ * The extension is intentionally pure: no filesystem, network, environment, or
+ * process access — so its manifest declares `sandbox_profile: "strict"` with all
+ * permissions false. Only types are imported from the published SDK specifier, so
+ * the module loads without resolving the SDK at module-evaluation time when the
+ * package is copied into an installed tracker.
+ */
+import type {
+  ExtensionApi,
+  ProjectProfileDefinition,
+  SchemaFieldDefinition,
+  SchemaItemTypeDefinition,
+} from "@unbrained/pm-cli/sdk";
+
+export const manifest = {
+  name: "builtin-kanban-profile",
+  version: "0.1.0",
+  entry: "./index.js",
+  priority: 0,
+  capabilities: ["schema"],
+};
+
+/**
+ * The Kanban flow card — the archetype's single domain item type.
+ *
+ * `folder` keeps card items in their own `cards/` directory and `aliases` lets
+ * authors type the friendlier `pm create kanban-card`. Registered globally so it
+ * is usable wherever built-in commands accept a type.
+ */
+export const KANBAN_ITEM_TYPE: SchemaItemTypeDefinition = {
+  name: "Card",
+  folder: "cards",
+  aliases: ["kanban-card"],
+  required_create_fields: [],
+};
+
+/**
+ * Flow-control front-matter fields for a Kanban board. None shadow a built-in
+ * field key, so they register cleanly alongside core metadata.
+ */
+export const KANBAN_ITEM_FIELDS: SchemaFieldDefinition[] = [
+  { name: "wip_limit", type: "number", optional: true },
+  { name: "class_of_service", type: "string", optional: true },
+  { name: "impediment", type: "string", optional: true },
+];
+
+/**
+ * The complete Kanban archetype as a {@link ProjectProfileDefinition}.
+ *
+ * This is the authoring anchor a profile package builds on: it bundles the item
+ * type, two flow statuses, the flow fields, the `Card` workflow, offline-friendly
+ * search config, a starter create template, and advisory package recommendations
+ * into one declarative archetype. `activate` hands it to `api.registerProfile`, so
+ * `pm profile apply kanban` stages every dimension idempotently. The field keys
+ * and type name are kept in lockstep with {@link KANBAN_ITEM_TYPE} and
+ * {@link KANBAN_ITEM_FIELDS} (the live registration surfaces); the package test
+ * asserts they never drift.
+ */
+export const kanbanProfile: ProjectProfileDefinition = {
+  name: "kanban",
+  title: "Kanban continuous flow",
+  summary: "Continuous-flow delivery with WIP limits, a verifying stage, class of service, and blocked-reason tracking.",
+  types: [
+    {
+      name: "Card",
+      folder: "cards",
+      aliases: ["kanban-card"],
+      description: "A unit of flow work that moves across the board to done.",
+    },
+  ],
+  statuses: [
+    {
+      id: "doing",
+      roles: ["active"],
+      aliases: ["wip"],
+      description: "Card is actively being worked within the column WIP limit.",
+    },
+    {
+      id: "verifying",
+      roles: ["active"],
+      aliases: ["verify"],
+      description: "Work is implementation-complete and being verified before done.",
+    },
+  ],
+  fields: [
+    {
+      key: "wip_limit",
+      type: "number",
+      commands: ["create", "update", "list"],
+      description: "Maximum number of cards allowed in the card's current column.",
+      aliases: ["wip"],
+    },
+    {
+      key: "class_of_service",
+      type: "string",
+      commands: ["create", "update", "list"],
+      description: "Delivery class: standard, expedite, fixed-date, or intangible.",
+      aliases: ["cos"],
+    },
+    {
+      key: "impediment",
+      type: "string",
+      commands: ["create", "update"],
+      description: "The impediment currently blocking the card, recorded for flow analysis.",
+    },
+  ],
+  workflows: [
+    {
+      type: "Card",
+      allowed_transitions: [
+        ["open", "doing"],
+        ["doing", "verifying"],
+        ["verifying", "doing"],
+        ["verifying", "closed"],
+        ["doing", "blocked"],
+        ["blocked", "doing"],
+      ],
+    },
+  ],
+  config: [
+    { key: "search_provider", value: "bm25", summary: "Offline BM25 lexical search needs no embedding service." },
+    { key: "search_max_results", value: "30", summary: "Board-sized result cap for quick card lookup." },
+  ],
+  templates: [
+    {
+      name: "card",
+      options: {
+        type: "Card",
+        priority: "2",
+        tags: "kanban",
+        acceptanceCriteria: "Card delivers the stated outcome and meets the definition of done.",
+        body: "## Context\n\n## Definition of done\n- [ ] \n",
+      },
+    },
+  ],
+  packages: [
+    { spec: "templates", reason: "Reusable create templates for recurring card shapes." },
+    { spec: "lifecycle-hooks", reason: "Automate flow transitions and WIP-limit reactions." },
+    { spec: "calendar", reason: "Visualize delivery cadence and due dates." },
+  ],
+};
+
+/**
+ * Register the Kanban archetype. The item types and fields are GLOBAL schema
+ * contributions, so they are available to every built-in command the moment the
+ * package is installed. The {@link kanbanProfile} is registered as a project
+ * profile so `pm profile apply kanban` can stage the remaining archetype
+ * dimensions (statuses/config/templates/workflow) idempotently. All three calls
+ * are covered by the package's single declared `schema` capability.
+ */
+export function activate(api: ExtensionApi): void {
+  api.registerItemFields(KANBAN_ITEM_FIELDS);
+  api.registerItemTypes([KANBAN_ITEM_TYPE]);
+  api.registerProfile(kanbanProfile);
+}
+
+/** No teardown state to release; the archetype schema is host-managed. */
+export function deactivate(): void {}
+
+export default {
+  manifest,
+  activate,
+  deactivate,
+};

package/packages/pm-kanban/extensions/kanban/manifest.json

@@ -0,0 +1,19 @@
+{
+  "name": "builtin-kanban-profile",
+  "version": "0.1.0",
+  "entry": "./index.ts",
+  "priority": 0,
+  "trusted": true,
+  "sandbox_profile": "strict",
+  "permissions": {
+    "fs_read": false,
+    "fs_write": false,
+    "network": false,
+    "env_read": false,
+    "env_write": false,
+    "process_spawn": false
+  },
+  "capabilities": ["schema"],
+  "manifest_version": 1,
+  "pm_min_version": "2026.6.24"
+}

package/packages/pm-kanban/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@unbrained/pm-kanban",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "description": "First-party pm archetype package: a complete Kanban continuous-flow profile built on public SDK primitives.",
+  "homepage": "https://github.com/unbraind/pm-cli/tree/main/packages/pm-kanban#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/unbraind/pm-cli.git",
+    "directory": "packages/pm-kanban"
+  },
+  "bugs": {
+    "url": "https://github.com/unbraind/pm-cli/issues"
+  },
+  "keywords": [
+    "pm-package",
+    "project-management",
+    "sdk",
+    "profile",
+    "archetype",
+    "kanban",
+    "exemplar"
+  ],
+  "pm": {
+    "aliases": [
+      "kanban"
+    ],
+    "extensions": [
+      "extensions/kanban"
+    ],
+    "catalog": {
+      "display_name": "Kanban Archetype",
+      "category": "sdk",
+      "summary": "Installable Kanban continuous-flow archetype: Card item type, flow fields, and a ProjectProfileDefinition built on public SDK primitives.",
+      "tags": [
+        "sdk",
+        "profile",
+        "archetype",
+        "kanban",
+        "schema",
+        "exemplar"
+      ],
+      "links": {
+        "docs": "https://github.com/unbraind/pm-cli/tree/main/packages/pm-kanban#readme",
+        "repository": "https://github.com/unbraind/pm-cli/tree/main/packages/pm-kanban",
+        "report": "https://github.com/unbraind/pm-cli/issues"
+      }
+    },
+    "docs": [
+      "README.md"
+    ],
+    "examples": [
+      "README.md"
+    ]
+  }
+}

package/packages/pm-lifecycle-hooks/extensions/lifecycle-hooks/index.ts

@@ -1,4 +1,4 @@
-import type { ExtensionApi } from "../../../../src/sdk/index.js";
+import type { ExtensionApi } from "@unbrained/pm-cli/sdk";
 
 export const manifest = {
   name: "builtin-lifecycle-hooks",

package/packages/pm-lifecycle-hooks/extensions/lifecycle-hooks/manifest.json

@@ -1,7 +1,7 @@
 {
   "name": "builtin-lifecycle-hooks",
   "version": "0.1.0",
-  "entry": "./index.js",
+  "entry": "./index.ts",
   "priority": 0,
   "trusted": true,
   "sandbox_profile": "strict",
@@ -15,5 +15,5 @@
   },
   "capabilities": ["hooks"],
   "manifest_version": 1,
-  "pm_min_version": "2026.5.0"
+  "pm_min_version": "2026.6.24"
 }

package/packages/pm-linked-test-adapters/extensions/linked-test-adapters/index.ts

@@ -1,11 +1,11 @@
-import type { CommandDefinition, ExtensionApi } from "../../../../src/sdk/index.js";
+import type { CommandDefinition, ExtensionApi } from "@unbrained/pm-cli/sdk";
 import {
   runTestRunsListPackage,
   runTestRunsLogsPackage,
   runTestRunsResumePackage,
   runTestRunsStatusPackage,
   runTestRunsStopPackage,
-} from "./runtime.js";
+} from "./runtime.ts";
 
 export const manifest = {
   name: "builtin-linked-test-adapters",

package/packages/pm-linked-test-adapters/extensions/linked-test-adapters/manifest.json

@@ -1,7 +1,7 @@
 {
   "name": "builtin-linked-test-adapters",
   "version": "0.1.0",
-  "entry": "./index.js",
+  "entry": "./index.ts",
   "priority": 0,
   "trusted": true,
   "sandbox_profile": "none",
@@ -15,7 +15,7 @@
   },
   "capabilities": ["commands", "schema"],
   "manifest_version": 1,
-  "pm_min_version": "2026.5.0",
+  "pm_min_version": "2026.6.24",
   "activation": {
     "commands": [
       "test-runs",

package/packages/pm-linked-test-adapters/extensions/linked-test-adapters/runtime.ts

@@ -1,6 +1,6 @@
 import path from "node:path";
 import { pathToFileURL } from "node:url";
-import type { GlobalOptions } from "../../../../src/sdk/index.js";
+import type { GlobalOptions } from "@unbrained/pm-cli/sdk";
 
 const PM_PACKAGE_ROOT_ENV = "PM_CLI_PACKAGE_ROOT";
 

package/packages/pm-search-advanced/extensions/search-advanced/index.ts

@@ -5,8 +5,8 @@ import type {
   SearchProviderDefinition,
   SearchProviderHit,
   SearchProviderQueryContext,
-} from "../../../../src/sdk/index.js";
-import { runAdvancedReindexPackage, runAdvancedSearchPackage } from "./runtime.js";
+} from "@unbrained/pm-cli/sdk";
+import { runAdvancedReindexPackage, runAdvancedSearchPackage } from "./runtime.ts";
 
 export const manifest = {
   name: "builtin-search-advanced",

package/packages/pm-search-advanced/extensions/search-advanced/manifest.json

@@ -1,7 +1,7 @@
 {
   "name": "builtin-search-advanced",
   "version": "0.1.0",
-  "entry": "./index.js",
+  "entry": "./index.ts",
   "priority": 0,
   "trusted": true,
   "sandbox_profile": "restricted",
@@ -19,7 +19,7 @@
     "search"
   ],
   "manifest_version": 1,
-  "pm_min_version": "2026.5.0",
+  "pm_min_version": "2026.6.24",
   "activation": {
     "commands": [
       "reindex",

package/packages/pm-search-advanced/extensions/search-advanced/runtime.ts

@@ -7,7 +7,7 @@ import type {
   ReindexResult,
   SearchOptions,
   SearchResult,
-} from "../../../../src/sdk/runtime.js";
+} from "@unbrained/pm-cli/sdk/runtime";
 
 const PM_PACKAGE_ROOT_ENV = "PM_CLI_PACKAGE_ROOT";
 const DEFAULT_EVAL_FIXTURES_PATH = path.join("tests", "search-eval", "golden-queries.json");

package/packages/pm-templates/extensions/templates/index.ts

@@ -1,4 +1,4 @@
-import type { CommandDefinition, ExtensionApi, GlobalOptions } from "../../../../src/sdk/index.js";
+import type { CommandDefinition, ExtensionApi, GlobalOptions } from "@unbrained/pm-cli/sdk";
 import {
   runTemplatesList as runTemplatesListPackage,
   runTemplatesSave as runTemplatesSavePackage,
@@ -6,7 +6,7 @@ import {
   type TemplatesListResult,
   type TemplatesSaveResult,
   type TemplatesShowResult,
-} from "./runtime.js";
+} from "./runtime.ts";
 
 export const manifest = {
   name: "builtin-templates",

package/packages/pm-templates/extensions/templates/manifest.json

@@ -1,7 +1,7 @@
 {
   "name": "builtin-templates",
   "version": "0.1.0",
-  "entry": "./index.js",
+  "entry": "./index.ts",
   "priority": 0,
   "trusted": true,
   "sandbox_profile": "restricted",
@@ -15,7 +15,7 @@
   },
   "capabilities": ["commands", "schema"],
   "manifest_version": 1,
-  "pm_min_version": "2026.5.0",
+  "pm_min_version": "2026.6.24",
   "activation": {
     "commands": ["templates", "templates list", "templates save", "templates show"]
   }

package/packages/pm-templates/extensions/templates/runtime.ts

@@ -1,6 +1,6 @@
 import path from "node:path";
 import { pathToFileURL } from "node:url";
-import type { GlobalOptions } from "../../../../src/sdk/index.js";
+import type { GlobalOptions } from "@unbrained/pm-cli/sdk";
 
 const PM_PACKAGE_ROOT_ENV = "PM_CLI_PACKAGE_ROOT";
 

package/packages/pm-todos/extensions/todos/index.ts

@@ -3,9 +3,9 @@ import type {
   GlobalOptions,
   ImportExportContext,
   ImportExportRegistrationOptions,
-} from "../../../../src/sdk/index.js";
-import type { TodosExportOptions, TodosExportResult, TodosImportOptions, TodosImportResult } from "./runtime.js";
-import { loadPackageRuntimeModule } from "./runtime-loader.js";
+} from "@unbrained/pm-cli/sdk";
+import type { TodosExportOptions, TodosExportResult, TodosImportOptions, TodosImportResult } from "./runtime.ts";
+import { loadPackageRuntimeModule } from "./runtime-loader.ts";
 
 export const manifest = {
   name: "builtin-todos-import-export",

package/packages/pm-todos/extensions/todos/manifest.json

@@ -1,7 +1,7 @@
 {
   "name": "builtin-todos-import-export",
   "version": "0.1.0",
-  "entry": "./index.js",
+  "entry": "./index.ts",
   "priority": 0,
   "trusted": true,
   "sandbox_profile": "restricted",
@@ -19,7 +19,7 @@
     "importers"
   ],
   "manifest_version": 1,
-  "pm_min_version": "2026.5.0",
+  "pm_min_version": "2026.6.24",
   "activation": {
     "commands": [
       "todos export",