@unbrained/pm-cli 2026.9.7 → 2026.9.9

package/dist/sdk/workspace.js

@@ -1,129 +1,5 @@
-/**
- * @module sdk/workspace
- *
- * Maintains repository-scaffold contracts shared by the public SDK and CLI.
- */
+!(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]="5b131b40-e139-5a7d-a6ef-633fe2cbee64")}catch(e2){}})();import{isFileMissingError}from"../core/fs/fs-utils.js";import{readFile,writeFile}from"node:fs/promises";import path from"node:path";import{EXIT_CODE}from"../core/shared/constants.js";import{PmCliError}from"../core/shared/errors.js";const PM_GITIGNORE_START="# pm-cli:runtime-cache:start";const PM_GITIGNORE_END="# pm-cli:runtime-cache:end";const PM_GITIGNORE_DEFAULT_TRACKER_ROOT=".agents/pm";const PM_GITIGNORE_RUNTIME_DIRECTORIES=["runtime/","search/","locks/","transactions/","checkpoints/"];const PM_GITIGNORE_TRACKED_FILES=["search/eval-queries.json"];async function withGitignorePermissionRecovery(operation){try{return await operation()}catch(error){if(error instanceof Error&&"code"in error&&typeof error.code==="string"&&["EACCES","EPERM","EROFS"].includes(error.code)){throw new PmCliError("The workspace .gitignore is not writable.",EXIT_CODE.GENERIC_FAILURE,{code:"init_gitignore_unwritable",reason:error.code.toLowerCase(),required:"Grant the current user read and write access to the workspace .gitignore before initialization.",why:"pm init must publish its managed runtime-cache ignore fence without replacing unrelated entries.",nextSteps:["Grant read and write access to the workspace .gitignore and rerun pm init.","If the workspace is intentionally read-only, initialize pm in a writable workspace or clone."]})}throw error}}function normalizeTrackerRelativeRoot(trackerRelativeRoot){return trackerRelativeRoot.replaceAll("\\","/").replace(/^\.\/+/,"").replace(/\/+$/,"")}function isPathOutsideRoot(relativePath){const normalized=relativePath.replaceAll("\\","/");return path.isAbsolute(relativePath)||normalized===".."||normalized.startsWith("../")}function getPmGitignoreBlock(trackerRelativeRoot=PM_GITIGNORE_DEFAULT_TRACKER_ROOT){const root=normalizeTrackerRelativeRoot(trackerRelativeRoot);return[PM_GITIGNORE_START,...PM_GITIGNORE_RUNTIME_DIRECTORIES.map(directory=>directory==="search/"?`${root}/${directory}*`:`${root}/${directory}`),...PM_GITIGNORE_TRACKED_FILES.map(file=>`!${root}/${file}`),PM_GITIGNORE_END].join("\n")}async function ensurePmGitignore(workspaceRoot,options={}){const gitignorePath=path.join(workspaceRoot,".gitignore");let trackerRelativeRoot=PM_GITIGNORE_DEFAULT_TRACKER_ROOT;if(options.pmRoot!==void 0){const relative=normalizeTrackerRelativeRoot(path.relative(path.resolve(workspaceRoot),path.resolve(options.pmRoot)));if(isPathOutsideRoot(relative)){return{path:gitignorePath,changed:false}}if(relative.length>0){trackerRelativeRoot=relative}}let current="";try{current=await withGitignorePermissionRecovery(()=>readFile(gitignorePath,"utf8"))}catch(error){if(!(error instanceof Error&&"code"in error&&isFileMissingError(error))){throw error}}const start=current.indexOf(PM_GITIGNORE_START);const end=current.indexOf(PM_GITIGNORE_END);const withoutManagedBlock=start>=0&&end>=start?`${current.slice(0,start)}${current.slice(end+PM_GITIGNORE_END.length)}`:current;const prefix=withoutManagedBlock.trimEnd();const next=`${prefix.length>0?`${prefix}
 
-!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]="89261a49-97e5-5ffc-a81c-2409f0b529cf")}catch(e){}}();
-import { isFileMissingError } from "../core/fs/fs-utils.js";
-import { readFile, writeFile } from "node:fs/promises";
-import path from "node:path";
-import { EXIT_CODE } from "../core/shared/constants.js";
-import { PmCliError } from "../core/shared/errors.js";
-/** Opening marker for the init-owned ignore block. */
-export const PM_GITIGNORE_START = "# pm-cli:runtime-cache:start";
-/** Closing marker for the init-owned ignore block. */
-export const PM_GITIGNORE_END = "# pm-cli:runtime-cache:end";
-/** Default workspace-relative tracker root used when no custom root is resolved. */
-export const PM_GITIGNORE_DEFAULT_TRACKER_ROOT = ".agents/pm";
-/**
- * Tracker-relative directories that hold per-clone runtime state (caches,
- * search indexes, locks, crash-recovery receipts). They must never be
- * committed: they churn on every command and conflict on every concurrent
- * branch merge. `transactions/` (SDK workspace-transaction journals) and
- * `checkpoints/` (bulk-mutation rollback receipts) are per-branch recovery
- * state with their own GC (`pm gc --scope transactions|checkpoints`), so
- * keeping them untracked is the recorded merge-safety disposition.
- */
-export const PM_GITIGNORE_RUNTIME_DIRECTORIES = [
-    "runtime/",
-    "search/",
-    "locks/",
-    "transactions/",
-    "checkpoints/",
-];
-/** Tracker-relative curated search evidence that remains version controlled. */
-export const PM_GITIGNORE_TRACKED_FILES = ["search/eval-queries.json"];
-/** Convert expected workspace permission failures into stable, path-safe recovery. */
-async function withGitignorePermissionRecovery(operation) {
-    try {
-        return await operation();
-    }
-    catch (error) {
-        if (error instanceof Error &&
-            "code" in error &&
-            typeof error.code === "string" &&
-            ["EACCES", "EPERM", "EROFS"].includes(error.code)) {
-            throw new PmCliError("The workspace .gitignore is not writable.", EXIT_CODE.GENERIC_FAILURE, {
-                code: "init_gitignore_unwritable",
-                reason: error.code.toLowerCase(),
-                required: "Grant the current user read and write access to the workspace .gitignore before initialization.",
-                why: "pm init must publish its managed runtime-cache ignore fence without replacing unrelated entries.",
-                nextSteps: [
-                    "Grant read and write access to the workspace .gitignore and rerun pm init.",
-                    "If the workspace is intentionally read-only, initialize pm in a writable workspace or clone.",
-                ],
-            });
-        }
-        throw error;
-    }
-}
-function normalizeTrackerRelativeRoot(trackerRelativeRoot) {
-    return trackerRelativeRoot
-        .replaceAll("\\", "/")
-        .replace(/^\.\/+/, "")
-        .replace(/\/+$/, "");
-}
-/** Return whether a relative path escapes its owning root, without rejecting valid names such as `..pm`. */
-export function isPathOutsideRoot(relativePath) {
-    const normalized = relativePath.replaceAll("\\", "/");
-    return (path.isAbsolute(relativePath) ||
-        normalized === ".." ||
-        normalized.startsWith("../"));
-}
-/** Return the canonical pm ignore block rendered for the given workspace-relative tracker root (defaults to `.agents/pm`), primarily for documentation and tests. */
-export function getPmGitignoreBlock(trackerRelativeRoot = PM_GITIGNORE_DEFAULT_TRACKER_ROOT) {
-    const root = normalizeTrackerRelativeRoot(trackerRelativeRoot);
-    return [
-        PM_GITIGNORE_START,
-        ...PM_GITIGNORE_RUNTIME_DIRECTORIES.map((directory) => directory === "search/"
-            ? `${root}/${directory}*`
-            : `${root}/${directory}`),
-        ...PM_GITIGNORE_TRACKED_FILES.map((file) => `!${root}/${file}`),
-        PM_GITIGNORE_END,
-    ].join("\n");
-}
-/**
- * Idempotently create or replace the fenced pm cache block in a workspace
- * `.gitignore`. When `pmRoot` is provided the ignored runtime directories are
- * rendered under the resolved workspace-relative tracker root, so custom-root
- * workspaces (`--pm-path`/`PM_PATH`) stop committing runtime caches (GH-598).
- * A tracker root outside the workspace needs no ignore rules here, so the
- * file is left untouched.
- */
-export async function ensurePmGitignore(workspaceRoot, options = {}) {
-    const gitignorePath = path.join(workspaceRoot, ".gitignore");
-    let trackerRelativeRoot = PM_GITIGNORE_DEFAULT_TRACKER_ROOT;
-    if (options.pmRoot !== undefined) {
-        const relative = normalizeTrackerRelativeRoot(path.relative(path.resolve(workspaceRoot), path.resolve(options.pmRoot)));
-        if (isPathOutsideRoot(relative)) {
-            return { path: gitignorePath, changed: false };
-        }
-        if (relative.length > 0) {
-            trackerRelativeRoot = relative;
-        }
-    }
-    let current = "";
-    try {
-        current = await withGitignorePermissionRecovery(() => readFile(gitignorePath, "utf8"));
-    }
-    catch (error) {
-        if (!(error instanceof Error && "code" in error && isFileMissingError(error))) {
-            throw error;
-        }
-    }
-    const start = current.indexOf(PM_GITIGNORE_START);
-    const end = current.indexOf(PM_GITIGNORE_END);
-    const withoutManagedBlock = start >= 0 && end >= start
-        ? `${current.slice(0, start)}${current.slice(end + PM_GITIGNORE_END.length)}`
-        : current;
-    const prefix = withoutManagedBlock.trimEnd();
-    const next = `${prefix.length > 0 ? `${prefix}\n\n` : ""}${getPmGitignoreBlock(trackerRelativeRoot)}\n`;
-    if (next === current) {
-        return { path: gitignorePath, changed: false };
-    }
-    await withGitignorePermissionRecovery(() => writeFile(gitignorePath, next, "utf8"));
-    return { path: gitignorePath, changed: true };
-}
+`:""}${getPmGitignoreBlock(trackerRelativeRoot)}
+`;if(next===current){return{path:gitignorePath,changed:false}}await withGitignorePermissionRecovery(()=>writeFile(gitignorePath,next,"utf8"));return{path:gitignorePath,changed:true}}export{PM_GITIGNORE_DEFAULT_TRACKER_ROOT,PM_GITIGNORE_END,PM_GITIGNORE_RUNTIME_DIRECTORIES,PM_GITIGNORE_START,PM_GITIGNORE_TRACKED_FILES,ensurePmGitignore,getPmGitignoreBlock,isPathOutsideRoot};
 //# sourceMappingURL=workspace.js.map
-//# debugId=89261a49-97e5-5ffc-a81c-2409f0b529cf

package/dist/types/index.js

@@ -1,10 +1,2 @@
-/**
- * @module types/index
- *
- * Defines the shared project-management data model used by CLI, SDK, MCP, and packages.
- */
-
-!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]="f6e82c93-54e8-53a7-94df-10a573aae933")}catch(e){}}();
-export * from "../types.js";
+!(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]="0ca7f52c-fb31-5cd9-b689-a918f4e61816")}catch(e2){}})();export*from"../types.js";
 //# sourceMappingURL=index.js.map
-//# debugId=f6e82c93-54e8-53a7-94df-10a573aae933

package/dist/types.d.ts

@@ -1035,6 +1035,8 @@ export interface AgentGuidanceSettings {
 }
 /** Restricts search mutation refresh policy values accepted by command, SDK, and storage contracts. */
 export type SearchMutationRefreshPolicy = "cache_only" | "semantic_configured" | "semantic_auto";
+/** Restricts the declared default search mode: `auto` derives hybrid-or-keyword from workspace state, a concrete mode pins it. */
+export type SearchDefaultMode = "auto" | "keyword" | "semantic" | "hybrid";
 /** Documents the search query expansion settings payload exchanged by command, SDK, and package integrations. */
 export interface SearchQueryExpansionSettings {
     /** Whether enabled applies to this operation. */
@@ -1208,6 +1210,8 @@ export interface PmSettings {
         embedding_timeout_ms: number;
         scanner_max_batch_retries: number;
         provider?: string;
+        /** Mode a search runs in when the caller passes none: `auto` (default) resolves to hybrid when semantic search is explicitly configured and runnable, keyword otherwise; a concrete mode pins it. Optional on the type so existing settings literals stay valid; readers always normalize it. */
+        default_mode?: SearchDefaultMode;
         /** Optional allow-list of corpus field names embedded for semantic search (see DEFAULT_SEARCH_CORPUS_FIELDS in core/search/corpus.ts). When unset or empty, the full default field set is used (backward compatible). When set, only the named fields are embedded — letting teams opt structured signals (priority, assignee, risk, acceptance_criteria, etc.) in/out for token efficiency. Changing this re-flags items stale on the next refresh. */
         corpus_fields?: string[];
         mutation_refresh_policy: SearchMutationRefreshPolicy;

package/dist/types.js

@@ -1,246 +1,2 @@
-/**
- * @module types
- *
- * Defines the shared project-management data model used by CLI, SDK, MCP, and packages.
- */
-/** Supported values accepted by the builtin item type contract. */
-
-!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]="8173bdb0-39c8-56c0-85c2-5c39f5c213cc")}catch(e){}}();
-export const BUILTIN_ITEM_TYPE_VALUES = [
-    "Epic",
-    "Feature",
-    "Task",
-    "Chore",
-    "Issue",
-    "Decision",
-    "Event",
-    "Reminder",
-    "Milestone",
-    "Meeting",
-    "Plan",
-];
-/** Supported values accepted by the item type contract. */
-export const ITEM_TYPE_VALUES = BUILTIN_ITEM_TYPE_VALUES;
-/** Supported values accepted by the status contract. */
-export const STATUS_VALUES = [
-    "draft",
-    "open",
-    "in_progress",
-    "blocked",
-    "closed",
-    "canceled",
-];
-/** Supported values accepted by the runtime status role contract. */
-export const RUNTIME_STATUS_ROLE_VALUES = [
-    "draft",
-    "active",
-    "blocked",
-    "terminal",
-    "terminal_done",
-    "terminal_canceled",
-    "default_open",
-    "default_close",
-    "default_cancel",
-];
-/** Supported values accepted by the runtime field type contract. */
-export const RUNTIME_FIELD_TYPE_VALUES = [
-    "string",
-    "number",
-    "boolean",
-    "string_array",
-    "array",
-    "object",
-];
-/** Supported values accepted by the runtime field command contract. */
-export const RUNTIME_FIELD_COMMAND_VALUES = [
-    "create",
-    "update",
-    "update_many",
-    "list",
-    "search",
-    "calendar",
-    "context",
-];
-/** Supported values accepted by the runtime unknown field policy contract. */
-export const RUNTIME_UNKNOWN_FIELD_POLICY_VALUES = [
-    "allow",
-    "warn",
-    "reject",
-];
-/** Supported values accepted by the dependency kind contract. */
-export const DEPENDENCY_KIND_VALUES = [
-    "blocks",
-    "parent",
-    "child",
-    "parent_child",
-    "child_of",
-    "related",
-    "related_to",
-    "discovered_from",
-    "blocked_by",
-    "incident_from",
-    "epic",
-    "implements",
-    "recurs_from",
-    "supersedes",
-    "task",
-    "verifies",
-];
-/** Supported values accepted by the scope contract. */
-export const SCOPE_VALUES = ["project", "global"];
-/** Supported values accepted by the risk contract. */
-export const RISK_VALUES = ["low", "medium", "high", "critical"];
-/** Supported values accepted by the issue severity contract. */
-export const ISSUE_SEVERITY_VALUES = [
-    "low",
-    "medium",
-    "high",
-    "critical",
-];
-/** Supported values accepted by the confidence text contract. */
-export const CONFIDENCE_TEXT_VALUES = ["low", "medium", "high"];
-/** Supported values accepted by the item format contract. */
-export const ITEM_FORMAT_VALUES = ["toon", "json_markdown"];
-/** Supported values accepted by the sprint release format policy contract. */
-export const SPRINT_RELEASE_FORMAT_POLICY_VALUES = [
-    "warn",
-    "strict_error",
-];
-/** Supported values accepted by the parent reference policy contract. */
-export const PARENT_REFERENCE_POLICY_VALUES = ["warn", "strict_error"];
-/** Supported values accepted by the validate metadata profile contract. */
-export const VALIDATE_METADATA_PROFILE_VALUES = [
-    "core",
-    "strict",
-    "custom",
-];
-/** Supported values accepted by the governance preset contract. */
-export const GOVERNANCE_PRESET_VALUES = [
-    "minimal",
-    "default",
-    "strict",
-    "custom",
-];
-/** Supported values accepted by the governance ownership enforcement contract. */
-export const GOVERNANCE_OWNERSHIP_ENFORCEMENT_VALUES = [
-    "none",
-    "warn",
-    "strict",
-];
-/** Supported values accepted by the governance create mode default contract. */
-export const GOVERNANCE_CREATE_MODE_DEFAULT_VALUES = [
-    "progressive",
-    "strict",
-];
-/** Supported values accepted by the governance close validation default contract. */
-export const GOVERNANCE_CLOSE_VALIDATION_DEFAULT_VALUES = [
-    "off",
-    "warn",
-    "strict",
-];
-/** Supported values accepted by the governance workflow enforcement contract. */
-export const GOVERNANCE_WORKFLOW_ENFORCEMENT_VALUES = [
-    "off",
-    "warn",
-    "strict",
-];
-/** Supported create/copy near-duplicate governance modes. */
-export const GOVERNANCE_DUPLICATE_DETECTION_MODE_VALUES = [
-    "off",
-    "advisory",
-    "strict",
-];
-/** Supported values accepted by the validate metadata required field contract. */
-export const VALIDATE_METADATA_REQUIRED_FIELD_VALUES = [
-    "author",
-    "acceptance_criteria",
-    "estimated_minutes",
-    "close_reason",
-    "reviewer",
-    "risk",
-    "confidence",
-    "sprint",
-    "release",
-];
-/** Supported values accepted by the recurrence frequency contract. */
-export const RECURRENCE_FREQUENCY_VALUES = [
-    "daily",
-    "weekly",
-    "monthly",
-    "yearly",
-];
-/** Supported values accepted by the recurrence weekday contract. */
-export const RECURRENCE_WEEKDAY_VALUES = [
-    "mon",
-    "tue",
-    "wed",
-    "thu",
-    "fri",
-    "sat",
-    "sun",
-];
-/** Canonical week-order index for a recurrence weekday (mon=0 .. sun=6). Shared by item serialization, create/update parsing, and calendar expansion so weekday ordering cannot drift between those modules. */
-export function weekdayOrderIndex(value) {
-    return RECURRENCE_WEEKDAY_VALUES.indexOf(value);
-}
-/** Supported values accepted by the plan mode contract. */
-export const PLAN_MODE_VALUES = [
-    "draft",
-    "research",
-    "review",
-    "approved",
-    "executing",
-    "paused",
-    "completed",
-    "superseded",
-];
-/** Supported values accepted by the plan step status contract. */
-export const PLAN_STEP_STATUS_VALUES = [
-    "pending",
-    "in_progress",
-    "completed",
-    "blocked",
-    "skipped",
-    "superseded",
-];
-/** Supported values accepted by the plan harness contract. */
-export const PLAN_HARNESS_VALUES = [
-    "codex",
-    "claude-code",
-    "cursor",
-    "generic",
-];
-/** Supported values accepted by the plan step link kind contract. */
-export const PLAN_STEP_LINK_KIND_VALUES = [
-    "related",
-    "blocks",
-    "blocked_by",
-    "depends_on",
-    "discovered_from",
-    "implements",
-    "recurs_from",
-    "verifies",
-    "supersedes",
-];
-/** Supported values accepted by the context depth contract. */
-export const CONTEXT_DEPTH_VALUES = [
-    "brief",
-    "standard",
-    "deep",
-    "full",
-];
-/** Supported values accepted by the context section contract. */
-export const CONTEXT_SECTION_VALUES = [
-    "hierarchy",
-    "activity",
-    "progress",
-    "recently_created",
-    "unparented",
-    "blockers",
-    "files",
-    "workload",
-    "staleness",
-    "tests",
-];
+!(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]="2c4c36ad-958a-59e6-9bd7-99458b182dbe")}catch(e2){}})();const BUILTIN_ITEM_TYPE_VALUES=["Epic","Feature","Task","Chore","Issue","Decision","Event","Reminder","Milestone","Meeting","Plan"];const ITEM_TYPE_VALUES=BUILTIN_ITEM_TYPE_VALUES;const STATUS_VALUES=["draft","open","in_progress","blocked","closed","canceled"];const RUNTIME_STATUS_ROLE_VALUES=["draft","active","blocked","terminal","terminal_done","terminal_canceled","default_open","default_close","default_cancel"];const RUNTIME_FIELD_TYPE_VALUES=["string","number","boolean","string_array","array","object"];const RUNTIME_FIELD_COMMAND_VALUES=["create","update","update_many","list","search","calendar","context"];const RUNTIME_UNKNOWN_FIELD_POLICY_VALUES=["allow","warn","reject"];const DEPENDENCY_KIND_VALUES=["blocks","parent","child","parent_child","child_of","related","related_to","discovered_from","blocked_by","incident_from","epic","implements","recurs_from","supersedes","task","verifies"];const SCOPE_VALUES=["project","global"];const RISK_VALUES=["low","medium","high","critical"];const ISSUE_SEVERITY_VALUES=["low","medium","high","critical"];const CONFIDENCE_TEXT_VALUES=["low","medium","high"];const ITEM_FORMAT_VALUES=["toon","json_markdown"];const SPRINT_RELEASE_FORMAT_POLICY_VALUES=["warn","strict_error"];const PARENT_REFERENCE_POLICY_VALUES=["warn","strict_error"];const VALIDATE_METADATA_PROFILE_VALUES=["core","strict","custom"];const GOVERNANCE_PRESET_VALUES=["minimal","default","strict","custom"];const GOVERNANCE_OWNERSHIP_ENFORCEMENT_VALUES=["none","warn","strict"];const GOVERNANCE_CREATE_MODE_DEFAULT_VALUES=["progressive","strict"];const GOVERNANCE_CLOSE_VALIDATION_DEFAULT_VALUES=["off","warn","strict"];const GOVERNANCE_WORKFLOW_ENFORCEMENT_VALUES=["off","warn","strict"];const GOVERNANCE_DUPLICATE_DETECTION_MODE_VALUES=["off","advisory","strict"];const VALIDATE_METADATA_REQUIRED_FIELD_VALUES=["author","acceptance_criteria","estimated_minutes","close_reason","reviewer","risk","confidence","sprint","release"];const RECURRENCE_FREQUENCY_VALUES=["daily","weekly","monthly","yearly"];const RECURRENCE_WEEKDAY_VALUES=["mon","tue","wed","thu","fri","sat","sun"];function weekdayOrderIndex(value){return RECURRENCE_WEEKDAY_VALUES.indexOf(value)}const PLAN_MODE_VALUES=["draft","research","review","approved","executing","paused","completed","superseded"];const PLAN_STEP_STATUS_VALUES=["pending","in_progress","completed","blocked","skipped","superseded"];const PLAN_HARNESS_VALUES=["codex","claude-code","cursor","generic"];const PLAN_STEP_LINK_KIND_VALUES=["related","blocks","blocked_by","depends_on","discovered_from","implements","recurs_from","verifies","supersedes"];const CONTEXT_DEPTH_VALUES=["brief","standard","deep","full"];const CONTEXT_SECTION_VALUES=["hierarchy","activity","progress","recently_created","unparented","blockers","files","workload","staleness","tests"];export{BUILTIN_ITEM_TYPE_VALUES,CONFIDENCE_TEXT_VALUES,CONTEXT_DEPTH_VALUES,CONTEXT_SECTION_VALUES,DEPENDENCY_KIND_VALUES,GOVERNANCE_CLOSE_VALIDATION_DEFAULT_VALUES,GOVERNANCE_CREATE_MODE_DEFAULT_VALUES,GOVERNANCE_DUPLICATE_DETECTION_MODE_VALUES,GOVERNANCE_OWNERSHIP_ENFORCEMENT_VALUES,GOVERNANCE_PRESET_VALUES,GOVERNANCE_WORKFLOW_ENFORCEMENT_VALUES,ISSUE_SEVERITY_VALUES,ITEM_FORMAT_VALUES,ITEM_TYPE_VALUES,PARENT_REFERENCE_POLICY_VALUES,PLAN_HARNESS_VALUES,PLAN_MODE_VALUES,PLAN_STEP_LINK_KIND_VALUES,PLAN_STEP_STATUS_VALUES,RECURRENCE_FREQUENCY_VALUES,RECURRENCE_WEEKDAY_VALUES,RISK_VALUES,RUNTIME_FIELD_COMMAND_VALUES,RUNTIME_FIELD_TYPE_VALUES,RUNTIME_STATUS_ROLE_VALUES,RUNTIME_UNKNOWN_FIELD_POLICY_VALUES,SCOPE_VALUES,SPRINT_RELEASE_FORMAT_POLICY_VALUES,STATUS_VALUES,VALIDATE_METADATA_PROFILE_VALUES,VALIDATE_METADATA_REQUIRED_FIELD_VALUES,weekdayOrderIndex};
 //# sourceMappingURL=types.js.map
-//# debugId=8173bdb0-39c8-56c0-85c2-5c39f5c213cc

package/docs/AGENT_GUIDE.md

@@ -288,7 +288,7 @@ Use these defaults unless the task requires otherwise:
 Concurrent agents work on ordinary Git branches/worktrees; tracker artifacts need the semantic merge contract from [Merge Safety](MERGE_SAFETY.md). The short loop:
 
 - After a fresh clone or new worktree, run `pm merge install` once so the field-aware merge drivers back the committed `.gitattributes` fence.
-- After every merge that touches `.agents/pm`, run `pm merge reconcile --dry-run --json`, review the receipt classification, then apply `pm merge reconcile`. Add `--force` only after explicitly accepting or re-applying every discarded scalar value. Finish with `pm validate --check-storage-integrity` and `pm history --verify --strict-exit`.
+- After every merge that touches `.agents/pm`, run `pm merge reconcile --dry-run --json`, review the receipt classification, then apply `pm merge reconcile`. Add `--force` only after explicitly accepting or re-applying every discarded scalar value. Finish with `pm validate --check-storage-integrity --check-history-drift`, then `pm history <id> --verify --strict-exit` for each affected stream (`_workspace` for workspace state).
 - Repositories fanning out many branches between merges should raise id entropy: `pm config project set ids_token_length 6`.
 - Use `--add-ac`/`--remove-ac` (not `--ac`) so concurrent acceptance-criteria edits merge instead of clobbering.
 

package/docs/COMMANDS.md

@@ -254,6 +254,16 @@ Use only one updated-at window per list call: `--today`, `--recent`, and `--upda
 
 Keyword mode now applies the configured `search.max_results` default (50) when `--limit` is omitted, so a broad query no longer returns every hit. When the limit drops rows the result adds a top-level `total` (pre-limit match count).
 
+### Default search mode (pm-n8a6e7)
+
+A bare `pm search` runs in the mode the SDK resolves from `search.default_mode`, never from a literal in the CLI. `auto` (the default) picks `hybrid` exactly when the stored settings name the active embedding provider (`search.provider`, the same `configured` verdict `pm health` reports) and a vector store or extension adapter resolves, or when an extension search provider is active; every other workspace runs `keyword`. Auto-detected Ollama/LanceDB runtime defaults do not count as configured, so an unconfigured host never pays an embedding round-trip it did not ask for. A concrete `search.default_mode` (`keyword`, `semantic`, `hybrid`) pins the answer, and `--mode` always wins. The result reports `mode` (what ran, after any runtime fallback) beside `mode_source` (`explicit`, `settings`, or `auto`), so a caller can tell a chosen mode from a derived one (compact responses carry `mode_source` only for `settings`, since `explicit` is the caller's own choice and `auto` is the documented default); when the provider is unreachable a hybrid default still degrades to keyword hits with the usual `search_semantic_fallback` warning.
+
+```bash
+pm search "context budget"                       # auto: hybrid here because search.provider is configured and the index resolves
+pm config project set search_default_mode keyword   # pin keyword for a workspace that prefers exact-token results
+pm search "context budget" --mode semantic       # explicit request, mode_source: explicit
+```
+
 ```bash
 pm search "reminder validation queue" --match-mode and          # require all three tokens
 pm search "exact title phrase" --match-mode exact               # contiguous-phrase match

package/docs/CONFIGURATION.md

@@ -388,6 +388,16 @@ Advanced relevance tuning is opt-in:
 When query expansion or rerank providers fail, `pm search` degrades gracefully and keeps the query runnable; warning codes are emitted in the result payload.
 `pm search` filter metadata now reports `query_expansion_*` and `rerank_*` fields so automation can detect when advanced tuning is active.
 
+`search.default_mode` decides the mode a bare `pm search` runs in (`--mode` always wins):
+
+| Value                | Behavior                                                                                                                                                          |
+| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `auto`               | default; `hybrid` when `search.provider` names the active embedding provider and a vector store or extension adapter resolves (or an extension search provider is active), `keyword` otherwise |
+| `keyword`            | pin exact-token ranking for every bare search                                                                                                                     |
+| `semantic`, `hybrid` | pin the semantic path; an unreachable provider still degrades to keyword hits with a `search_semantic_fallback` warning                                            |
+
+Every search result reports `mode_source` (`explicit`, `settings`, or `auto`) beside the effective `mode`.
+
 Mutation commands invalidate keyword search caches immediately. Semantic vector refresh is controlled by `search.mutation_refresh_policy`:
 
 | Policy                | Behavior                                                                                                            |
@@ -399,6 +409,7 @@ Mutation commands invalidate keyword search caches immediately. Semantic vector
 Useful commands:
 
 ```bash
+pm config project set search_default_mode keyword
 pm config project set search_mutation_refresh_policy cache_only
 pm config project set search_embedding_corpus_max_characters 12000
 pm config project set search_query_expansion_enabled true
@@ -468,7 +479,7 @@ pm config project set qdrant_api_key '<QDRANT_API_KEY>'   # omit on unauthentica
 
 After changing any of these, run `pm reindex --mode hybrid` so the vector index reflects the new provider/store. `pm search ... --mode semantic|hybrid` emits a `vector_index_stale` warning when items have been modified since the last reindex.
 
-**Refresh contract (important for agents):** by default a mutation (`pm create`/`pm update`) does **not** synchronously re-embed the changed item, so a brand-new item is absent from `--mode semantic|hybrid` results until the next `pm reindex`. This keeps writes fast. Control the tradeoff with `search.mutation_refresh_policy`: `cache_only` (never refresh on write — fastest), `semantic_auto` (refresh when implicit Ollama/LanceDB defaults are active), or `semantic_configured` (refresh only when semantic search is explicitly configured). Keyword mode (`--mode keyword`, the default) always reflects writes immediately because it reads items directly.
+**Refresh contract (important for agents):** by default a mutation (`pm create`/`pm update`) does **not** synchronously re-embed the changed item, so a brand-new item is absent from `--mode semantic|hybrid` results until the next `pm reindex`. This keeps writes fast. Control the tradeoff with `search.mutation_refresh_policy`: `cache_only` (never refresh on write — fastest), `semantic_auto` (refresh when implicit Ollama/LanceDB defaults are active), or `semantic_configured` (refresh only when semantic search is explicitly configured). Keyword mode (`--mode keyword`, or the `auto` default on a workspace without a configured semantic provider) always reflects writes immediately because it reads items directly.
 
 ## Custom Item Types