@unbrained/pm-cli 2026.6.24 → 2026.6.30

package/docs/AGENT_GUIDE.md

@@ -102,6 +102,8 @@ pm release <item-id>
 
 | Need | Command |
 |------|---------|
+| The single next action + why | `pm next` (concrete ready leaves first; completed-container closeout rows surface only when no leaf work is ready; `--ready-only` for the tightest output) |
+| Next ready work in one epic | `pm next --parent <id>` |
 | Next work and agenda | `pm context --limit 10` |
 | Comprehensive whole-tracker snapshot | `pm context --depth full` (every section, no per-section row cap) |
 | Status of one epic/subtree | `pm context --parent <id> --depth deep` |

package/docs/CLAUDE_CODE_PLUGIN.md

@@ -55,7 +55,7 @@ This clones the repo, reads `.claude-plugin/marketplace.json` at the root, insta
 claude mcp add --transport stdio pm-mcp -- npx -y --package=@unbrained/pm-cli@latest pm-mcp
 ```
 
-Gives you the 26 MCP tools without skills or slash commands.
+Gives you the 28 MCP tools without skills or slash commands.
 
 ### 3. Direct project `.mcp.json` (project-scoped MCP only)
 
@@ -113,7 +113,7 @@ node scripts/smoke-claude-plugin.mjs
 pnpm smoke:claude-plugin
 ```
 
-Verifies: plugin file structure, manifest name consistency, MCP initialize, 26 tools present, full workflow (init → create → claim → update → link files/docs/tests → get → context → search → validate → health), and session-start hook.
+Verifies: plugin file structure, manifest name consistency, MCP initialize, 28 tools present, full workflow (init → create → claim → update → link files/docs/tests → get → context → search → validate → health), and session-start hook.
 
 ### MCP server smoke test
 

package/docs/COMMANDS.md

@@ -35,6 +35,7 @@ Tracked documentation work: [pm-u9d0](../.agents/pm/epics/pm-u9d0.toon).
 | Verification | `test`, `test-all`, `test-runs`, `validate`, `gc` | run linked tests and repository checks |
 | History | `history`, `history-compact`, `history-redact`, `history-repair`, `activity`, `restore`, `stats` | inspect, compact, redact, re-anchor, and recover item state |
 | Schema | `schema add-type` / `remove-type` / `add-status` / `remove-status` / `add-field` / `remove-field` / `apply-preset` | manage config-driven custom item types (`.agents/pm/schema/types.json`), statuses (`.agents/pm/schema/statuses.json`), and custom metadata fields (`.agents/pm/schema/fields.json`); `apply-preset` adopts a domain type preset; `add-type --infer` derives types from title-prefix conventions |
+| Profiles | `profile list` / `show` / `apply` / `lint` | compose item types, statuses, fields, workflows, config, templates, and recommended packages into archetype bundles (agile/ops/research); `apply` stages every dimension idempotently; `lint` reports author-time consistency findings without writing |
 | 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 | `contracts`, `help`, optional `guide`/`completion` | command contracts plus optional guide-shell docs routing and shell helpers |
@@ -66,6 +67,7 @@ pm install '*' --project
 pm package catalog --project
 pm install npm:@scope/pm-package --project
 pm package describe --project   # by-name surface map of every loaded package
+pm package describe my-package --markdown --output docs/my-package-reference.md
 pm package doctor --project --detail summary
 pm upgrade --dry-run
 pm upgrade --packages-only
@@ -78,6 +80,7 @@ When package-owned commands are unavailable, usage guidance includes an install-
 ## Triage
 
 ```bash
+pm next                                 # the single highest-priority READY item + why, then the ready/blocked queues
 pm context --limit 10
 pm search "calendar reminder validation" --limit 10
 pm get pm-a1b2                          # read one item; add --fields/--depth for lower-token projections
@@ -91,6 +94,14 @@ pm dedupe-audit --mode parent_scope --limit 20
 pm dedupe-merge --keep pm-canonical --close pm-duplicate --dry-run
 ```
 
+Use `pm next` when the only question is "what should I work on now?" — it is the distilled, dependency-aware version of `context`. It computes READINESS rather than just listing active work: an item is **ready** when its status is active, it has no open blockers (neither the scalar `blocked_by` nor any `blocked_by` dependency points at a non-terminal item), and it has no open children (a concrete leaf, never an Epic with open work beneath it). Open containers whose descendants are already terminal are governance closeout rows: they stay out of the normal ready queue while concrete leaf work exists, then surface when closeout is the next action. `pm next` returns one `recommended` item with a deterministic rationale (status, priority, deadline, blocker clearance, parent advancement, downstream unblocks, and completed-container closeout when applicable), a ranked `ready` queue, and a `blocked` companion queue annotated with each item's open blockers so you know exactly what to clear next. In-progress work is recommended before unstarted work. Scope to one epic with `--parent <id>`, cap rows with `--limit`/`--blocked-limit`, drop the blocked list with `--ready-only`, and render markdown with `--format markdown`. Available over MCP as the narrow `pm_next` tool (and the `next` action of `pm_run`).
+
+```bash
+pm next                                 # recommend the next action + ready/blocked queues
+pm next --parent pm-epic01              # scope readiness to one epic's subtree
+pm next --ready-only --limit 3 --json   # tightest agent-loop projection
+```
+
 Use `context` first for a compact active-work snapshot. Use `search` when the request names a concept, component, or prior issue.
 Use `pm get <id>` to read a single item by ID — the single-item read primitive used throughout the agent loop. It accepts `--fields <list>` and `--depth brief|standard|deep|full` for token-minimal projections, and `--tree`/`--tree-depth <n>` to include descendants. `pm get <id> --json` returns the `body` inside the `item` object (`.item.body`); see [Full results, totals, and bodies](#full-results-totals-and-bodies). To duplicate an existing item as a starting point, `pm copy <id> --title "New title"` clones it into a fresh id with lifecycle fields reset.
 `context` standard/deep views include high-level child completion counters plus `recently_created` and `unparented` sections, so agents can spot new orphan work before creating duplicates.
@@ -752,6 +763,32 @@ pm create Spike "Investigate retry backoff"
 
 The option composes with `--defaults`, `--preset`, `--author`, `--agent-guidance`, and `--with-packages`; re-running it is idempotent and reports `registered_type_preset` in JSON output. Already-initialized projects can adopt the same presets without re-running init via `pm schema apply-preset agile|ops|research`.
 
+## Project Profiles
+
+Tracker references: [pm-v37g](../.agents/pm/features/pm-v37g.toon), [pm-bhmk](../.agents/pm/tasks/pm-bhmk.toon), [pm-j1fj](../.agents/pm/features/pm-j1fj.toon).
+
+`pm profile` composes the schema, config, template, and package primitives into complete project-management archetypes. Where a type preset only registers item types, a profile bundles item types, custom statuses, custom fields, per-type workflows, config knobs, create templates, and recommended packages so a fresh tracker can be tailored to an archetype in one idempotent command.
+
+```bash
+pm profile list                  # show built-in archetypes and their composition counts
+pm profile show agile            # full composition of one profile
+pm profile lint agile            # author-time consistency check (graded error/warning; never writes)
+pm profile apply agile --dry-run # preview the diff without writing
+pm profile apply agile           # stage every dimension (idempotent; re-runs are no-ops)
+```
+
+Built-in profiles:
+
+- `agile`: Story/Spike types, a `review` status, `story_points`/`acceptance_owner` fields, a Story workflow, a `story` template, and offline BM25 search config. Recommends `templates`, `calendar`, `search-advanced`.
+- `ops`: Incident/Runbook types, `mitigating`/`monitoring` statuses, `severity`/`service` fields, an Incident workflow, an `incident` template. Recommends `lifecycle-hooks`, `governance-audit`, `calendar`.
+- `research`: Experiment/Hypothesis types, an `analyzing` status, `hypothesis`/`method` fields, an Experiment workflow, an `experiment` template. Recommends `search-advanced`, `templates`, `beads`.
+
+Apply reports a per-dimension diff (`added` / `updated` / `unchanged`). Re-applying an already-applied profile performs zero writes. Package recommendations are advisory — apply never installs packages; `pm profile show <name>` lists the suggested `pm package install <spec>` candidates. The same surface is available to agents through the `pm_profile` MCP tool.
+
+`pm profile lint <name>` runs an author-time consistency check on a built-in or extension-contributed profile without touching the tracker, surfacing graded findings: `error` for problems that would make `apply` throw or silently lose data (invalid/duplicate types, statuses, or fields; unknown/invalid config knobs; malformed workflow transitions) and `warning` for structurally-valid but suspicious content (workflows governing or referencing types/statuses the profile never declares, templates creating an undeclared type, a non-canonical profile name, empty title/summary/package spec). It exits non-zero when the profile has any `error`-severity finding (warnings keep it green), so it gates cleanly in CI as `pm profile lint <name>`. The same check is exposed to package authors as the SDK `lintProjectProfile` / `assertProjectProfile` primitives — see [SDK.md](./SDK.md).
+
+Profiles are extensible: a package can ship its own archetype with `api.registerProfile(profile)` (built on the public SDK `defineProjectProfile` primitive — see [SDK.md](./SDK.md)). When the package is active, its profile appears in `pm profile list` (labelled with its source package) and resolves through `pm profile show`/`apply` exactly like a built-in. Built-in names are reserved, so a package profile can never silently shadow `agile`/`ops`/`research`. The bundled [pm-kanban](../packages/pm-kanban/README.md) package registers a `kanban` continuous-flow archetype this way.
+
 ## 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.

package/docs/EXTENSIONS.md

@@ -32,11 +32,10 @@ Bundled first-party packages live under `packages/pm-*`:
 
 ```bash
 pm package catalog --project
-pm install '*' --project
 pm install all --project
 pm install calendar --project
 pm install search-advanced --project
-pm install governance-audit --project
+pm install kanban --project
 ```
 
 `pm install '*'`, `pm install all`, and shell-expanded `pm install *` are normalized to the same bundled install-all request. First-party package aliases come from each package manifest, with a fallback derived from the `packages/pm-*` directory name.
@@ -87,7 +86,7 @@ Package roots declare resources in `package.json` under `pm`:
 
 Installation activates `pm.extensions`. `pm.docs`, `pm.examples`, `pm.assets`, and `pm.prompts` are catalog metadata (metadata-only — they are discovered and surfaced in the catalog but not executed). Declare agent-facing prompt/slash-command markdown under `pm.prompts` and non-code assets (images, skills, fixtures) under `pm.assets`; their conventional roots are `prompts/` (also `.agents/pm/prompts/`) and `assets/` (also `.agents/pm/assets/`).
 
-`pm package init` emits a root extension (`"extensions": ["."]`) authored fully in TypeScript (ADR [pm-2c28](../.agents/pm/decisions/pm-2c28.toon)): a typed `index.ts`, a strict `tsconfig.json`, and `build`/`test` scripts, with the manifest `entry` pointing at the compiled `./index.js`. Run `npm install && npm run build` to produce that entry before `pm install`. The generated README shows how to author exported command/hook definitions with the SDK [define* builders](../.agents/pm/decisions/pm-3mph.toon). The default `--capability commands` scaffold registers a starter command and a colocated `node:test` suite. `--capability hooks` keeps the starter command and adds an `after_command` lifecycle hook plus SDK testing coverage with `assertRegisteredHook` and `runRegisteredHookForTest`, giving package authors a runnable template for reacting to pm mutations when project management is context management. `--capability search` keeps the starter command and adds a deterministic search provider/vector-store adapter pair plus SDK tests with `assertRegisteredSearchProvider`, `assertRegisteredVectorStoreAdapter`, `runRegisteredSearchProviderForTest`, and `runRegisteredVectorStoreAdapterForTest`, giving retrieval packages a copyable context-management primitive without external services. `--capability importers` keeps the starter command and adds paired import/export command registrations plus SDK tests with `assertRegisteredImporter`, `assertRegisteredExporter`, `runRegisteredImporterForTest`, and `runRegisteredExporterForTest`, giving integration packages a copyable context-movement primitive for synchronizing external project systems; the generated manifest declares both `importers` and `schema` because the starter includes schema-governed flag metadata. Starter manifests use the same least-privilege policy metadata as pure first-party command packages: `trusted: true`, `sandbox_profile: "strict"`, and explicit `false` permissions for `fs_read`, `fs_write`, `network`, `env_read`, `env_write`, and `process_spawn`. Larger packages may point at nested extension directories after declaring runtime dependencies, relaxing only the permissions they actually need, and validating with `pm package doctor`.
+`pm package init` emits a root extension (`"extensions": ["."]`) authored **and loaded** as TypeScript (ADR [pm-2c28](../.agents/pm/decisions/pm-2c28.toon) / [pm-m1uz](../.agents/pm/decisions/pm-m1uz.toon)): a typed `index.ts`, a strict type-check-only `tsconfig.json`, and `typecheck`/`test` scripts, with the manifest `entry` pointing at `./index.ts` itself. pm loads that `.ts` entry directly via Node's native type stripping (Node >=22.18), so there is no build step — run `npm install` (for the peer SDK and type-checking) before `pm install`. The generated README shows how to author exported command/hook definitions with the SDK [define* builders](../.agents/pm/decisions/pm-3mph.toon). The default `--capability commands` scaffold registers a starter command and a colocated `node:test` suite. `--capability hooks` keeps the starter command and adds an `after_command` lifecycle hook plus SDK testing coverage with `assertRegisteredHook` and `runRegisteredHookForTest`, giving package authors a runnable template for reacting to pm mutations when project management is context management. `--capability search` keeps the starter command and adds a deterministic search provider/vector-store adapter pair plus SDK tests with `assertRegisteredSearchProvider`, `assertRegisteredVectorStoreAdapter`, `runRegisteredSearchProviderForTest`, and `runRegisteredVectorStoreAdapterForTest`, giving retrieval packages a copyable context-management primitive without external services. `--capability importers` keeps the starter command and adds paired import/export command registrations plus SDK tests with `assertRegisteredImporter`, `assertRegisteredExporter`, `runRegisteredImporterForTest`, and `runRegisteredExporterForTest`, giving integration packages a copyable context-movement primitive for synchronizing external project systems; the generated manifest declares both `importers` and `schema` because the starter includes schema-governed flag metadata. `--capability schema` keeps the starter command and registers a custom item type, item field, and migration via `api.registerItemTypes`, `api.registerItemFields`, and `api.registerMigration`, with SDK tests using `assertRegisteredItemType`, `assertRegisteredItemField`, `assertRegisteredMigration`, and `runRegisteredMigrationForTest`; it deliberately omits `activation.commands` because a custom item type is a global contribution that built-in commands (`pm create <type>`, `pm list`, `pm validate`) must see, so pm activates it conservatively for every command. `--capability profile` keeps the starter command and registers a complete project-profile archetype — item types, custom statuses, fields, a per-type workflow, config knobs, a create template, and package recommendations — via `api.registerProfile`, with an SDK test using the harness-bound `assertProfile` (the public `assertRegisteredProfile`); like the schema starter it omits `activation.commands` because the contributed profile is resolved by the built-in `pm profile list/show/apply` commands (granted by the same `schema` capability, since a profile is a schema+config bundle), so pm activates it conservatively for every command and `pm profile apply <name>` tailors a fresh tracker in one shot. The remaining four capabilities complete the matrix to one starter per SDK registration surface. `--capability renderers` keeps the starter command and adds a `toon` output renderer override via `api.registerRenderer` (scoped to its own command — it returns `null` to pass other output through to pm's default renderer) plus SDK tests with `assertRegisteredRendererOverride` and `runRegisteredRendererOverrideForTest`. `--capability parser` adds a parser override via `api.registerParser` that rewrites the command's parsed options before its handler runs (a deprecated `--shout`→`--upper` alias rewrite); the starter command declares the matching `--shout`/`--upper` flags and surfaces the normalized value so the override is runnable end to end through `pm <command> --shout`, and the manifest also declares `schema` because flag metadata is schema-governed, with SDK tests using `assertRegisteredParserOverride` and `runRegisteredParserOverrideForTest`. `--capability preflight` adds a preflight override via `api.registerPreflight` over pm's pre-run migration/format gate decision (a safe no-op echo by default) plus SDK tests with `assertRegisteredPreflightOverride` and `runRegisteredPreflightOverrideForTest`. `--capability services` overrides the built-in `output_format` service via `api.registerService` (scoped to its own command, passing other commands' output through) plus SDK tests with `assertRegisteredServiceOverride` and `runRegisteredServiceOverrideForTest`. Starter manifests use the same least-privilege policy metadata as pure first-party command packages: `trusted: true`, `sandbox_profile: "strict"`, and explicit `false` permissions for `fs_read`, `fs_write`, `network`, `env_read`, `env_write`, and `process_spawn`. Larger packages may point at nested extension directories after declaring runtime dependencies, relaxing only the permissions they actually need, and validating with `pm package doctor`, which additionally emits the advisory `extension_schema_narrow_activation` warning when a package registers custom item types/fields yet declares narrow `activation.commands` (the schema footgun above), recommending the field be dropped so the type stays globally available.
 
 Package tests can pair `readPmPackageManifest(packageRoot)` with
 `assertPackageManifest(manifest, { resources: ... })` from
@@ -112,13 +111,13 @@ Runtime path overrides:
 - `PM_PATH`: project tracker root
 - `PM_GLOBAL_PATH`: global profile root
 
-Extensions are authored fully in TypeScript (ADR [pm-2c28](../.agents/pm/decisions/pm-2c28.toon)): a minimal standalone extension has a `manifest.json` and a TypeScript `index.ts` entrypoint compiled to the `./index.js` the loader imports by file URL. Author against the SDK types with `import type { ExtensionApi }` — the type-only import is erased at compile time, so the emitted `index.js` carries **no runtime import** of `@unbrained/pm-cli` (standalone entries are loaded outside any `node_modules`, so a runtime SDK import would fail). Compile with `npx tsc` after installing `typescript` and `@unbrained/pm-cli` for the type resolution.
+Extensions are authored **and loaded** as TypeScript (ADR [pm-2c28](../.agents/pm/decisions/pm-2c28.toon) / [pm-m1uz](../.agents/pm/decisions/pm-m1uz.toon)): a minimal standalone extension has a `manifest.json` and a TypeScript `index.ts` entrypoint the loader imports directly by file URL via Node's native type stripping (Node >=22.18) — there is no compile step and no `./index.js`. Author against the SDK types with `import type { ExtensionApi }` — the type-only import is erased on load, so the `.ts` entry carries **no runtime import** of `@unbrained/pm-cli` (standalone entries are loaded outside any `node_modules`, so a runtime SDK import would fail). Type-check with `npx tsc --noEmit` after installing `typescript` and `@unbrained/pm-cli` for the type resolution.
 
 ```json
 {
   "name": "hello",
   "version": "0.1.0",
-  "entry": "./index.js",
+  "entry": "./index.ts",
   "manifest_version": 1,
   "pm_min_version": "2026.5.0",
   "pm_max_version": "2027.0.0",
@@ -137,7 +136,7 @@ Extensions are authored fully in TypeScript (ADR [pm-2c28](../.agents/pm/decisio
 ```
 
 ```ts
-// index.ts — `import type` is erased at compile; the emitted index.js has no runtime import.
+// index.ts — the manifest entry; `import type` is erased on load (native type stripping), so it has no runtime import.
 import type { ExtensionApi } from "@unbrained/pm-cli/sdk";
 export function activate(api: ExtensionApi): void {
   api.registerCommand({
@@ -201,8 +200,8 @@ Rules:
 - An empty-string or non-string `pm_min_version`/`pm_max_version` makes the whole manifest malformed (`extension_manifest_invalid:<layer>:<name>`). Omit the field instead of leaving it blank.
 - Optional `engines.pm` and `engines.node` metadata is accepted for tooling, but `pm_min_version`/`pm_max_version` are the loader-enforced compatibility fields.
 - Declare only capabilities the extension actually uses. Declaring a capability it never registers against is over-broad: `pm package doctor` emits an advisory `extension_capability_unused:<layer>:<name>:<capability>` warning (never blocking) so you can trim the manifest, while the inverse — registering a surface whose capability is undeclared — is the blocking `extension_capability_missing` activation failure. Catch over-declaration earlier with the `assertExtensionCapabilityUsage` SDK testing helper.
-- Unknown capabilities emit deterministic warnings.
-- Legacy aliases such as `migration` and `validation` are normalized to `schema` with warnings.
+- `activation.commands` is an optional array of the command paths the extension registers (e.g. `["hello", "tickets import"]`). pm uses it to activate the extension lazily — importing and running `activate` only when an invoked command matches — so declaring it (every first-party package and `pm package init` scaffold does) keeps the extension's own commands dispatchable while unrelated commands skip the import. Omit it and pm falls back to capability heuristics, which cannot enumerate the contributed commands. Globally-scoped surfaces (hooks, parser/preflight/renderer overrides, and search providers for built-in search commands) activate regardless of this list.
+- Unknown capabilities emit deterministic warnings; legacy aliases such as `migration` and `validation` are normalized to `schema` with warnings.
 
 Supported capabilities:
 
@@ -223,6 +222,7 @@ First-party package exemplars:
 - `pm-command-kit`: command capability exemplar for `registerCommand`, `registerFlags`, and `registerParser`.
 - `pm-governance-audit`: governance hook exemplar for compact read/write sidecar logs.
 - `pm-guide-shell`: guide-topic package for bundled workflow docs.
+- `pm-kanban`: archetype exemplar shipping a complete Kanban continuous-flow profile (Card type, flow fields, and a `ProjectProfileDefinition`) on public SDK primitives.
 - `pm-lifecycle-hooks`: default-inert lifecycle hook registration.
 - `pm-linked-test-adapters`: linked-test run-management adapters and reporters.
 - `pm-search-advanced`: deterministic local search provider registration.
@@ -300,12 +300,11 @@ Common APIs:
 - `api.registerItemFields(fields)` adds custom metadata fields. Agents can set declared fields with repeatable `pm create --field name=value` and `pm update <id> --field name=value`; undeclared names are rejected. Each field `type` is validated against `string | number | boolean | array | object` at activation, with a did-you-mean hint on typos.
 - `api.registerItemTypes(types)` adds custom item types.
 - `api.registerMigration(definition)` adds schema migrations.
+- `api.registerProfile(profile)` contributes a project profile — a declarative archetype bundling item types, statuses, fields, per-type workflows, config, templates, and package recommendations. Once active it resolves by name through `pm profile list/show/apply` alongside the core `agile`/`ops`/`research` archetypes (built-in names are reserved; a colliding registration is ignored with a warning). Requires the `schema` capability.
 - `api.registerService("output_format", handler)` customizes output formatting through the service override API. Return `context.payload`, `null`, or `undefined` for commands the extension does not own.
 - `api.registerRenderer("toon" | "json", renderer)` adds format-specific renderers. Return `null` for unrelated payloads so pm falls back to native rendering.
 - `api.hooks.beforeCommand(handler)`, `api.hooks.afterCommand(handler)`, `api.hooks.onWrite(handler)`, `api.hooks.onRead(handler)`, and `api.hooks.onIndex(handler)` add lifecycle hooks.
-  `afterCommand` receives command outcome fields plus optional compact `affected`
-  item entries for mutations, including `previous_status`, `status`,
-  `changed_fields`, and partial `previous`/`current` front matter snapshots.
+  `afterCommand` receives command outcome fields plus optional compact `affected` item entries for mutations, including `previous_status`, `status`, `changed_fields`, and partial `previous`/`current` front matter snapshots.
   `onWrite` always includes `path`, `scope`, and `op`; item mutations also add optional `item_id`, `item_type`, `before`, `after`, and `changed_fields`.
 - An optional module-level `deactivate()` export (VS Code-style) is invoked by the host on shutdown/reload — including by the long-running MCP server between native-action requests — to close connections, clear timers, and release resources opened during `activate`. Teardown is best-effort and timeout-bounded by default so it does not block other extensions, except when a host explicitly disables waiting limits with `deactivate_timeout_ms: 0` or `Infinity`, which can wait indefinitely for a hanging `deactivate()` hook.
 
@@ -339,8 +338,8 @@ Explore installed runtime entries, or describe exactly what each loaded package
 
 ```bash
 pm package explore --project
-pm package describe --project          # every loaded package
-pm package describe my-extension       # one package's surface map
+pm package describe --project                 # surface map of every loaded package
+pm package describe my-extension --markdown --output docs/my-extension-reference.md
 ```
 
 Run diagnostics:

package/docs/RELEASING.md

@@ -36,6 +36,7 @@ pnpm version:check
 ## One-Time Setup
 
 - Use npm provenance publishing for `.github/workflows/release.yml` so GitHub-hosted release jobs publish signed packages. Keep `id-token: write`, Node 24 or newer, npm 11.5.1 or newer, `NODE_AUTH_TOKEN` from the `release` environment `NPM_TOKEN` secret, and `npm publish --access public --provenance`. The token must authenticate as a maintainer with read-write access to `@unbrained/pm-cli`.
+- Add `RELEASE_PAT` to the `release` environment from a maintainer token with `contents:write` and branch-protection bypass rights. Auto Release creates a checked version/changelog commit and tag on `main`; the default `GITHUB_TOKEN` has `contents:write` but cannot satisfy protected-branch required status checks for that freshly-created commit. The workflow does not persist this elevated token during checkout or dependency installation; `run-release-pipeline.mjs` scopes it to the git push process.
 - Add `SENTRY_AUTH_TOKEN` as an optional GitHub Environment or repository secret when Sentry release creation and sourcemap upload should run. Add `SENTRY_PERSONAL_ADMIN_TOKEN` for the GitHub-hosted Sentry issue-threshold gate; CI-scoped release tokens may not have issue-read scope. The release workflow skips Sentry upload cleanly when `SENTRY_AUTH_TOKEN` is absent, but fails the reliability threshold gate when `SENTRY_PERSONAL_ADMIN_TOKEN` is absent; local maintainers should still run the token-backed Sentry gate before release.
 - Keep any `release` environment compatible with free GitHub features. This repository is public, so environment secrets and tag/branch deployment rules are compatible with the free GitHub path; do not add paid-only release gates.
 - Ensure `GITHUB_TOKEN` has `contents: write` for GitHub Release creation.
@@ -54,8 +55,11 @@ Policy:
 - same-day follow-up release (`YYYY.M.D-N`) is manual-only via `allow_same_day_release=true`
 - release preparation must pass all quality and compatibility gates before commit+tag push
 - `CHANGELOG.md` is generated by the latest npm `pm-changelog` package (`pm install npm:pm-changelog --project`, then `pm changelog generate --mode replace --all-release-tags`) from closed tracker items across git release tag windows and checked in CI; do not edit it by hand
+- protected-branch pushes require `RELEASE_PAT`; Auto Release fails fast before the expensive release gates when `push=true`, `dry_run=false`, and that secret is not configured
 - release reliability gating requires `SENTRY_PERSONAL_ADMIN_TOKEN` for issue-threshold checks; Auto Release fails before creating the version commit/tag when the token is missing and `push=true`, while sourcemap upload remains optional through `SENTRY_AUTH_TOKEN`
 - after creating and pushing a new tag, auto-release dispatches `.github/workflows/release.yml` with that tag and waits for the publish workflow to finish, because GitHub does not start normal push/tag workflows from `GITHUB_TOKEN` pushes
+- scheduled failure issues include the preflight state (`push`, `dry_run`, `release_pat_configured`, and `sentry_personal_admin_token_configured`) plus a detected cause so agents can distinguish missing release secrets from Sentry gate failures without scanning the full workflow log first
+- after a scheduled run publishes a tag and the downstream release workflow succeeds, auto-release closes any open `Auto Release blocked` issue so the GitHub tracker reflects current release health
 
 Pipeline entrypoint:
 
@@ -164,7 +168,7 @@ git push origin v<version>
 - version policy and tag guard
 - secret scan
 - build, typecheck, test, and coverage
-- static quality gate (complexity, duplication, dead/orphan module, file/folder hygiene)
+- static quality gate (shared complexity, duplication, dead/orphan module, file/folder hygiene, source/exported docstring coverage profile)
 - temporary-project compatibility gate against latest published tracker data
 - reliability threshold gate (Sentry severity threshold, bounded to a recent-activity window via `--sentry-window-days` (default `14`, `0` = unbounded) so a stale benign unresolved issue cannot block every scheduled release; `--telemetry-mode` gate policy: `off` | `best-effort` | `required`). Scheduled `auto-release.yml` failures open/update an `Auto Release blocked` GitHub issue so blocked daily releases are never silently skipped.
 - sandboxed `pm` coverage
@@ -202,6 +206,7 @@ Use the npm registry package for maintainer global updates. Do not use `npm inst
 
 - If local gates fail, fix and rerun before tagging.
 - Treat failed scheduled Nightly Validation jobs as release-health blockers until triaged. The nightly workflow opens or updates a GitHub issue for each failing scheduled OS/Node matrix entry, with the run URL and commit SHA, so cross-platform regressions do not rely on someone manually scanning the Actions tab.
+- Treat a green manual Auto Release dry-run (`push=false` or `dry_run=true`) as gate confidence only. It does not prove the protected-branch publish path; scheduled production runs still require `RELEASE_PAT` and `SENTRY_PERSONAL_ADMIN_TOKEN` to be configured in the `release` environment.
 - If the tag workflow fails before npm publish, confirm no package was published before moving or replacing a tag.
 - If npm publish succeeds but GitHub Release creation fails, rerun `.github/workflows/release.yml` with `workflow_dispatch` and `tag=v<version>`; the workflow skips duplicate npm publish, reruns public verification, and creates the GitHub Release for the existing tag.
 - Record failure evidence and remediation in the release `pm` item.

package/docs/SDK.md

@@ -41,6 +41,7 @@ Common authoring exports:
 - `composeExtensionPackage` (author-once capstone: returns both the module and its synthesized manifest)
 - `synthesizeExtensionManifest` (generate a complete least-privilege manifest from a blueprint)
 - `describeExtensionBlueprint` (static surface map of a blueprint) / `lintExtensionBlueprint` (author-time preflight)
+- `renderExtensionSurfaceMarkdown` (render a describe summary to a drift-free Markdown reference doc for a package README)
 - `checkExtensionManifestCompatibility` (author-time `pm_min_version`/`pm_max_version` check against a target pm version)
 - `preflightExtension` (one-call capstone: lint + manifest synthesis + version-compat in a single consolidated report)
 - `EXTENSION_CAPABILITIES`
@@ -58,11 +59,29 @@ Common authoring exports:
 Registration builders (`define*`, zero-cost identity — see [Authoring Builders](#authoring-builders)):
 
 - `defineCommand` / `defineFlag` / `defineItemType` / `defineItemField` / `defineMigration`
+- `defineProjectProfile` (archetype bundle of types/statuses/fields/workflows/config/templates/packages — powers `pm profile`)
 - `defineSearchProvider` / `defineVectorStoreAdapter`
 - `defineCommandOverride` / `defineParserOverride` / `definePreflightOverride` / `defineServiceOverride` / `defineRendererOverride`
 - `defineImporter` / `defineExporter`
 - `defineBeforeCommandHook` / `defineAfterCommandHook` / `defineOnWriteHook` / `defineOnReadHook` / `defineOnIndexHook`
 
+Project profiles:
+
+- `defineProjectProfile` / `BUILTIN_PROFILES` / `PROFILE_NAMES` / `resolveProfile` / `listProfiles` / `normalizeProfileName`
+- `describeProjectProfile` (pure composition summary — per-dimension counts plus resolved entry identifiers; the project-profile analogue of `describeExtensionBlueprint`) and `describeProfileComposition`
+- `lintProjectProfile` (pure, tracker-independent author-time consistency check that grades findings `error`/`warning` across every dimension — invalid/duplicate types, statuses, fields; workflows governing undeclared types or referencing undeclared statuses; unknown/invalid config knobs; templates creating undeclared types; empty package specs) and its `ProjectProfileLintReport` / `ProjectProfileLintFinding` types
+- `assertProjectProfile` (the throwing test counterpart: fails on any `error` finding, or on warnings too with `{ strict: true }` — the profile analogue of `assertExtensionBlueprint`)
+- `planProfileApplication` (pure, idempotent diff of a profile against the current tracker state) and its `ProfileApplicationPlan` / `ProfileCurrentState` types
+- The bundled [pm-kanban exemplar](../packages/pm-kanban/README.md) ships a complete archetype as an installable package: it registers the live schema (`Card` type + flow fields) and exports a `ProjectProfileDefinition` the planner can stage, all on public SDK primitives.
+
+Author-time lifecycle: `defineProjectProfile` → `lintProjectProfile` / `assertProjectProfile` (validate before registering) → `api.registerProfile` → `describeProjectProfile` / `planProfileApplication` (preview) → `pm profile apply`. Validate a profile in a package test before it ships:
+
+```ts
+import { assertProjectProfile } from "@unbrained/pm-cli/sdk/testing";
+
+assertProjectProfile(kanbanProfile); // throws on any error finding
+```
+
 Package manifest exports:
 
 - `PM_PACKAGE_RESOURCE_KINDS` (`extensions`, `docs`, `examples`, `assets`, `prompts`)
@@ -118,6 +137,7 @@ Testing helper exports (also under `@unbrained/pm-cli/sdk/testing`):
 - `assertRegisteredVectorStoreAdapter`
 - `assertRegisteredItemField`
 - `assertRegisteredItemType`
+- `assertRegisteredProfile`
 - `assertRegisteredServiceOverride`
 - `assertRegisteredMigration`
 - `assertExtensionCapabilityUsage`
@@ -127,6 +147,7 @@ Testing helper exports (also under `@unbrained/pm-cli/sdk/testing`):
 - `assertExtensionPreflight` (one-line throwing capstone over `preflightExtension`; replaces chaining the three asserts above)
 - `describeExtensionActivation`
 - `describeExtensionBlueprint` / `lintExtensionBlueprint` (also surfaced here for the full author → describe → preflight → test loop)
+- `renderExtensionSurfaceMarkdown` (render the describe summary to a drift-free Markdown reference; powers `describe --markdown`)
 
 `createExtensionTestHarness(module, options)` is the recommended entry point and
 the ergonomic capstone over every standalone helper below: it activates the
@@ -137,8 +158,13 @@ never threads `activation.registrations` vs `activation.commands` vs
 surfaces as a confusing `available: (none)` error. Write
 `const ext = await createExtensionTestHarness(module, { capabilities: ["commands"] })`,
 then `ext.assertCommandContract({ command })`, `await ext.runCommand({ command })`,
-and `await ext.deactivate()`. The methods do not use `this`, so they remain safe
-to destructure (`const { runCommand } = ext;`), and the raw `ext.activation`
+`ext.activationSummary()`, `ext.renderMarkdown({ title: "My package" })`, and
+`await ext.deactivate()`. `activationSummary()` returns the same
+`ExtensionActivationSummary` as `describeExtensionActivation(ext.activation)`;
+`renderMarkdown()` feeds that summary through `renderExtensionSurfaceMarkdown`,
+with an optional `extensionName` filter for scoped package docs. The methods do
+not use `this`, so they remain safe to destructure
+(`const { runCommand, renderMarkdown } = ext;`), and the raw `ext.activation`
 stays public as an escape hatch to the standalone helpers for any surface a
 convenience method does not cover.
 
@@ -289,6 +315,33 @@ to "what does this installed package add to my context?" — distinct from
 `pm package doctor` (errors/policy) and `pm package manage` (update metadata), which
 report only command/action paths, not the full registration surface.
 
+`renderExtensionSurfaceMarkdown(summary, options?)` is the **render** leg of the
+describe verb: it projects any `ExtensionActivationSummary` to a deterministic
+Markdown reference document — a title heading, a one-line capabilities summary,
+and a section per registered surface. Pipe `describeExtensionBlueprint(blueprint)`
+straight into it during a build or test step and embed the result in your
+README, and the "commands & capabilities" reference can never drift from the
+surface the loader actually registers ("project management = context
+management"). `options.title` / `options.headingLevel` (an integer in `[1, 6]`,
+default `2`; section headings render one level deeper) control nesting, and
+`options.includeEmpty` renders every section (as `_None._`) rather than omitting
+empty ones.
+
+```ts
+import { describeExtensionBlueprint, renderExtensionSurfaceMarkdown } from "@unbrained/pm-cli/sdk";
+
+const reference = renderExtensionSurfaceMarkdown(describeExtensionBlueprint(blueprint), { title: "my-pkg", headingLevel: 2 });
+// → "## my-pkg\n\nCapabilities: `commands`, `schema`\n\n### Commands\n\n- `greet hello`\n…"
+```
+
+The same renderer powers `pm extension describe --markdown` / `pm package
+describe --markdown`, which compose a per-extension section plus a union section
+across every loaded extension. Add `--output docs/package-reference.md` to write
+the generated Markdown directly to a file for README/reference-doc refreshes.
+`--markdown` is a presentation format (it cannot be combined with `--json`);
+MCP `describe` keeps returning the structured summary, which a caller can hand to
+`renderExtensionSurfaceMarkdown` itself.
+
 Commander option contract exports:
 
 - `CREATE_COMMANDER_OPTION_REGISTRATION_CONTRACTS`
@@ -413,6 +466,8 @@ const ext = await createExtensionTestHarness(extensionModule, { capabilities: ["
 ext.assertCommandContract({ command: "incident triage", flags: ["--severity"] });
 ext.assertFlags({ targetCommand: "list", flags: ["--incident-filter"] });
 const { result } = await ext.runCommand({ command: "incident triage", options: { severity: "high" } });
+const summary = ext.activationSummary();
+const reference = ext.renderMarkdown({ title: "incident package surfaces" });
 await ext.deactivate();
 ```
 
@@ -428,6 +483,7 @@ For provider-safe schemas, use `PM_PROVIDER_TOOL_PARAMETERS_SCHEMA`. It is flat
 | `registerItemFields` | `schema` |
 | `registerItemTypes` | `schema` |
 | `registerMigration` | `schema` |
+| `registerProfile` | `schema` |
 | `registerImporter` | `importers` |
 | `registerExporter` | `importers` |
 | `registerParser` | `parser` |
@@ -478,7 +534,7 @@ Manifest:
 {
   "name": "hello",
   "version": "0.1.0",
-  "entry": "./index.js",
+  "entry": "./index.ts",
   "pm_min_version": "2026.5.31",
   "trusted": true,
   "sandbox_profile": "strict",
@@ -502,7 +558,7 @@ Manifest typing also accepts optional `engines` metadata:
 {
   "engines": {
     "pm": ">=2026.5.31",
-    "node": ">=20"
+    "node": ">=22.18"
   }
 }
 ```
@@ -527,7 +583,59 @@ scaffold paired import/export commands with example flag metadata and a runnable
 `node:test` file that exercises `assertRegisteredImporter`,
 `assertRegisteredExporter`, `runRegisteredImporterForTest`, and
 `runRegisteredExporterForTest`; the generated manifest declares both `importers`
-and `schema` because extension flag metadata is schema-governed.
+and `schema` because extension flag metadata is schema-governed. Pass
+`--capability schema` to scaffold a command plus a custom item type, item field,
+and migration (via `registerItemTypes`/`registerItemFields`/`registerMigration`)
+and a runnable `node:test` file that exercises `assertRegisteredItemType`,
+`assertRegisteredItemField`, `assertRegisteredMigration`, and
+`runRegisteredMigrationForTest` — a copyable starting point for modeling a
+project domain. Pass `--capability profile` to scaffold a command plus a complete
+project-profile archetype (item types, statuses, fields, a per-type workflow,
+config, a create template, and package recommendations via `registerProfile`) and
+a `node:test` file exercising the harness-bound `assertProfile` (the public
+`assertRegisteredProfile`); it omits
+`activation.commands` (granted by the same `schema` capability) so the contributed
+profile resolves through `pm profile list/show/apply` and `pm profile apply <name>`
+tailors a fresh tracker in one shot — the broadest customization primitive in one
+copyable starter.
+
+The four override surfaces complete the matrix to one starter per SDK
+registration capability. Pass `--capability renderers` to scaffold a `toon`
+output renderer override (via `registerRenderer`, scoped to its own command so
+other output passes through) with a `node:test` file exercising
+`assertRegisteredRendererOverride` and `runRegisteredRendererOverrideForTest`;
+`--capability parser` for a parser override (via `registerParser`) that rewrites
+the command's parsed options — the starter command declares matching
+`--shout`/`--upper` flags (so the manifest also declares `schema`) and surfaces
+the normalized value, making the override runnable through `pm <command> --shout`
+— exercising `assertRegisteredParserOverride` and
+`runRegisteredParserOverrideForTest`; `--capability preflight` for a preflight
+override (via `registerPreflight`) over pm's pre-run migration/format gate
+decision, exercising `assertRegisteredPreflightOverride` and
+`runRegisteredPreflightOverrideForTest`; and `--capability services` for an
+`output_format` service override (via `registerService`, scoped to its own
+command), exercising `assertRegisteredServiceOverride` and
+`runRegisteredServiceOverrideForTest`.
+
+Every command-bearing variant's generated `manifest.json` also declares
+`activation.commands` — the exact command paths the starter registers — so pm
+activates the package lazily, importing and running `activate` only when an
+invoked command matches. This mirrors every first-party bundled package and is
+the contract authors keep in sync with their registrations: an omitted or stale
+entry means the matching command will not dispatch from the CLI (globally-scoped
+surfaces such as hooks and search providers for built-in search commands still
+activate regardless). The `schema` starter is the deliberate exception: it omits
+`activation.commands` so its custom item type — a global contribution that
+built-in commands like `pm create <type>` must see — activates conservatively for
+every command rather than gating on the package's own commands.
+
+Each `--capability` starter authors an imperative `activate` body. To scaffold the
+declarative `composeExtension` form instead, pass `--declarative` to
+`pm package init` / `pm package scaffold` (it is an init/scaffold flag, package-mode
+only — every `--capability` variant emits its blueprint form, since `composeExtension`
+is a runtime SDK value import that only package-mode authoring links) — see
+[Declarative Authoring](#declarative-authoring). See [EXTENSIONS.md](EXTENSIONS.md)
+for the manifest-field reference.
 
 ## Self-Identity and Lifecycle
 
@@ -645,8 +753,8 @@ argument unchanged), exactly like `defineExtension` and the wider
 `defineConfig`/`defineComponent` ecosystem convention — the value is entirely at
 the type level.
 
-pm packages are authored fully in TypeScript (ADR
-[pm-2c28](../.agents/pm/decisions/pm-2c28.toon)). A bare `const cmd = { ... }`
+pm packages are authored **and loaded** as TypeScript (ADR
+[pm-2c28](../.agents/pm/decisions/pm-2c28.toon) / [pm-m1uz](../.agents/pm/decisions/pm-m1uz.toon)). A bare `const cmd = { ... }`
 satisfies the registration types only structurally and widens its literals;
 wrapping it in a builder checks the object against the contract *and* preserves
 the narrow literal types, while inferring the nested handler's `context`
@@ -750,6 +858,16 @@ malformed definition surfaces the same activation diagnostic as a hand-written
 hand-written `activate` bodies so they load in extension-only installs; reach for
 `composeExtension` in npm package-mode authoring where the SDK is a dependency.
 
+For a generated starting point, `pm package init <path> --declarative` scaffolds
+this loop end to end for any `--capability`: an `index.ts` that authors a
+`defineExtensionBlueprint` blueprint (the capability's surfaces wired through the
+`define*` builders) and exports `composeExtension(blueprint)`, plus an
+`index.test.ts` that guards it with the author-time `assertExtensionPreflight`
+capstone and exercises the composed module through `createExtensionTestHarness`. It
+is package-mode only (`composeExtension` is a runtime SDK value import, so it belongs
+in package-mode authoring where the SDK is a linked dependency, not the import-free
+extension-only starters).
+
 ### Modular blueprints
 
 Tracked: [pm-high](../.agents/pm/tasks/pm-high.toon),
@@ -772,10 +890,10 @@ export const commandsModule = defineExtensionBlueprint({
 ```
 
 ```ts
-// index.ts — NodeNext import specifiers keep the .js extension; they resolve to the .ts source.
+// index.ts — the manifest entry; import sibling .ts modules by their real extension (loaded directly via native type stripping).
 import { composeExtension, mergeExtensionBlueprints } from "@unbrained/pm-cli/sdk";
-import { commandsModule } from "./commands.js";
-import { searchModule } from "./search.js";
+import { commandsModule } from "./commands.ts";
+import { searchModule } from "./search.ts";
 
 export default composeExtension(mergeExtensionBlueprints(commandsModule, searchModule));
 ```
@@ -813,7 +931,7 @@ import { synthesizeExtensionManifest } from "@unbrained/pm-cli/sdk";
 const manifest = synthesizeExtensionManifest(blueprint, {
   name: "command-kit",
   version: "1.0.0",
-  entry: "./index.js",
+  entry: "./index.ts",
   priority: 0,
 });
 manifest.capabilities; // ["commands", "parser", "schema"] — derived, not hand-written
@@ -844,7 +962,7 @@ import { composeExtensionPackage } from "@unbrained/pm-cli/sdk";
 const { module, manifest } = composeExtensionPackage(blueprint, {
   name: "command-kit",
   version: "1.0.0",
-  entry: "./index.js",
+  entry: "./index.ts",
   priority: 0,
 });
 export default module;          // the package entry's default export
@@ -913,7 +1031,7 @@ const activation = await activateExtensionForTest({
   manifest: {
     name: "hello-ext",
     version: "0.1.0",
-    entry: "./index.js",
+    entry: "./index.ts",
     priority: 0,
     capabilities: ["commands", "schema"],
   },
@@ -1024,14 +1142,14 @@ import { assertExtensionPreflight } from "@unbrained/pm-cli/sdk/testing";
 
 // Inspect every author-time stage in one report…
 const report = preflightExtension(blueprint, {
-  identity: { name: "command-kit", version: "1.0.0", entry: "./index.js", priority: 0 },
+  identity: { name: "command-kit", version: "1.0.0", entry: "./index.ts", priority: 0 },
   target: { pmVersion: "2026.6.23" },
 });
 //   report.manifest.capabilities (derived), report.compatibility.compatible, report.findings[]
 
 // …or guard the whole package in one CI line.
 assertExtensionPreflight(blueprint, {
-  identity: { name: "command-kit", version: "1.0.0", entry: "./index.js", priority: 0 },
+  identity: { name: "command-kit", version: "1.0.0", entry: "./index.ts", priority: 0 },
   target: { pmVersion: "2026.6.23" },
 });
 ```
@@ -1234,9 +1352,58 @@ const migration = assertRegisteredMigration(activation.registrations, {
 // migration.definition is the normalized SchemaMigrationDefinition
 ```
 
+### Project profiles (`registerProfile`)
+
+Tracked: [pm-08sv](../.agents/pm/features/pm-08sv.toon).
+
+A **project profile** is the broadest customization primitive a package can ship:
+one declarative `ProjectProfileDefinition` that bundles item types, custom
+statuses, fields, per-type workflows, config knobs, create templates, and package
+recommendations into a single archetype `pm profile apply` stages idempotently.
+The three core archetypes (`agile`/`ops`/`research`) are baked in; a package adds
+its own with `api.registerProfile(profile)` under the `schema` capability:
+
+```ts
+import { defineProjectProfile, type ExtensionApi } from "@unbrained/pm-cli/sdk";
+
+export const kanbanProfile = defineProjectProfile({
+  name: "kanban",
+  title: "Kanban continuous flow",
+  summary: "WIP-limited flow with a verifying stage.",
+  types: [{ name: "Card", folder: "cards" }],
+  statuses: [{ id: "doing", roles: ["active"] }],
+  fields: [{ key: "wip_limit", type: "number", commands: ["create", "update"] }],
+  workflows: [{ type: "Card", allowed_transitions: [["open", "doing"]] }],
+  config: [{ key: "search_provider", value: "bm25", summary: "Offline lexical search." }],
+  templates: [{ name: "card", options: { type: "Card" } }],
+  packages: [{ spec: "templates", reason: "Reusable card shapes." }],
+});
+
+export function activate(api: ExtensionApi): void {
+  api.registerProfile(kanbanProfile);
+}
+```
+
+Once the package is active, the profile resolves by name through `pm profile list`
+(labelled with its source package), `pm profile show <name>`, and
+`pm profile apply <name>` — exactly like a core archetype, with no consumer code.
+Built-in names are reserved: a registered profile that collides with a core name
+(or another package's profile) is ignored with a warning rather than shadowing it.
+Profiles flow through the declarative loop too — `composeExtension({ profiles: [...] })`
+auto-wires `registerProfile`, and `deriveExtensionCapabilities` maps a `profiles`
+surface to `schema`. Prove a profile registered with `assertRegisteredProfile`:
+
+```ts
+import { assertRegisteredProfile } from "@unbrained/pm-cli/sdk/testing";
+
+const { profile } = assertRegisteredProfile(activation.registrations, { profile: "kanban" });
+// profile is the normalized ProjectProfileDefinition
+```
+
 Together these complete the SDK assertion surface: every extension `register*`
-method now has a matching `assertRegistered*` helper, so packages can prove any
-registration without importing private registry internals.
+method (including `registerProfile`) now has a matching `assertRegistered*`
+helper, so packages can prove any registration without importing private registry
+internals.
 
 The three executable registration surfaces add `runRegistered*ForTest` invoke
 helpers on top of those assertions, so a package can exercise the real behavior of

package/docs/TESTING.md

@@ -20,6 +20,7 @@ Tracked documentation work: [pm-u9d0](../.agents/pm/epics/pm-u9d0.toon).
 
 ```bash
 pnpm build
+pnpm lint
 pnpm typecheck
 node scripts/run-tests.mjs test
 node scripts/run-tests.mjs coverage
@@ -27,6 +28,17 @@ node scripts/run-tests.mjs coverage
 
 `node scripts/run-tests.mjs` wraps Vitest in temporary tracker roots, then cleans them up.
 
+`pnpm lint` is the local CodeFactor parity check. It layers ESLint rules for
+shipped source, package, plugin, and script surfaces that match the CodeFactor
+maintainability findings this repo tracks (`complexity`,
+`no-unsafe-optional-chaining`, and the relevant `eslint-plugin-unicorn`
+mechanical rules), jscpd duplicate detection across source and tests, and the
+repo-specific `quality:static` gate. The dedicated `quality:static` gate remains
+authoritative for source/exported docstring coverage, orphan-module checks,
+directory-load caps, and the TypeScript-aware duplicate/complexity checks that
+are tailored to pm's source layout; `pnpm lint` delegates to it instead of
+running a second threshold profile.
+
 ## Focused Test Runs
 
 ```bash