@unbrained/pm-cli 2026.6.10 → 2026.6.12

package/dist/core/validate/stale-file-classification.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Classification of stale linked paths reported by `pm validate --check-files`.
+ *
+ * A linked file path that no longer exists is either:
+ * - `moved`: a file with the same basename still exists elsewhere in the
+ *   scanned candidate set — the candidates are reported so an agent can relink
+ *   the item to the new location instead of dropping the link, or
+ * - `deleted`: no candidate with that basename exists anywhere in the scan,
+ *   so the link points at content that is gone and pruning it is safe.
+ *
+ * Pure module (pm-0v2m / GH-184): no filesystem access — callers pass the
+ * already-collected candidate file list from the files check scan.
+ */
+export type StaleLinkedPathClassification = "moved" | "deleted";
+export interface ClassifiedStaleLinkedPath {
+    /** Normalized workspace-relative stale linked path. */
+    path: string;
+    classification: StaleLinkedPathClassification;
+    /**
+     * Candidate new locations (same basename, different path), sorted and capped
+     * at `candidateLimit`. Empty for `deleted`.
+     */
+    candidates: string[];
+    /** True when more candidates existed than `candidateLimit` allowed. */
+    candidates_truncated: boolean;
+}
+export declare const DEFAULT_STALE_PATH_CANDIDATE_LIMIT = 3;
+/**
+ * Classify each stale (missing) linked path as `moved` or `deleted` by
+ * matching its basename against the candidate file list. Output preserves the
+ * input order of `stalePaths` (callers pass an already-sorted unique list).
+ * A candidate equal to the stale path itself never matches (the path is known
+ * missing; an identical candidate would be self-referential noise).
+ */
+export declare function classifyStaleLinkedPaths(stalePaths: readonly string[], candidateFiles: readonly string[], candidateLimit?: number): ClassifiedStaleLinkedPath[];
+/**
+ * Render compact `<path>:moved:<top-candidate>` / `<path>:deleted` rows for
+ * the files check details (token-efficient counterpart to the full
+ * classification objects).
+ */
+export declare function summarizeStaleLinkedPathClassifications(classified: readonly ClassifiedStaleLinkedPath[]): string[];

package/dist/core/validate/stale-file-classification.js

@@ -0,0 +1,73 @@
+/**
+ * Classification of stale linked paths reported by `pm validate --check-files`.
+ *
+ * A linked file path that no longer exists is either:
+ * - `moved`: a file with the same basename still exists elsewhere in the
+ *   scanned candidate set — the candidates are reported so an agent can relink
+ *   the item to the new location instead of dropping the link, or
+ * - `deleted`: no candidate with that basename exists anywhere in the scan,
+ *   so the link points at content that is gone and pruning it is safe.
+ *
+ * Pure module (pm-0v2m / GH-184): no filesystem access — callers pass the
+ * already-collected candidate file list from the files check scan.
+ */
+
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="2df68560-32a7-5762-9470-cf82e978a90d")}catch(e){}}();
+export const DEFAULT_STALE_PATH_CANDIDATE_LIMIT = 3;
+function basenameOf(relativePath) {
+    const lastSlash = Math.max(relativePath.lastIndexOf("/"), relativePath.lastIndexOf("\\"));
+    return lastSlash === -1 ? relativePath : relativePath.slice(lastSlash + 1);
+}
+/**
+ * Classify each stale (missing) linked path as `moved` or `deleted` by
+ * matching its basename against the candidate file list. Output preserves the
+ * input order of `stalePaths` (callers pass an already-sorted unique list).
+ * A candidate equal to the stale path itself never matches (the path is known
+ * missing; an identical candidate would be self-referential noise).
+ */
+export function classifyStaleLinkedPaths(stalePaths, candidateFiles, candidateLimit = DEFAULT_STALE_PATH_CANDIDATE_LIMIT) {
+    const limit = Number.isFinite(candidateLimit) && candidateLimit >= 1 ? Math.floor(candidateLimit) : DEFAULT_STALE_PATH_CANDIDATE_LIMIT;
+    const candidatesByBasename = new Map();
+    for (const candidate of candidateFiles) {
+        const basename = basenameOf(candidate);
+        if (basename.length === 0) {
+            continue;
+        }
+        const bucket = candidatesByBasename.get(basename);
+        if (bucket) {
+            bucket.push(candidate);
+        }
+        else {
+            candidatesByBasename.set(basename, [candidate]);
+        }
+    }
+    return stalePaths.map((stalePath) => {
+        const matches = (candidatesByBasename.get(basenameOf(stalePath)) ?? [])
+            .filter((candidate) => candidate !== stalePath)
+            .sort((left, right) => left.localeCompare(right));
+        if (matches.length === 0) {
+            return {
+                path: stalePath,
+                classification: "deleted",
+                candidates: [],
+                candidates_truncated: false,
+            };
+        }
+        return {
+            path: stalePath,
+            classification: "moved",
+            candidates: matches.slice(0, limit),
+            candidates_truncated: matches.length > limit,
+        };
+    });
+}
+/**
+ * Render compact `<path>:moved:<top-candidate>` / `<path>:deleted` rows for
+ * the files check details (token-efficient counterpart to the full
+ * classification objects).
+ */
+export function summarizeStaleLinkedPathClassifications(classified) {
+    return classified.map((entry) => entry.classification === "moved" ? `${entry.path}:moved:${entry.candidates[0]}` : `${entry.path}:deleted`);
+}
+//# sourceMappingURL=stale-file-classification.js.map
+//# debugId=2df68560-32a7-5762-9470-cf82e978a90d

package/dist/core/validate/stale-file-classification.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stale-file-classification.js","sources":["core/validate/stale-file-classification.ts"],"sourceRoot":"/","sourcesContent":["/**\n * Classification of stale linked paths reported by `pm validate --check-files`.\n *\n * A linked file path that no longer exists is either:\n * - `moved`: a file with the same basename still exists elsewhere in the\n *   scanned candidate set — the candidates are reported so an agent can relink\n *   the item to the new location instead of dropping the link, or\n * - `deleted`: no candidate with that basename exists anywhere in the scan,\n *   so the link points at content that is gone and pruning it is safe.\n *\n * Pure module (pm-0v2m / GH-184): no filesystem access — callers pass the\n * already-collected candidate file list from the files check scan.\n */\n\nexport type StaleLinkedPathClassification = \"moved\" | \"deleted\";\n\nexport interface ClassifiedStaleLinkedPath {\n  /** Normalized workspace-relative stale linked path. */\n  path: string;\n  classification: StaleLinkedPathClassification;\n  /**\n   * Candidate new locations (same basename, different path), sorted and capped\n   * at `candidateLimit`. Empty for `deleted`.\n   */\n  candidates: string[];\n  /** True when more candidates existed than `candidateLimit` allowed. */\n  candidates_truncated: boolean;\n}\n\nexport const DEFAULT_STALE_PATH_CANDIDATE_LIMIT = 3;\n\nfunction basenameOf(relativePath: string): string {\n  const lastSlash = Math.max(relativePath.lastIndexOf(\"/\"), relativePath.lastIndexOf(\"\\\\\"));\n  return lastSlash === -1 ? relativePath : relativePath.slice(lastSlash + 1);\n}\n\n/**\n * Classify each stale (missing) linked path as `moved` or `deleted` by\n * matching its basename against the candidate file list. Output preserves the\n * input order of `stalePaths` (callers pass an already-sorted unique list).\n * A candidate equal to the stale path itself never matches (the path is known\n * missing; an identical candidate would be self-referential noise).\n */\nexport function classifyStaleLinkedPaths(\n  stalePaths: readonly string[],\n  candidateFiles: readonly string[],\n  candidateLimit: number = DEFAULT_STALE_PATH_CANDIDATE_LIMIT,\n): ClassifiedStaleLinkedPath[] {\n  const limit = Number.isFinite(candidateLimit) && candidateLimit >= 1 ? Math.floor(candidateLimit) : DEFAULT_STALE_PATH_CANDIDATE_LIMIT;\n  const candidatesByBasename = new Map<string, string[]>();\n  for (const candidate of candidateFiles) {\n    const basename = basenameOf(candidate);\n    if (basename.length === 0) {\n      continue;\n    }\n    const bucket = candidatesByBasename.get(basename);\n    if (bucket) {\n      bucket.push(candidate);\n    } else {\n      candidatesByBasename.set(basename, [candidate]);\n    }\n  }\n\n  return stalePaths.map((stalePath) => {\n    const matches = (candidatesByBasename.get(basenameOf(stalePath)) ?? [])\n      .filter((candidate) => candidate !== stalePath)\n      .sort((left, right) => left.localeCompare(right));\n    if (matches.length === 0) {\n      return {\n        path: stalePath,\n        classification: \"deleted\" as const,\n        candidates: [],\n        candidates_truncated: false,\n      };\n    }\n    return {\n      path: stalePath,\n      classification: \"moved\" as const,\n      candidates: matches.slice(0, limit),\n      candidates_truncated: matches.length > limit,\n    };\n  });\n}\n\n/**\n * Render compact `<path>:moved:<top-candidate>` / `<path>:deleted` rows for\n * the files check details (token-efficient counterpart to the full\n * classification objects).\n */\nexport function summarizeStaleLinkedPathClassifications(classified: readonly ClassifiedStaleLinkedPath[]): string[] {\n  return classified.map((entry) =>\n    entry.classification === \"moved\" ? `${entry.path}:moved:${entry.candidates[0]}` : `${entry.path}:deleted`,\n  );\n}\n"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;;;AAiBH,MAAM,CAAC,MAAM,kCAAkC,GAAG,CAAC,CAAC;AAEpD,SAAS,UAAU,CAAC,YAAoB;IACtC,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC,YAAY,CAAC,WAAW,CAAC,GAAG,CAAC,EAAE,YAAY,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC,CAAC;IAC1F,OAAO,SAAS,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,YAAY,CAAC,KAAK,CAAC,SAAS,GAAG,CAAC,CAAC,CAAC;AAC7E,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,wBAAwB,CACtC,UAA6B,EAC7B,cAAiC,EACjC,iBAAyB,kCAAkC;IAE3D,MAAM,KAAK,GAAG,MAAM,CAAC,QAAQ,CAAC,cAAc,CAAC,IAAI,cAAc,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,kCAAkC,CAAC;IACvI,MAAM,oBAAoB,GAAG,IAAI,GAAG,EAAoB,CAAC;IACzD,KAAK,MAAM,SAAS,IAAI,cAAc,EAAE,CAAC;QACvC,MAAM,QAAQ,GAAG,UAAU,CAAC,SAAS,CAAC,CAAC;QACvC,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC1B,SAAS;QACX,CAAC;QACD,MAAM,MAAM,GAAG,oBAAoB,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QAClD,IAAI,MAAM,EAAE,CAAC;YACX,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;QACzB,CAAC;aAAM,CAAC;YACN,oBAAoB,CAAC,GAAG,CAAC,QAAQ,EAAE,CAAC,SAAS,CAAC,CAAC,CAAC;QAClD,CAAC;IACH,CAAC;IAED,OAAO,UAAU,CAAC,GAAG,CAAC,CAAC,SAAS,EAAE,EAAE;QAClC,MAAM,OAAO,GAAG,CAAC,oBAAoB,CAAC,GAAG,CAAC,UAAU,CAAC,SAAS,CAAC,CAAC,IAAI,EAAE,CAAC;aACpE,MAAM,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,SAAS,KAAK,SAAS,CAAC;aAC9C,IAAI,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC,IAAI,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC,CAAC;QACpD,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACzB,OAAO;gBACL,IAAI,EAAE,SAAS;gBACf,cAAc,EAAE,SAAkB;gBAClC,UAAU,EAAE,EAAE;gBACd,oBAAoB,EAAE,KAAK;aAC5B,CAAC;QACJ,CAAC;QACD,OAAO;YACL,IAAI,EAAE,SAAS;YACf,cAAc,EAAE,OAAgB;YAChC,UAAU,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC;YACnC,oBAAoB,EAAE,OAAO,CAAC,MAAM,GAAG,KAAK;SAC7C,CAAC;IACJ,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,uCAAuC,CAAC,UAAgD;IACtG,OAAO,UAAU,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAC9B,KAAK,CAAC,cAAc,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,IAAI,UAAU,KAAK,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,IAAI,UAAU,CAC1G,CAAC;AACJ,CAAC","debugId":"2df68560-32a7-5762-9470-cf82e978a90d"}

package/dist/mcp/server.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="c65aa3d0-c69f-561b-8e23-939348167e21")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="e3feb52b-3154-5b9c-85ec-f0639c808233")}catch(e){}}();
 import readline from "node:readline";
 import { fileURLToPath } from "node:url";
 import { createEmptyExtensionCommandRegistry, createEmptyExtensionHookRegistry, createEmptyExtensionParserRegistry, createEmptyExtensionPreflightRegistry, createEmptyExtensionRegistrationRegistry, createEmptyExtensionRendererRegistry, createEmptyExtensionServiceRegistry, } from "../core/extensions/extension-registries.js";
@@ -8,6 +8,7 @@ import { activateExtensions, deactivateExtensions, loadExtensions, runActiveComm
 import { pathExists } from "../core/fs/fs-utils.js";
 import { resolvePmCliVersion } from "../core/packages/root.js";
 import { projectMutationResult } from "../core/output/mutation-projection.js";
+import { withQuerySummary } from "../core/output/query-summary.js";
 import { PmCliError } from "../core/shared/errors.js";
 import { decodeHtmlEntitiesInOptions } from "../core/shared/html-entity-decode.js";
 import { levenshteinDistanceWithinLimit } from "../core/shared/levenshtein.js";
@@ -17,9 +18,9 @@ import { getSettingsPath, resolvePmRoot } from "../core/store/paths.js";
 import { readSettings } from "../core/store/settings.js";
 import { normalizeListOptions, normalizeUpdateOptions } from "../cli/registration-helpers.js";
 import { UPDATE_COMMANDER_STRING_OPTION_CONTRACTS } from "../sdk/cli-contracts/commander-mutation-options.js";
-import { PM_TOOL_ACTIONS } from "../sdk/cli-contracts/enum-contracts.js";
 import { clearWorkspaceContractsCache } from "../sdk/runtime.js";
-import { runActivity, runAggregate, runAppend, runClaim, runClose, runCloseMany, runComments, runContracts, runContext, runCreate, runCopy, runConfig, runDelete, runDeps, runDocs, runExtension, runFiles, runFilesDiscover, runGc, runGet, runHealth, runHistory, runHistoryCompact, runHistoryRedact, runHistoryRepair, runInit, runLearnings, runList, runNotes, runPlan, runRelease, runSchemaAddStatus, runSchemaAddType, runSchemaList, runSchemaRemoveStatus, runSchemaRemoveType, runSchemaShow, runSchemaShowStatus, runSearch, runStats, runTelemetry, runTest, runTestAll, runUpdate, runUpdateMany, runUpgrade, runValidate, } from "../cli/commands/index.js";
+import { TOOLS } from "./tool-definitions.js";
+import { runActivity, runAggregate, runAppend, runClaim, runClose, runCloseMany, runComments, runContracts, runContext, runCreate, runCopy, runConfig, runDelete, runDeps, runDocs, runExtension, runFiles, runFilesDiscover, runGc, runGet, runHealth, runHistory, runHistoryCompact, runHistoryRedact, runHistoryRepair, runHistoryRepairAll, assertHistoryRepairTarget, runInit, runLearnings, runList, runNotes, runPlan, runRelease, runSchemaAddStatus, runSchemaAddType, runSchemaList, runSchemaRemoveStatus, runSchemaRemoveType, runSchemaShow, runSchemaShowStatus, runSearch, runStats, runTelemetry, runTest, runTestAll, runUpdate, runUpdateMany, runUpgrade, runValidate, } from "../cli/commands/index.js";
 const PM_PACKAGE_ROOT_ENV = "PM_CLI_PACKAGE_ROOT";
 function resolvePmPackageRoot() {
     return fileURLToPath(new URL("../..", import.meta.url));
@@ -30,256 +31,9 @@ if (typeof process.env[PM_PACKAGE_ROOT_ENV] !== "string" || process.env[PM_PACKA
 // Reflect the real package.json version so agents/telemetry can identify the
 // build serving requests (was hard-coded "1.0.0"; see pm-2nvw).
 const PM_MCP_SERVER_VERSION = resolvePmCliVersion(import.meta.url, ["../.."]) ?? "0.0.0";
-const TOOL_SCHEMA_BASE = {
-    type: "object",
-    properties: {
-        cwd: {
-            type: "string",
-            description: "Workspace directory to run the native pm operation in. Defaults to the MCP server process cwd.",
-        },
-        path: {
-            type: "string",
-            description: "Optional pm data root, equivalent to PM_PATH/global --path. Leave unset for real repository tracking.",
-        },
-        author: {
-            type: "string",
-            description: "Mutation author. Defaults to PM_AUTHOR or pm settings when supported by the underlying operation.",
-        },
-    },
-    additionalProperties: true,
-};
-const idSchema = {
-    type: "string",
-    description: "pm item id, for example pm-abc1.",
-};
-// pm-fd8n: derive the pm_run action enumeration from the canonical
-// PM_TOOL_ACTIONS contract instead of a hand-maintained prose list, so the
-// MCP-facing description can never drift from the actual supported actions.
-const PM_RUN_ACTION_DESCRIPTION = `Operation name (one of): ${PM_TOOL_ACTIONS.join(", ")}. ` +
-    "Package-owned actions (for example calendar/templates/guide/dedupe-audit/normalize/reindex/comments-audit/completion/test-runs-list/test-runs-status/test-runs-logs/test-runs-stop/test-runs-resume) are available dynamically when installed.";
-const LIST_TOP_LEVEL_OPTION_PROPERTIES = {
-    status: { type: "string", description: "Alias for options.status." },
-    type: { type: "string", description: "Alias for options.type." },
-    tag: { type: "string", description: "Alias for options.tag." },
-    priority: { type: "string", description: "Alias for options.priority." },
-    limit: { type: ["string", "number"], description: "Alias for options.limit." },
-    offset: { type: ["string", "number"], description: "Alias for options.offset." },
-};
-const SEARCH_TOP_LEVEL_OPTION_PROPERTIES = {
-    mode: { type: "string", description: "Alias for options.mode." },
-    status: { type: "string", description: "Alias for options.status." },
-    type: { type: "string", description: "Alias for options.type." },
-    tag: { type: "string", description: "Alias for options.tag." },
-    priority: { type: "string", description: "Alias for options.priority." },
-    limit: { type: ["string", "number"], description: "Alias for options.limit." },
-};
-function objectSchema(properties, required = []) {
-    return {
-        ...TOOL_SCHEMA_BASE,
-        properties: {
-            ...TOOL_SCHEMA_BASE.properties,
-            ...properties,
-        },
-        required,
-    };
-}
-const TOOLS = [
-    {
-        name: "pm_run",
-        description: "Run any supported pm operation natively through the pm library. Use this for commands not covered by narrower pm_* tools.",
-        inputSchema: objectSchema({
-            action: {
-                type: "string",
-                description: PM_RUN_ACTION_DESCRIPTION,
-            },
-            id: idSchema,
-            query: { type: "string", description: "Search query for action=search." },
-            reason: { type: "string", description: "Close reason for action=close." },
-            force: { type: "boolean", description: "Force ownership/terminal-state override when supported." },
-            subcommand: {
-                type: "string",
-                enum: ["list", "show", "show-status", "add-type", "remove-type", "add-status", "remove-status"],
-                description: "Schema subcommand when action=schema.",
-            },
-            name: {
-                type: "string",
-                description: "Item type name for action=schema show/add-type/remove-type, or status id for show-status/add-status/remove-status.",
-            },
-            description: {
-                type: "string",
-                description: "Custom item type or status description for action=schema add-type/add-status.",
-            },
-            defaultStatus: { type: "string", description: "Default status for action=schema add-type." },
-            folder: { type: "string", description: "Storage folder for action=schema add-type." },
-            alias: {
-                type: "array",
-                items: { type: "string" },
-                description: "Aliases for action=schema add-type/add-status.",
-            },
-            role: {
-                type: "array",
-                items: { type: "string" },
-                description: "Lifecycle roles for action=schema add-status: draft, active, blocked, terminal, terminal_done, terminal_canceled, default_open, default_close, default_cancel.",
-            },
-            order: { type: "number", description: "Display/sort order for action=schema add-status." },
-            options: { type: "object", description: "Underlying pm command options using camelCase keys." },
-            fullChangedFields: {
-                type: "boolean",
-                description: "For mutation actions, return the full changed_fields array instead of the default changed_field_count.",
-            },
-            idOnly: {
-                type: "boolean",
-                description: "For single-item mutation actions, return only id and status.",
-            },
-        }, ["action"]),
-    },
-    {
-        name: "pm_context",
-        description: "Return the agent-oriented project context snapshot.",
-        inputSchema: objectSchema({ options: { type: "object" } }),
-    },
-    {
-        name: "pm_search",
-        description: "Search pm items with keyword, semantic, or hybrid search. " +
-            "Defaults to a compact projection for token efficiency. " +
-            "Pass options.mode=keyword|semantic|hybrid, options.limit=N to cap hits, " +
-            "options.fields='id,title,score' for a custom projection, or options.full=true for full item bodies (can be large).",
-        inputSchema: objectSchema({ query: { type: "string" }, options: { type: "object" }, ...SEARCH_TOP_LEVEL_OPTION_PROPERTIES }, ["query"]),
-    },
-    {
-        name: "pm_list",
-        description: "List pm items with status/type/tag/priority filters. Defaults to compact projection for token efficiency. " +
-            "options.status accepts CSV (open,in_progress). " +
-            "Pass options.compact=false or options.includeBody=true for full bodies/comments. " +
-            "Pass options.brief=true for ultra-terse (id/status/type/title only). " +
-            "Pass options.fields='id,title,priority' for custom projection. " +
-            "Pass options.limit=N to cap row count.",
-        inputSchema: objectSchema({ options: { type: "object" }, ...LIST_TOP_LEVEL_OPTION_PROPERTIES }),
-    },
-    {
-        name: "pm_get",
-        description: "Read one pm item. Pass options.depth='brief' or options.fields='id,title,status' for low-token inspection.",
-        inputSchema: objectSchema({
-            id: idSchema,
-            options: { type: "object", description: "Get options such as depth=brief|standard|deep|full or fields=id,title,status." },
-        }, ["id"]),
-    },
-    {
-        name: "pm_create",
-        description: "Create a pm item natively and write pm history. " +
-            "Output is compact by default (changed_fields replaced with changed_field_count for token efficiency); pass fullChangedFields=true for the full changed_fields array.",
-        inputSchema: objectSchema({
-            fullChangedFields: { type: "boolean", description: "Return full changed_fields instead of changed_field_count." },
-            allowMissingParent: { type: "boolean", description: "Allow unresolved parent references and emit a validation warning." },
-            options: { type: "object", description: "Create options. title and description are required." },
-        }, ["options"]),
-    },
-    {
-        name: "pm_copy",
-        description: "Copy an existing pm item into a new id while resetting lifecycle fields. " +
-            "Output is compact by default (changed_fields replaced with changed_field_count); pass fullChangedFields=true for the full changed_fields array.",
-        inputSchema: objectSchema({
-            id: idSchema,
-            fullChangedFields: { type: "boolean", description: "Return full changed_fields instead of changed_field_count." },
-            options: { type: "object", description: "Copy options such as title override, author, and message." },
-        }, ["id"]),
-    },
-    {
-        name: "pm_update",
-        description: "Update pm item metadata/body/dependencies/log seeds natively. " +
-            "Output is compact by default (changed_fields replaced with changed_field_count); pass fullChangedFields=true for the full changed_fields delta.",
-        inputSchema: objectSchema({
-            id: idSchema,
-            fullChangedFields: { type: "boolean", description: "Return full changed_fields instead of changed_field_count." },
-            options: { type: "object" },
-        }, ["id", "options"]),
-    },
-    {
-        name: "pm_claim",
-        description: "Claim a pm item.",
-        inputSchema: objectSchema({ id: idSchema, force: { type: "boolean" }, options: { type: "object" } }, ["id"]),
-    },
-    {
-        name: "pm_release",
-        description: "Release a pm item claim.",
-        inputSchema: objectSchema({ id: idSchema, force: { type: "boolean" }, options: { type: "object" } }, ["id"]),
-    },
-    {
-        name: "pm_close",
-        description: "Close a pm item with optional close reason and optional close validation (reason requirement follows governance settings). " +
-            "Output is compact by default (changed_fields replaced with changed_field_count); pass fullChangedFields=true for the full changed_fields array.",
-        inputSchema: objectSchema({
-            id: idSchema,
-            reason: { type: "string", description: "Close reason text when provided or required by governance settings." },
-            duplicateOf: { type: "string", description: "Canonical item id when closing this item as a duplicate." },
-            fullChangedFields: { type: "boolean", description: "Return full changed_fields instead of changed_field_count." },
-            idOnly: { type: "boolean", description: "Return only id and status." },
-            options: { type: "object" },
-        }, ["id"]),
-    },
-    {
-        name: "pm_comments",
-        description: "List or add comments on a pm item. Use options.add to append. " +
-            "List calls default to the most recent 20 comments with total_count/has_more metadata for token efficiency. " +
-            "Pass options.limit=N to choose a page size, options.limit=0 for summary-only metadata, or options.full=true for full history.",
-        inputSchema: objectSchema({ id: idSchema, options: { type: "object" } }, ["id"]),
-    },
-    {
-        name: "pm_files",
-        description: "List, add, remove, audit, or validate linked files for a pm item.",
-        inputSchema: objectSchema({ id: idSchema, options: { type: "object" } }, ["id"]),
-    },
-    {
-        name: "pm_docs",
-        description: "List, add, or remove linked docs for a pm item.",
-        inputSchema: objectSchema({ id: idSchema, options: { type: "object" } }, ["id"]),
-    },
-    {
-        name: "pm_notes",
-        description: "List or add structured notes on a pm item. Use options.add to append a note; omit it to list existing notes.",
-        inputSchema: objectSchema({ id: idSchema, options: { type: "object" } }, ["id"]),
-    },
-    {
-        name: "pm_learnings",
-        description: "List or add learnings on a pm item. Use options.add to capture a learning/insight; omit it to list existing learnings.",
-        inputSchema: objectSchema({ id: idSchema, options: { type: "object" } }, ["id"]),
-    },
-    {
-        name: "pm_deps",
-        description: "List, add, or remove dependencies for a pm item. Use options.add to declare a dependency and options.remove to drop one; omit both to list current dependencies.",
-        inputSchema: objectSchema({ id: idSchema, options: { type: "object" } }, ["id"]),
-    },
-    {
-        name: "pm_test",
-        description: "List, add, remove, or run linked tests for a pm item.",
-        inputSchema: objectSchema({ id: idSchema, options: { type: "object" } }, ["id"]),
-    },
-    {
-        name: "pm_validate",
-        description: "Run pm validation checks.",
-        inputSchema: objectSchema({ options: { type: "object" } }),
-    },
-    {
-        name: "pm_health",
-        description: "Run pm health diagnostics. Pass options.brief=true for compact low-token details, options.skipIntegrity=true, options.skipDrift=true, options.skipVectors=true for a fast status-only check, or options.full=true for the complete deep check.",
-        inputSchema: objectSchema({ options: { type: "object" } }),
-    },
-    {
-        name: "pm_contracts",
-        description: "Inspect pm command, flag, schema, and availability contracts.",
-        inputSchema: objectSchema({ options: { type: "object" } }),
-    },
-    {
-        name: "pm_plan",
-        description: "Run agent-optimized Plan workflows. options.subcommand selects: create|show|add-step|update-step|complete-step|block-step|reorder-step|remove-step|link|unlink|decision|discovery|validation|resume|approve|materialize. Provide id for all non-create subcommands; provide stepRef for step lifecycle subcommands. Plans store agent-readable steps with dependencies, decisions, discoveries, validation, and resume context.",
-        inputSchema: objectSchema({
-            id: { type: "string", description: "Plan id (required for all subcommands except create)." },
-            stepRef: { type: "string", description: "Step id or order for step lifecycle subcommands." },
-            reorderTo: { type: "number", description: "New order for reorder-step." },
-            options: { type: "object", description: "Plan options including subcommand, stepRef, stepStatus, link, depth, etc." },
-        }),
-    },
-];
+// Tool definitions (TOOLS) live in ./tool-definitions.ts so the `pm contracts`
+// golden-file snapshot can import the surface without loading the server
+// runtime (pm-4os2). This file owns dispatch, normalization, and transport.
 // pm-qxwu: TOOL_SCHEMA_BASE keeps additionalProperties:true so legitimate
 // passthrough keeps working, which means a typo'd top-level arg (e.g.
 // "fullChangedField" missing the trailing "s") is silently swallowed and the
@@ -372,7 +126,7 @@ function globalOptions(args) {
         noPager: true,
     };
 }
-const ARRAY_TO_CSV_FIELDS = new Set(["tags", "blockedBy", "blocked_by", "skills"]);
+const ARRAY_TO_CSV_FIELDS = new Set(["tags", "blockedBy", "blocked_by", "skills", "fields"]);
 const SCALAR_TO_ARRAY_FIELDS = new Set([
     "comment",
     "note",
@@ -455,10 +209,41 @@ function optionsWithAuthor(args, action) {
     else if (action === "close") {
         hoistKey("duplicateOf");
     }
+    else if (action === "append") {
+        // pm-7u9j: the narrow pm_append tool declares `body` top-level; runAppend
+        // reads it from options, so hoist unless options.body already wins.
+        // (pm_schema/pm_config top-level args are consumed directly by runAction's
+        // schema/config cases, which read args before options — no hoist needed.)
+        hoistKey("body");
+    }
     const options = normalizeMcpOptionsArrays({ ...hoistedTopLevel, ...baseOptions }, action);
     const author = readString(args, "author");
     return author && options.author === undefined ? { ...options, author } : options;
 }
+// GH-170 (pm-pfnx): the narrow pm_files/pm_docs tools spell the CLI --note flag
+// as `addNote` (the shared `note` parameter is the array-typed create/update
+// note seed). Translate it onto the runner's `note` option; an explicit
+// options.note (pm_run callers) wins.
+function withAddNoteOption(options) {
+    if (options.addNote === undefined) {
+        return options;
+    }
+    const next = { ...options };
+    if (next.note === undefined && typeof next.addNote === "string") {
+        next.note = next.addNote;
+    }
+    delete next.addNote;
+    return next;
+}
+function withFilesDiscoveryOptions(options) {
+    const next = { ...options };
+    if (next.discoveryNote !== undefined && next.note === undefined && typeof next.discoveryNote === "string") {
+        next.note = next.discoveryNote;
+    }
+    delete next.discover;
+    delete next.discoveryNote;
+    return next;
+}
 function normalizeActionName(value) {
     return value.trim().toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
 }
@@ -743,7 +528,9 @@ async function runAction(args) {
                 listOptions.includeBody === undefined) {
                 listOptions.compact = true;
             }
-            return runList(readString(args, "status"), listOptions, global);
+            // pm-rmjy: echo the applied filters + resolved projection mode so agents
+            // get structured confirmation of what the server actually ran.
+            return withQuerySummary((await runList(readString(args, "status"), listOptions, global)), listOptions);
         }
         case "get":
             return runGet(id ?? readRequiredString(options, "id"), global, options);
@@ -754,7 +541,8 @@ async function runAction(args) {
                 searchOptions.fields === undefined) {
                 searchOptions.compact = true;
             }
-            return runSearch(readRequiredString(args, "query"), searchOptions, global);
+            // pm-rmjy: echo the applied filters + resolved projection mode (see list).
+            return withQuerySummary((await runSearch(readRequiredString(args, "query"), searchOptions, global)), searchOptions);
         }
         case "create": {
             const { changedFields, idOnly, runnerOptions } = withMutationCompaction(args, options);
@@ -802,10 +590,15 @@ async function runAction(args) {
             return runNotes(id ?? readRequiredString(options, "id"), options, global);
         case "learnings":
             return runLearnings(id ?? readRequiredString(options, "id"), options, global);
-        case "files":
-            return runFiles(id ?? readRequiredString(options, "id"), options, global);
+        case "files": {
+            const fileId = id ?? readRequiredString(options, "id");
+            if (options.discover === true) {
+                return runFilesDiscover(fileId, withFilesDiscoveryOptions(options), global);
+            }
+            return runFiles(fileId, withAddNoteOption(options), global);
+        }
         case "docs":
-            return runDocs(id ?? readRequiredString(options, "id"), options, global);
+            return runDocs(id ?? readRequiredString(options, "id"), withAddNoteOption(options), global);
         case "test":
             return runTest(id ?? readRequiredString(options, "id"), options, global);
         case "test-all":
@@ -836,8 +629,15 @@ async function runAction(args) {
         }
         case "contracts":
             return runContracts(options, global);
-        case "config":
-            return runConfig(readString(args, "scope") ?? readString(options, "scope") ?? "project", readString(args, "configAction") ?? readRequiredString(options, "action"), readString(args, "key") ?? readString(options, "key"), options, global, readString(args, "value") ?? readString(options, "value"));
+        case "config": {
+            // pm-v68d: the narrow pm_config tool declares configAction top-level;
+            // options.configAction/options.action remain accepted for pm_run parity.
+            const configAction = readString(args, "configAction") ?? readString(options, "configAction") ?? readString(options, "action");
+            if (configAction === undefined) {
+                throw new PmCliError("Missing required argument: configAction", 64);
+            }
+            return runConfig(readString(args, "scope") ?? readString(options, "scope") ?? "project", configAction, readString(args, "key") ?? readString(options, "key"), options, global, readString(args, "value") ?? readString(options, "value"));
+        }
         case "activity": {
             const activityOptions = { ...options };
             if (activityOptions.compact === undefined) {
@@ -871,8 +671,12 @@ async function runAction(args) {
             return runHistory(id ?? readRequiredString(options, "id"), options, global);
         case "history-redact":
             return runHistoryRedact(id ?? readRequiredString(options, "id"), options, global);
-        case "history-repair":
-            return runHistoryRepair(id ?? readRequiredString(options, "id"), options, global);
+        case "history-repair": {
+            const repairAll = options.all === true;
+            const repairId = id ?? readString(options, "id");
+            assertHistoryRepairTarget(repairId, repairAll);
+            return repairAll ? runHistoryRepairAll(options, global) : runHistoryRepair(repairId, options, global);
+        }
         case "history-compact":
             return runHistoryCompact(id ?? readRequiredString(options, "id"), options, global);
         case "plan": {
@@ -1001,6 +805,7 @@ const HANDLERS = {
     pm_create: (args) => runAction({ ...args, action: "create" }),
     pm_copy: (args) => runAction({ ...args, action: "copy" }),
     pm_update: (args) => runAction({ ...args, action: "update" }),
+    pm_append: (args) => runAction({ ...args, action: "append" }),
     pm_claim: (args) => runAction({ ...args, action: "claim" }),
     pm_release: (args) => runAction({ ...args, action: "release" }),
     pm_close: (args) => runAction({ ...args, action: "close" }),
@@ -1014,6 +819,8 @@ const HANDLERS = {
     pm_validate: (args) => runAction({ ...args, action: "validate" }),
     pm_health: (args) => runAction({ ...args, action: "health" }),
     pm_contracts: (args) => runAction({ ...args, action: "contracts" }),
+    pm_schema: (args) => runAction({ ...args, action: "schema" }),
+    pm_config: (args) => runAction({ ...args, action: "config" }),
     pm_plan: (args) => runAction({ ...args, action: "plan" }),
 };
 function resultContent(result, warnings) {
@@ -1060,9 +867,10 @@ export async function handleRequest(request) {
             serverInfo: { name: "pm-mcp", version: PM_MCP_SERVER_VERSION },
             instructions: "You have access to native pm CLI tools for git-based project management. " +
                 "Use pm_context or pm_search before creating new work. " +
-                "Prefer narrow tools (pm_context, pm_list, pm_get, pm_search, pm_create, pm_copy, pm_update, pm_claim, pm_release, pm_close, pm_comments, pm_files, pm_docs, pm_notes, pm_learnings, pm_deps, pm_test, pm_validate, pm_health, pm_contracts, pm_plan) over pm_run when they cover the operation. " +
+                "Prefer narrow tools (pm_context, pm_list, pm_get, pm_search, pm_create, pm_copy, pm_update, pm_append, pm_claim, pm_release, pm_close, pm_comments, pm_files, pm_docs, pm_notes, pm_learnings, pm_deps, pm_test, pm_validate, pm_health, pm_contracts, pm_schema, pm_config, pm_plan) over pm_run when they cover the operation. " +
                 "Use pm_plan for agent harness Plan workflows: it provides Codex/Claude/Cursor-style planning with durable steps, dependencies, decisions, discoveries, validation, and materialization. " +
-                "Use pm_run with an explicit action for package-owned operations (calendar/templates/guide/dedupe-audit/normalize/reindex/comments-audit/completion/test-runs-list/test-runs-status/test-runs-logs/test-runs-stop/test-runs-resume), plus activity, aggregate, history, stats, append, test-all, and gc. " +
+                "Use pm_schema and pm_config for workspace configuration: pm_schema manages custom item types/statuses and pm_config reads or writes settings keys. " +
+                "Use pm_run with an explicit action for package-owned operations (calendar/templates/guide/dedupe-audit/normalize/reindex/comments-audit/completion/test-runs-list/test-runs-status/test-runs-logs/test-runs-stop/test-runs-resume), plus activity, aggregate, history, stats, test-all, and gc. " +
                 "Use history-redact for audited history-stream redaction workflows, history-repair to re-anchor a drifted history chain, and history-compact to checkpoint/prune long history streams while preserving replay integrity. " +
                 "Set author to 'claude-code-agent' on all mutations. " +
                 "Do not pass path during real repository tracking — only pass path for sandbox or test runs.",
@@ -1158,4 +966,4 @@ if (process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1]) {
     startMcpServer();
 }
 //# sourceMappingURL=server.js.map
-//# debugId=c65aa3d0-c69f-561b-8e23-939348167e21
+//# debugId=e3feb52b-3154-5b9c-85ec-f0639c808233