@unbrained/pm-cli 2026.9.4 → 2026.9.6

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

@@ -7,7 +7,8 @@ import {
   EXIT_CODE,
   PmCliError,
   isTerminalStatus,
-  normalizeStatusInput,
+  SETTINGS_DEFAULTS,
+  parseStatusFilterCsv,
   normalizeSimilarityText,
   nowIso,
   readSettings,
@@ -46,6 +47,8 @@ interface DedupeAuditPreparedCandidate {
   created_at: string;
   updated_at: string;
   normalized_title: string;
+  /** Lifecycle evidence captured from this call's workspace registry. */
+  terminal?: boolean;
 }
 
 /** Documents the dedupe audit candidate payload exchanged by command, SDK, and package integrations. */
@@ -176,8 +179,8 @@ export interface DedupeAuditResult {
   warnings?: string[];
 }
 
+/** Normalize the optional strategy name against the supported audit modes. */
 const parseMode = (raw: string | undefined): DedupeAuditMode => {
-  /** Normalize the optional strategy name against the supported audit modes. */
   const normalized = (raw ?? "title_exact").trim().toLowerCase();
   if (!DEDUPE_AUDIT_MODES.includes(normalized as DedupeAuditMode)) {
     throw new PmCliError(
@@ -188,39 +191,23 @@ const parseMode = (raw: string | undefined): DedupeAuditMode => {
   return normalized as DedupeAuditMode;
 };
 
-let dedupeAllowedStatuses = new Set<string>([
-  "draft",
-  "open",
-  "in_progress",
-  "blocked",
-  "closed",
-  "canceled",
-]);
-let dedupeTerminalStatuses = new Set<string>(["closed", "canceled"]);
-let dedupeStatusRegistry: RuntimeStatusRegistry | null = null;
+const defaultStatusRegistry = resolveRuntimeStatusRegistry(
+  SETTINGS_DEFAULTS.schema,
+);
 
+/** Parse package filters with the host SDK's workflow aliases and all sentinel. */
 const parseStatus = (
   raw: string | undefined,
+  registry: RuntimeStatusRegistry = defaultStatusRegistry,
 ): ItemStatus | "all" | undefined => {
-  /** Normalize an optional status token against the active audit registry. */
-  if (raw === undefined) {
-    return undefined;
-  }
-  const normalized = raw.trim().toLowerCase().replaceAll("-", "_");
-  if (normalized === "all") {
-    return "all";
-  }
-  if (!dedupeAllowedStatuses.has(normalized)) {
-    throw new PmCliError(
-      `Status filter must be one of all|${[...dedupeAllowedStatuses].join("|")}`,
-      EXIT_CODE.USAGE,
-    );
-  }
-  return normalized as ItemStatus;
+  if (raw === undefined) return undefined;
+  return (
+    parseStatusFilterCsv(raw, registry, { strict: true })?.join(",") ?? "all"
+  );
 };
 
+/** Parse an optional fuzzy-match threshold on the inclusive zero-to-one scale. */
 const parseThreshold = (raw: string | undefined): number | undefined => {
-  /** Parse an optional fuzzy-match threshold on the inclusive zero-to-one scale. */
   if (raw === undefined) {
     return undefined;
   }
@@ -234,22 +221,15 @@ const parseThreshold = (raw: string | undefined): number | undefined => {
   return parsed;
 };
 
-const isTerminal = (status: ItemStatus): boolean => {
-  /** Resolve terminality through the active schema with a built-in fallback. */
-  if (dedupeStatusRegistry) {
-    return isTerminalStatus(status, dedupeStatusRegistry);
-  }
-  const normalized = normalizeStatusInput(status) ?? status;
-  return dedupeTerminalStatuses.has(normalized);
-};
-
+/** Rank canonical candidates by lifecycle, priority, recency, and identity. */
 const compareCandidates = (
   left: DedupeAuditPreparedCandidate,
   right: DedupeAuditPreparedCandidate,
 ): number => {
-  /** Rank canonical candidates by lifecycle, priority, recency, and identity. */
-  const leftTerminal = isTerminal(left.status);
-  const rightTerminal = isTerminal(right.status);
+  const leftTerminal =
+    left.terminal ?? isTerminalStatus(left.status, defaultStatusRegistry);
+  const rightTerminal =
+    right.terminal ?? isTerminalStatus(right.status, defaultStatusRegistry);
   if (leftTerminal !== rightTerminal) {
     return leftTerminal ? 1 : -1;
   }
@@ -264,10 +244,10 @@ const compareCandidates = (
   return left.id.localeCompare(right.id);
 };
 
+/** Project one prepared comparison record into the public candidate shape. */
 const toCandidate = (
   candidate: DedupeAuditPreparedCandidate,
 ): DedupeAuditCandidate => {
-  /** Project one prepared comparison record into the public candidate shape. */
   return {
     id: candidate.id,
     title: candidate.title,
@@ -280,12 +260,12 @@ const toCandidate = (
   };
 };
 
+/** Build an executable close recommendation for one duplicate candidate. */
 const toMergeSuggestion = (
   duplicate: DedupeAuditPreparedCandidate,
   canonical: DedupeAuditPreparedCandidate,
   mode: DedupeAuditMode,
 ): DedupeMergeSuggestion => {
-  /** Build an executable close recommendation for one duplicate candidate. */
   const closeReason = `Duplicate of ${canonical.id}`;
   const message = `Close ${duplicate.id} as duplicate of ${canonical.id} from pm dedupe-audit (${mode}).`;
   const escapedReason = closeReason.replaceAll('"', '\\"');
@@ -299,14 +279,15 @@ const toMergeSuggestion = (
   };
 };
 
+/** Score exact normalized titles first, then fall back to token overlap. */
 const similarityScore = (
   left: DedupeAuditPreparedCandidate,
   right: DedupeAuditPreparedCandidate,
 ): number => {
-  /** Score exact normalized titles first, then fall back to token overlap. */
   return scoreItemSimilarity(left.title, right.title).score;
 };
 
+/** Visit each unordered candidate pair exactly once. */
 const forEachCandidatePair = (
   items: DedupeAuditPreparedCandidate[],
   visit: (
@@ -316,7 +297,6 @@ const forEachCandidatePair = (
     rightIndex: number,
   ) => void,
 ): void => {
-  /** Visit each unordered candidate pair exactly once. */
   for (let leftIndex = 0; leftIndex < items.length; leftIndex += 1) {
     for (
       let rightIndex = leftIndex + 1;
@@ -328,15 +308,16 @@ const forEachCandidatePair = (
   }
 };
 
+/** Select one numeric extreme while preserving a deterministic empty fallback. */
 const extremeOrDefault = (
   values: number[],
   select: (...candidates: number[]) => number,
   fallback: number,
 ): number => {
-  /** Select one numeric extreme while preserving a deterministic empty fallback. */
   return values.length === 0 ? fallback : select(...values);
 };
 
+/** Assemble one deterministic cluster and its optional similarity envelope. */
 const clusterFromMembers = (
   mode: DedupeAuditMode,
   key: string,
@@ -344,7 +325,6 @@ const clusterFromMembers = (
   matchReason: string,
   threshold?: number,
 ): DedupeAuditCluster => {
-  /** Assemble one deterministic cluster and its optional similarity envelope. */
   const sortedMembers = [...members].sort(compareCandidates);
   const canonical = sortedMembers[0];
   const duplicates = sortedMembers.slice(1);
@@ -375,11 +355,11 @@ const clusterFromMembers = (
   return cluster;
 };
 
+/** Group candidates by a caller-defined non-empty comparison key. */
 const collectGroupedCandidates = (
   items: DedupeAuditPreparedCandidate[],
   keyFor: (item: DedupeAuditPreparedCandidate) => string | undefined,
 ): Map<string, DedupeAuditPreparedCandidate[]> => {
-  /** Group candidates by a caller-defined non-empty comparison key. */
   const groups = new Map<string, DedupeAuditPreparedCandidate[]>();
   for (const item of items) {
     const key = keyFor(item);
@@ -391,12 +371,12 @@ const collectGroupedCandidates = (
   return groups;
 };
 
+/** Convert non-singleton candidate groups into deterministic clusters. */
 const clustersFromGroups = (
   groups: Map<string, DedupeAuditPreparedCandidate[]>,
   mode: DedupeAuditMode,
   matchReason: string,
 ): DedupeAuditCluster[] => {
-  /** Convert non-singleton candidate groups into deterministic clusters. */
   return [...groups.entries()]
     .filter(([, members]) => members.length > 1)
     .map(([key, members]) =>
@@ -404,10 +384,10 @@ const clustersFromGroups = (
     );
 };
 
+/** Group candidates that share the same normalized title. */
 const collectExactTitleClusters = (
   items: DedupeAuditPreparedCandidate[],
 ): DedupeAuditCluster[] => {
-  /** Group candidates that share the same normalized title. */
   const groups = collectGroupedCandidates(items, (item) =>
     item.normalized_title.length === 0 ? undefined : item.normalized_title,
   );
@@ -418,10 +398,10 @@ const collectExactTitleClusters = (
   );
 };
 
+/** Group normalized-title duplicates only when they share a parent. */
 const collectParentScopedClusters = (
   items: DedupeAuditPreparedCandidate[],
 ): DedupeAuditCluster[] => {
-  /** Group normalized-title duplicates only when they share a parent. */
   const groups = collectGroupedCandidates(items, (item) =>
     item.parent && item.normalized_title.length > 0
       ? `${item.parent}|${item.normalized_title}`
@@ -434,8 +414,8 @@ const collectParentScopedClusters = (
   );
 };
 
+/** Find and compress one disjoint-set root for fuzzy clustering. */
 const findRoot = (parents: number[], index: number): number => {
-  /** Find and compress one disjoint-set root for fuzzy clustering. */
   let current = index;
   while (parents[current] !== current) {
     parents[current] = parents[parents[current]];
@@ -444,8 +424,8 @@ const findRoot = (parents: number[], index: number): number => {
   return current;
 };
 
+/** Join two fuzzy-cluster roots under the lower deterministic index. */
 const unionRoots = (parents: number[], left: number, right: number): void => {
-  /** Join two fuzzy-cluster roots under the lower deterministic index. */
   const leftRoot = findRoot(parents, left);
   const rightRoot = findRoot(parents, right);
   if (leftRoot === rightRoot) {
@@ -454,11 +434,11 @@ const unionRoots = (parents: number[], left: number, right: number): void => {
   parents[Math.max(leftRoot, rightRoot)] = Math.min(leftRoot, rightRoot);
 };
 
+/** Build transitive fuzzy-title clusters at the requested similarity floor. */
 const collectFuzzyTitleClusters = (
   items: DedupeAuditPreparedCandidate[],
   threshold: number,
 ): DedupeAuditCluster[] => {
-  /** Build transitive fuzzy-title clusters at the requested similarity floor. */
   const parents = items.map((_item, index) => index);
   forEachCandidatePair(items, (left, right, leftIndex, rightIndex) => {
     if (similarityScore(left, right) >= threshold) {
@@ -490,11 +470,11 @@ const collectFuzzyTitleClusters = (
     });
 };
 
+/** Order larger clusters first and break ties by canonical identity. */
 const compareClusters = (
   left: DedupeAuditCluster,
   right: DedupeAuditCluster,
 ): number => {
-  /** Order larger clusters first and break ties by canonical identity. */
   const bySize = right.cluster_size - left.cluster_size;
   if (bySize !== 0) {
     return bySize;
@@ -502,12 +482,12 @@ const compareClusters = (
   return left.canonical.id.localeCompare(right.canonical.id);
 };
 
+/** Dispatch candidate collection to the selected comparison strategy. */
 const collectDedupeClusters = (
   mode: DedupeAuditMode,
   prepared: DedupeAuditPreparedCandidate[],
   fuzzyThreshold: number,
 ): DedupeAuditCluster[] => {
-  /** Dispatch candidate collection to the selected comparison strategy. */
   if (mode === "title_exact") {
     return collectExactTitleClusters(prepared);
   }
@@ -517,10 +497,11 @@ const collectDedupeClusters = (
   return collectFuzzyTitleClusters(prepared, fuzzyThreshold);
 };
 
+/** Precompute normalized fields used by every dedupe comparison strategy. */
 const toPreparedDedupeCandidate = (
   item: ListedItem,
+  registry: RuntimeStatusRegistry,
 ): DedupeAuditPreparedCandidate => {
-  /** Precompute normalized fields used by every dedupe comparison strategy. */
   return {
     id: item.id,
     title: item.title,
@@ -531,6 +512,7 @@ const toPreparedDedupeCandidate = (
     created_at: item.created_at,
     updated_at: item.updated_at,
     normalized_title: normalizeSimilarityText(item.title),
+    terminal: isTerminalStatus(item.status, registry),
   };
 };
 
@@ -538,6 +520,7 @@ const toPreparedDedupeCandidate = (
 const toNullable = <Value>(value: Value | undefined): Value | null =>
   value ?? null;
 
+/** Echo normalized audit filters in the stable public result shape. */
 const buildDedupeAuditFilters = (params: {
   mode: DedupeAuditMode;
   status: ItemStatus | "all" | undefined;
@@ -545,7 +528,6 @@ const buildDedupeAuditFilters = (params: {
   limit: number | undefined;
   fuzzyThreshold: number;
 }): DedupeAuditResult["filters"] => {
-  /** Echo normalized audit filters in the stable public result shape. */
   return {
     mode: params.mode,
     status: toNullable(params.status),
@@ -572,24 +554,27 @@ export const runDedupeAudit = async (
   const pmRoot = resolvePmRoot(process.cwd(), global.path);
   const settings = await readSettings(pmRoot);
   const statusRegistry = resolveRuntimeStatusRegistry(settings.schema);
-  dedupeStatusRegistry = statusRegistry;
-  dedupeAllowedStatuses = new Set(
-    statusRegistry.definitions.map((definition) => definition.id),
-  );
-  dedupeTerminalStatuses = new Set(statusRegistry.terminal_statuses);
   const mode = parseMode(options.mode);
-  const status = parseStatus(options.status);
+  const status = parseStatus(options.status, statusRegistry);
   const limit = parseIntegerLimit(options.limit);
   const threshold = parseThreshold(options.threshold);
   const fuzzyThreshold = threshold ?? 0.8;
 
   const listed = await runList(
     status === "all" ? undefined : status,
-    { ...buildListQueryFilters(options), full: true as const },
+    {
+      ...buildListQueryFilters(options),
+      full: true as const,
+      all: true,
+      noTruncate: true,
+      strictRead: true,
+    },
     global,
   );
 
-  const prepared = listed.items.map((item) => toPreparedDedupeCandidate(item));
+  const prepared = listed.items.map((item) =>
+    toPreparedDedupeCandidate(item, statusRegistry),
+  );
 
   const clusters = collectDedupeClusters(mode, prepared, fuzzyThreshold);
 

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

@@ -60,14 +60,14 @@ const dedupeAuditFlags = [
     long: "--status",
     value_name: "value",
     value_type: "string",
-    description: "Filter by status.",
+    description: "Filter by configured status IDs or aliases (comma-separated); all includes every lifecycle state.",
   },
   ...auditNormalizeFilterFlags,
   {
     long: "--limit",
     value_name: "n",
     value_type: "string",
-    description: "Limit analyzed items.",
+    description: "Limit returned duplicate clusters; every matching item is analyzed.",
   },
   {
     long: "--threshold",

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

@@ -4,6 +4,7 @@
  * Resolves the host pm SDK runtime and exposes the typed subset consumed by
  * the governance-audit package without copying core command implementations.
  */
+export { SETTINGS_DEFAULTS, parseStatusFilterCsv } from "@unbrained/pm-cli/sdk";
 import * as runtime from "@unbrained/pm-cli/sdk/runtime";
 
 /** Host SDK values used by package-owned audit commands and runtime decorators. */

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

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-governance-audit",
-  "version": "2026.9.4",
+  "version": "2026.9.6",
   "private": true,
   "type": "module",
   "description": "First-party pm package for governance audit and normalization workflows.",

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

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-guide-shell",
-  "version": "2026.9.4",
+  "version": "2026.9.6",
   "private": true,
   "type": "module",
   "description": "First-party pm package for guide and shell completion workflows.",

package/packages/pm-kanban/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-kanban",
-  "version": "2026.9.4",
+  "version": "2026.9.6",
   "private": true,
   "type": "module",
   "description": "First-party pm archetype package: a complete Kanban continuous-flow profile built on public SDK primitives.",

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

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-lifecycle-hooks",
-  "version": "2026.9.4",
+  "version": "2026.9.6",
   "private": true,
   "type": "module",
   "description": "First-party pm package demonstrating safe lifecycle hook registration.",

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

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-linked-test-adapters",
-  "version": "2026.9.4",
+  "version": "2026.9.6",
   "private": true,
   "type": "module",
   "description": "First-party pm package for optional linked-test run management adapters and reporters.",

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

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-search-advanced",
-  "version": "2026.9.4",
+  "version": "2026.9.6",
   "private": true,
   "type": "module",
   "description": "First-party pm package for semantic, hybrid, and reindex search workflows.",

package/packages/pm-templates/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-templates",
-  "version": "2026.9.4",
+  "version": "2026.9.6",
   "private": true,
   "type": "module",
   "description": "First-party pm package for reusable create templates.",

package/packages/pm-todos/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-todos",
-  "version": "2026.9.4",
+  "version": "2026.9.6",
   "private": true,
   "type": "module",
   "description": "First-party pm package for Todo markdown import and export.",

package/packages/pm-vcs/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-vcs-sdk-exemplar",
-  "version": "2026.9.4",
+  "version": "2026.9.6",
   "private": true,
   "type": "module",
   "description": "Beyond-PM exemplar: a VCS-style changeset workflow built entirely on public pm SDK and extension primitives.",

package/plugins/pm-claude/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "pm-claude",
   "description": "Native pm CLI integration for Claude Code — 28 MCP tools, 5 workflow skills, 14 slash commands, 4 subagents (coordinator, delivery-chain, triage, verification), hybrid TUI task tracking (pm as persistent store + Claude Code task panel as live view), session context injection, and full git-based project management without leaving Claude Code.",
-  "version": "2026.9.4",
+  "version": "2026.9.6",
   "author": {
     "name": "unbrained",
     "url": "https://github.com/unbraind/pm-cli"

package/plugins/pm-claude/skills/pm-audit/SKILL.md

@@ -94,8 +94,8 @@ Load the smallest thing that answers the question. Costs are measured.
 | The whole command surface with per-command ceilings | `pm_contracts` with `summary: true` | ~2.6k tok |
 | An unfamiliar capability family | `pm_run` with `action: "guide", topic: "<topic>", depth: "brief"` | ~0.6-1k tok |
 
-Guide topics: `quickstart`, `commands`, `workflows`, `sdk`, `extensions`,
-`skills`, `harnesses`, `release`, `tokens`, `graph`, `assurance`, `merge`.
+Guide topics are declared at runtime: `pm guide` prints the current index and
+`pm guide <topic> --depth brief` expands one topic. Do not copy the list.
 
 Never load `docs/COMMANDS.md` (~29k tok) or `docs/SDK.md` (~45k tok) whole.
 

package/plugins/pm-claude/skills/pm-developer/SKILL.md

@@ -133,8 +133,8 @@ Load the smallest thing that answers the question. Costs are measured.
 | The whole command surface with per-command ceilings | `pm_contracts` with `summary: true` | ~2.6k tok |
 | An unfamiliar capability family | `pm_run` with `action: "guide", topic: "<topic>", depth: "brief"` | ~0.6-1k tok |
 
-Guide topics: `quickstart`, `commands`, `workflows`, `sdk`, `extensions`,
-`skills`, `harnesses`, `release`, `tokens`, `graph`, `assurance`, `merge`.
+Guide topics are declared at runtime: `pm guide` prints the current index and
+`pm guide <topic> --depth brief` expands one topic. Do not copy the list.
 
 Never load `docs/COMMANDS.md` (~29k tok) or `docs/SDK.md` (~45k tok) whole.
 

package/plugins/pm-claude/skills/pm-planner/SKILL.md

@@ -157,8 +157,8 @@ Load the smallest thing that answers the question. Costs are measured.
 | The whole command surface with per-command ceilings | `pm_contracts` with `summary: true` | ~2.6k tok |
 | An unfamiliar capability family | `pm_run` with `action: "guide", topic: "<topic>", depth: "brief"` | ~0.6-1k tok |
 
-Guide topics: `quickstart`, `commands`, `workflows`, `sdk`, `extensions`,
-`skills`, `harnesses`, `release`, `tokens`, `graph`, `assurance`, `merge`.
+Guide topics are declared at runtime: `pm guide` prints the current index and
+`pm guide <topic> --depth brief` expands one topic. Do not copy the list.
 
 Never load `docs/COMMANDS.md` (~29k tok) or `docs/SDK.md` (~45k tok) whole.
 

package/plugins/pm-claude/skills/pm-release/SKILL.md

@@ -92,8 +92,8 @@ Load the smallest thing that answers the question. Costs are measured.
 | The whole command surface with per-command ceilings | `pm_contracts` with `summary: true` | ~2.6k tok |
 | An unfamiliar capability family | `pm_run` with `action: "guide", topic: "<topic>", depth: "brief"` | ~0.6-1k tok |
 
-Guide topics: `quickstart`, `commands`, `workflows`, `sdk`, `extensions`,
-`skills`, `harnesses`, `release`, `tokens`, `graph`, `assurance`, `merge`.
+Guide topics are declared at runtime: `pm guide` prints the current index and
+`pm guide <topic> --depth brief` expands one topic. Do not copy the list.
 
 Never load `docs/COMMANDS.md` (~29k tok) or `docs/SDK.md` (~45k tok) whole.
 

package/plugins/pm-claude/skills/pm-workflow/SKILL.md

@@ -15,7 +15,7 @@ Use this skill for all pm-tracked work. Prefer native MCP tools over shell `pm`
 |---------|------|
 | Orient / read state | `pm_context`, `pm_search`, `pm_list`, `pm_get` |
 | Create / update | `pm_create`, `pm_update`, `pm_claim`, `pm_release`, `pm_close` |
-| Evidence | `pm_comments`, `pm_files`, `pm_docs`, `pm_test` |
+| Evidence | `pm_comments`, `pm_notes`, `pm_learnings`, `pm_files`, `pm_docs`, `pm_test` |
 | Verify | `pm_validate`, `pm_health`, `pm_contracts` |
 | Everything else | `pm_run` with an explicit `action` |
 
@@ -154,8 +154,8 @@ Load the smallest thing that answers the question. Costs are measured.
 | The whole command surface with per-command ceilings | `pm_contracts` with `summary: true` | ~2.6k tok |
 | An unfamiliar capability family | `pm_run` with `action: "guide", topic: "<topic>", depth: "brief"` | ~0.6-1k tok |
 
-Guide topics: `quickstart`, `commands`, `workflows`, `sdk`, `extensions`,
-`skills`, `harnesses`, `release`, `tokens`, `graph`, `assurance`, `merge`.
+Guide topics are declared at runtime: `pm guide` prints the current index and
+`pm guide <topic> --depth brief` expands one topic. Do not copy the list.
 
 Never load `docs/COMMANDS.md` (~29k tok) or `docs/SDK.md` (~45k tok) whole.
 

package/plugins/pm-codex/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "pm-codex",
-  "version": "2026.9.4",
+  "version": "2026.9.6",
   "description": "Native Codex integration for pm-cli with bundled MCP tools, skills, commands, and agent workflows.",
   "author": {
     "name": "unbrained",

package/plugins/pm-codex/skills/pm-auditor/SKILL.md

@@ -30,8 +30,8 @@ Load the smallest thing that answers the question. Costs are measured.
 | The whole command surface with per-command ceilings | `pm_contracts` with `summary: true` | ~2.6k tok |
 | An unfamiliar capability family | `pm_run` with `action: "guide", topic: "<topic>", depth: "brief"` | ~0.6-1k tok |
 
-Guide topics: `quickstart`, `commands`, `workflows`, `sdk`, `extensions`,
-`skills`, `harnesses`, `release`, `tokens`, `graph`, `assurance`, `merge`.
+Guide topics are declared at runtime: `pm guide` prints the current index and
+`pm guide <topic> --depth brief` expands one topic. Do not copy the list.
 
 Never load `docs/COMMANDS.md` (~29k tok) or `docs/SDK.md` (~45k tok) whole.
 

package/plugins/pm-codex/skills/pm-native/SKILL.md

@@ -14,7 +14,7 @@ Use MCP tools before shell commands:
 
 - Orient: `pm_context`, `pm_search`, `pm_list`, `pm_get`
 - Mutate: `pm_create`, `pm_update`, `pm_claim`, `pm_release`, `pm_close`
-- Evidence: `pm_comments`, `pm_files`, `pm_docs`, `pm_test`
+- Evidence: `pm_comments`, `pm_notes`, `pm_learnings`, `pm_files`, `pm_docs`, `pm_test`
 - Verify: `pm_validate`, `pm_health`, `pm_contracts`
 - Everything else: `pm_run` with an explicit `action`
 
@@ -37,7 +37,6 @@ Most tools accept:
 ```json
 {
   "cwd": "/repo/root",
-  "author": "codex-agent",
   "options": {
     "limit": "10"
   }
@@ -79,8 +78,8 @@ Load the smallest thing that answers the question. Costs are measured.
 | The whole command surface with per-command ceilings | `pm_contracts` with `summary: true` | ~2.6k tok |
 | An unfamiliar capability family | `pm_run` with `action: "guide", topic: "<topic>", depth: "brief"` | ~0.6-1k tok |
 
-Guide topics: `quickstart`, `commands`, `workflows`, `sdk`, `extensions`,
-`skills`, `harnesses`, `release`, `tokens`, `graph`, `assurance`, `merge`.
+Guide topics are declared at runtime: `pm guide` prints the current index and
+`pm guide <topic> --depth brief` expands one topic. Do not copy the list.
 
 Never load `docs/COMMANDS.md` (~29k tok) or `docs/SDK.md` (~45k tok) whole.
 

package/plugins/pm-codex/skills/pm-release/SKILL.md

@@ -29,8 +29,8 @@ Load the smallest thing that answers the question. Costs are measured.
 | The whole command surface with per-command ceilings | `pm_contracts` with `summary: true` | ~2.6k tok |
 | An unfamiliar capability family | `pm_run` with `action: "guide", topic: "<topic>", depth: "brief"` | ~0.6-1k tok |
 
-Guide topics: `quickstart`, `commands`, `workflows`, `sdk`, `extensions`,
-`skills`, `harnesses`, `release`, `tokens`, `graph`, `assurance`, `merge`.
+Guide topics are declared at runtime: `pm guide` prints the current index and
+`pm guide <topic> --depth brief` expands one topic. Do not copy the list.
 
 Never load `docs/COMMANDS.md` (~29k tok) or `docs/SDK.md` (~45k tok) whole.
 

package/scripts/finalize-build.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 
-import { chmod, stat } from "node:fs/promises";
+import { chmod, readFile, stat, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
 
@@ -16,6 +16,7 @@ async function outputExists(filePath) {
   }
 }
 
+/** Finalize executable modes and the semantically identical compact public SDK manifest. */
 export async function main(repoRoot = process.cwd()) {
   const executableOutputs = [
     path.join(repoRoot, "dist", "cli.js"),
@@ -28,6 +29,17 @@ export async function main(repoRoot = process.cwd()) {
       await chmod(outputPath, 0o755);
     }
   }
+
+  // Keep the checked-in compatibility manifest readable, while distributing
+  // identical JSON data without indentation through its stable public export.
+  const manifest = JSON.parse(
+    await readFile(path.join(repoRoot, "sdk", "public-surface.json"), "utf8"),
+  );
+  await writeFile(
+    path.join(repoRoot, "dist", "sdk", "public-surface.json"),
+    `${JSON.stringify(manifest)}\n`,
+    "utf8",
+  );
 }
 
 /* c8 ignore start -- CLI auto-run guard; logic covered via exported main() */