@unbrained/pm-cli 2026.8.9 → 2026.8.11

package/docs/SDK_EVIDENCE_TRACEABILITY.md

@@ -12,6 +12,8 @@ Use `pm files lookup` with one or more project-relative or absolute paths:
 pm files lookup src/sdk/files.ts
 pm files lookup src/sdk/files.ts docs/SDK_EVIDENCE_TRACEABILITY.md --limit 20
 pm files lookup /absolute/project/src/sdk/files.ts --scope project --strict-read --json
+pm files lookup src/sdk/files.ts --explain
+pm files lookup src/sdk/files.ts --lines 650:720 --decision-depth 12 --json
 ```
 
 The command normalizes in-project absolute paths to project-relative paths, deduplicates targets, and returns referencing items in deterministic priority, update-time, and ID order. The default result limit is 50. Use `--offset` for bounded pagination or `--no-truncate` for an authoritative unbounded source scan.
@@ -26,6 +28,34 @@ Every response includes:
 
 `--strict-read` fails instead of returning partial source-scan results. Indexed reads are intentionally reported as `unchecked`: they are cursor-bound projections optimized for bounded context retrieval, while strict reads force authoritative item loading.
 
+## Explain why source exists
+
+`--explain` upgrades reverse lookup from an ownership list to a bounded context
+projection. Every match adds:
+
+- its linked-file evidence and compact `value`, `why_now`, `outcome`, and
+  `objective` rationale;
+- the shortest typed relationship path to a governing Decision, including
+  inverse edge names when traversal crosses an edge backwards;
+- a deterministic relevance score used before normal priority, update-time,
+  and id tie-breakers; and
+- explicit ambiguity codes when Git attribution is unavailable, selected lines
+  have no mapped commit, no governing Decision is reachable, or several
+  equally short Decisions exist.
+
+`--lines start:end` is an inclusive, one-based selector that implies
+`--explain` and accepts exactly one path. It runs bounded `git blame` and a
+256-commit path log. A blamed commit contributes only when its commit message
+contains the exact pm item id, so Git history supplements linked tracker
+evidence without inventing lineage. Git failures are non-fatal and appear as
+ambiguity rather than silently claiming attribution. `--decision-depth` is
+bounded from 1 through 32 and defaults to 8.
+
+The top-level `traceability_receipt` reports the requested range, blamed,
+mapped, and unmapped commit counts, and effective decision depth. Explained
+lookups use an authoritative source scan because a compact metadata index does
+not contain the rationale and graph fields required to support the answer.
+
 ## SDK and MCP
 
 The public SDK exposes both reusable-client and one-shot forms:
@@ -37,6 +67,9 @@ const client = new PmClient({ cwd: process.cwd() });
 const fromClient = await client.filesLookup({
   paths: ["src/sdk/files.ts"],
   limit: 20,
+  explain: true,
+  lineRange: { start: 650, end: 720 },
+  decisionDepth: 12,
 });
 
 const oneShot = await filesLookup(
@@ -45,7 +78,12 @@ const oneShot = await filesLookup(
 );
 ```
 
-The MCP `files` action uses the same primitive when `lookupPath` is present. `id` remains required for item-local add, remove, discover, and list operations; reverse lookup instead requires one or more `lookupPath` values. Use `pm contracts --command files --flags-only --json` for the active machine contract.
+The MCP `files` action uses the same primitive when `lookupPath` is present and
+accepts `explain`, `lines`, and `decisionDepth`. The dedicated `files_lookup`
+tool exposes the same fields. `id` remains required for item-local add, remove,
+discover, and list operations; reverse lookup instead requires one or more
+`lookupPath` values. Use `pm contracts --command files --flags-only --json` for
+the active machine contract.
 
 SDK hosts that manage authoritative item writes directly can use `queryLinkedFileMetadataIndex` from the public item-metadata-index surface. The reverse projection is rebuilt from linked-file collections and updated in the same derived-index writer section as normal metadata deltas. A missing, stale, corrupt, or extension-incompatible index must fall back to authoritative reads.
 

package/docs/SDK_RUNTIME_BOUNDARIES.md

@@ -2,7 +2,11 @@
 
 Tracker: [pm-1eted6](../.agents/pm/issues/pm-1eted6.toon),
 [pm-3lhth4](../.agents/pm/issues/pm-3lhth4.toon), and
-[pm-0xmajx](../.agents/pm/issues/pm-0xmajx.toon).
+[pm-0xmajx](../.agents/pm/issues/pm-0xmajx.toon). Refusal reachability and
+recovery completeness are tracked by
+[pm-elmpav](../.agents/pm/features/pm-elmpav.toon),
+[pm-185870](../.agents/pm/issues/pm-185870.toon), and
+[pm-yqe0mo](../.agents/pm/issues/pm-yqe0mo.toon).
 
 These SDK primitives keep host and project-runtime policy consistent across the
 bundled CLI, packages, and automation without requiring consumers to reproduce
@@ -56,3 +60,34 @@ guidance when presenting refusals as human-readable or structured output.
 Host-only validation remains at the transport boundary, while rules shared by
 packages and commands live in public SDK primitives so callers receive the
 same refusal contract regardless of entrypoint.
+
+`createUnknownSubcommandError` is the shared constructor for positional command
+families. It emits `unknown_subcommand` with the stable
+`unknown_positional_token` reason, a complete sorted `allowed_values` set, the
+attempted command, and a nearest copy-pasteable retry when edit distance gives
+an unambiguous candidate. CLI, direct SDK dispatch, MCP, and package hosts use
+the same primitive. The CLI also recognizes split schema actions such as
+`schema add type Name` and recommends the declared `schema add-type Name`
+form instead of collapsing the failure into a generic arity error.
+Core graph, config, plan, schema, profile, merge, telemetry, workspace, and
+package/extension lifecycle dispatchers use this contract. The bundled
+templates package demonstrates the same primitive for package-registered
+families; custom packages can import it from the public SDK instead of
+inventing a private refusal envelope. The former `unknown_lifecycle_action`
+catalog name remains a compatibility alias of `unknown_subcommand`.
+
+`PmErrorCodeContract.owned_states` declares concrete refusal states, their
+probe ids, reachable entrypoints, and expected exit classes. The generated
+catalog joins those declarations to the discovered error-code inventory.
+Package and test harnesses can pass real-entrypoint observations to
+`verifyPmRefusalReachability`; missing probes, wrong codes, wrong exit classes,
+and undeclared observations fail closed. This makes an error code's existence
+and its runtime reachability independently testable.
+
+Unknown-option recovery separates human and machine budgets. Human guidance
+shows the first three ranked command paths plus an explicit remainder count.
+The structured envelope returns up to twelve ranked paths alongside
+`candidate_commands_total` and `candidate_commands_truncated`, ordered by
+shared option vocabulary and then command path. Consumers must inspect another
+command contract before changing operations; candidate discovery is not an
+instruction to run a different command.

package/docs/TESTING.md

@@ -242,12 +242,12 @@ baseline, scorer tests, and SDK documentation together.
 Tracked by [pm-k6t4yb](../.agents/pm/tasks/pm-k6t4yb.toon) and
 [pm-b2hc4x](../.agents/pm/tasks/pm-b2hc4x.toon).
 
-Every named workflow step that makes a build, test, quality, security, package,
-or release claim is discovered and matched exactly against
-`scripts/release/gate-registry.json`. Each registry entry declares:
+Every workflow job is discovered by its stable `workflow-file#job-id` identity
+and matched exactly against `scripts/release/gate-registry.json`; human-facing
+step names never define the inventory. Each registry entry declares:
 
 - a canonical pm owner;
-- the enforced workflow steps it owns;
+- the enforced workflow jobs it participates in;
 - actionable failure taxonomy;
 - explicit bypass policy and audit rationale;
 - an executable negative-control test and assertion.
@@ -259,11 +259,14 @@ pnpm quality:gate-registry
 node scripts/release/gate-registry.mjs --inventory
 ```
 
-`pnpm quality:static` includes the registry. A newly named workflow gate fails
-until it has an owner and negative-control proof; a removed or renamed workflow
-step also fails until stale policy is reconciled. Public source claims are
-mapped to exact evidence strings and an enforced registry entry so
-documentation cannot silently advertise advisory behavior.
+`pnpm quality:static` includes the registry. A new workflow job fails until it
+is declared under at least one canonical gate, and a removed or renamed job id
+fails until stale policy is reconciled. Display-name edits do not mutate gate
+identity. Public source claims are mapped to exact evidence strings and an
+enforced registry entry so documentation cannot silently advertise advisory
+behavior.
+The inventory output lists registry-derived `registered` job IDs beside the
+parsed `workflow_jobs`; validation requires the two sets to match exactly.
 
 ## Tracker Context-Quality Ratchets
 

package/docs/agent-task-token-baseline.json

@@ -14,12 +14,12 @@
     },
     {
       "id": "returning-agent",
-      "max_estimated_tokens": 383
+      "max_estimated_tokens": 597
     },
     {
       "id": "failing-command",
       "max_estimated_tokens": 197
     }
   ],
-  "composite_max_estimated_tokens": 2437
+  "composite_max_estimated_tokens": 2651
 }

package/docs/generated/AGENT_COMMAND_SURFACE.md

@@ -62,6 +62,7 @@ This file is generated from `PM_COMMAND_VISIBILITY_CONTRACTS`. Do not edit it ma
 | `stats` | full |
 | `health` | standard |
 | `validate` | core |
+| `assurance` | full |
 | `gc` | full |
 | `workspace` | full |
 | `contracts` | standard |

package/marketplace.json

@@ -6,14 +6,14 @@
   },
   "metadata": {
     "description": "Official marketplace for pm CLI — native git-based project management for Claude Code and AI coding agents.",
-    "version": "2026.8.9"
+    "version": "2026.8.11"
   },
   "plugins": [
     {
       "name": "pm-claude",
       "source": "./plugins/pm-claude",
       "description": "Native pm CLI integration for Claude Code — 28 MCP tools, 5 workflow skills, 14 slash commands, 4 subagents, hybrid TUI task tracking, session context injection, and coordination subagents for git-based project management without leaving Claude Code.",
-      "version": "2026.8.9",
+      "version": "2026.8.11",
       "author": {
         "name": "unbrained",
         "url": "https://github.com/unbraind/pm-cli"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-cli",
-  "version": "2026.8.9",
+  "version": "2026.8.11",
   "description": "Git-native project management CLI for humans and agents.",
   "type": "module",
   "packageManager": "pnpm@11.10.0",
@@ -120,7 +120,7 @@
     "lint:complexity:baseline": "eslint . --suppress-rule complexity --suppress-rule sonarjs/cognitive-complexity",
     "lint:duplicates": "jscpd --config .jscpd.json",
     "lint:codefactor": "pnpm quality:static",
-    "quality:static": "pnpm build && pnpm exec tsx scripts/release/static-quality-gate.mts --max-eslint-suppressions 114 --max-coverage-ignore-pragmas 477 --min-docstring-coverage 100 --min-exported-docstring-coverage 100 --min-member-docstring-coverage 100 && node scripts/release/audit-package-boundary.mjs && node scripts/release/package-sdk-contract-parity.mjs && node scripts/release/surface-replication-gate.mjs && node scripts/release/token-budget-gate.mjs && node scripts/release/context-intent-calibration-gate.mjs && node scripts/release/tracker-measurement-gate.mjs && node scripts/release/gate-registry.mjs && node scripts/sdk-surface-snapshot.mjs --check && node scripts/bench/sdk-entrypoint-costs.mjs --check && node scripts/bench/cli-transport-floor.mjs --check",
+    "quality:static": "pnpm build && pnpm exec tsx scripts/release/static-quality-gate.mts --max-eslint-suppressions 114 --max-coverage-ignore-pragmas 477 --min-docstring-coverage 100 --min-exported-docstring-coverage 100 --min-member-docstring-coverage 100 && node scripts/release/audit-package-boundary.mjs && node scripts/release/package-sdk-contract-parity.mjs && node scripts/release/surface-replication-gate.mjs && node scripts/release/absence-tolerance-gate.mjs && node scripts/release/token-budget-gate.mjs && node scripts/release/context-intent-calibration-gate.mjs && node scripts/release/tracker-measurement-gate.mjs && node scripts/release/gate-registry.mjs && node scripts/sdk-surface-snapshot.mjs --check && node scripts/bench/sdk-entrypoint-costs.mjs --check && node scripts/bench/cli-transport-floor.mjs --check",
     "quality:token-budget": "node scripts/release/token-budget-gate.mjs",
     "quality:token-surface": "node scripts/measure-agent-token-surface.mjs --check",
     "quality:token-surface:update": "pnpm build && node scripts/measure-agent-token-surface.mjs --update",
@@ -133,6 +133,7 @@
     "quality:tracker-measurements": "pnpm build && node scripts/release/tracker-measurement-gate.mjs",
     "quality:package-artifact": "pnpm build && node scripts/release/package-artifact-gate.mjs",
     "quality:surface-replication": "node scripts/release/surface-replication-gate.mjs",
+    "quality:absence-tolerance": "node scripts/release/absence-tolerance-gate.mjs",
     "quality:docs-skills": "node scripts/release/docs-skills-gate.mjs",
     "quality:docs-links": "node scripts/release/docs-skills-gate.mjs --links-only",
     "quality:hosted-analysis": "node scripts/release/hosted-analysis-gate.mjs",
@@ -160,8 +161,8 @@
     "version:next": "node scripts/release-version.mjs next",
     "version:sync": "node scripts/sync-versions.mjs apply",
     "changelog:pm:install": "node dist/cli.js install npm:pm-changelog --project",
-    "changelog:pm": "pnpm changelog:pm:install && node dist/cli.js changelog generate --output CHANGELOG.md --title \"Changelog\" --mode replace --all-release-tags --status closed --item-url-base https://github.com/unbraind/pm-cli/blob/main/.agents/pm",
-    "changelog:pm:check": "pnpm changelog:pm:install && node dist/cli.js changelog generate --output CHANGELOG.md --title \"Changelog\" --mode replace --all-release-tags --status closed --item-url-base https://github.com/unbraind/pm-cli/blob/main/.agents/pm --check",
+    "changelog:pm": "pnpm changelog:pm:install && node dist/cli.js changelog generate --output CHANGELOG.md --title \"Changelog\" --mode replace --all-release-tags --status closed --exclude-tag changelog-exclude --item-url-base https://github.com/unbraind/pm-cli/blob/main/.agents/pm",
+    "changelog:pm:check": "pnpm changelog:pm:install && node dist/cli.js changelog generate --output CHANGELOG.md --title \"Changelog\" --mode replace --all-release-tags --status closed --exclude-tag changelog-exclude --item-url-base https://github.com/unbraind/pm-cli/blob/main/.agents/pm --check",
     "release:notes": "node scripts/generate-release-notes.mjs",
     "release:gates": "node scripts/release/run-gates.mjs --telemetry-mode best-effort",
     "verify:preflight": "node scripts/release/run-gates.mjs --telemetry-mode best-effort",
@@ -210,11 +211,11 @@
     "@codspeed/vitest-plugin": "^5.7.1",
     "@eslint/js": "^10.0.1",
     "@sentry/cli": "^3.6.2",
-    "@types/node": "^26.1.2",
+    "@types/node": "^26.2.0",
     "@types/npm-package-arg": "^6.1.4",
     "@vitest/coverage-v8": "^4.1.10",
     "esbuild": "0.28.1",
-    "eslint": "^10.8.0",
+    "eslint": "^10.8.1",
     "eslint-plugin-sonarjs": "^4.2.0",
     "eslint-plugin-unicorn": "^73.0.0",
     "fast-check": "^4.9.0",

package/packages/pm-beads/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-beads",
-  "version": "2026.8.9",
+  "version": "2026.8.11",
   "private": true,
   "type": "module",
   "description": "First-party pm package for importing Beads JSONL records.",

package/packages/pm-calendar/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-calendar",
-  "version": "2026.8.9",
+  "version": "2026.8.11",
   "private": true,
   "type": "module",
   "description": "First-party pm package for calendar and agenda views.",

package/packages/pm-command-kit/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-command-kit",
-  "version": "2026.8.9",
+  "version": "2026.8.11",
   "private": true,
   "type": "module",
   "description": "First-party pm exemplar package for the commands capability: registerCommand, registerFlags, and registerParser.",

package/packages/pm-digital-twin/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-digital-twin",
-  "version": "2026.8.9",
+  "version": "2026.8.11",
   "private": true,
   "type": "module",
   "description": "Beyond-PM exemplar: a temporal production-facility digital twin built entirely on public pm SDK and extension primitives.",

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

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-governance-audit",
-  "version": "2026.8.9",
+  "version": "2026.8.11",
   "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.8.9",
+  "version": "2026.8.11",
   "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.8.9",
+  "version": "2026.8.11",
   "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.8.9",
+  "version": "2026.8.11",
   "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.8.9",
+  "version": "2026.8.11",
   "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.8.9",
+  "version": "2026.8.11",
   "private": true,
   "type": "module",
   "description": "First-party pm package for semantic, hybrid, and reindex search workflows.",

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

@@ -8,6 +8,7 @@ import type {
   ExtensionApi,
   GlobalOptions,
 } from "@unbrained/pm-cli/sdk";
+import { createUnknownSubcommandError } from "@unbrained/pm-cli/sdk";
 import {
   runTemplatesList as runTemplatesListPackage,
   runTemplatesSave as runTemplatesSavePackage,
@@ -53,9 +54,14 @@ function assertListInvocation(
 ): void {
   const unexpectedSubcommand = args.find((arg) => arg.trim().length > 0);
   if (unexpectedSubcommand) {
-    throw new Error(
-      `Unknown pm templates subcommand "${unexpectedSubcommand}". Allowed: list, save, show. Apply a saved template with pm create <type> <title> --template <name>.`,
-    );
+    throw createUnknownSubcommandError({
+      command_path: "templates",
+      token: unexpectedSubcommand,
+      allowed: ["list", "save", "show"],
+      message_suffix:
+        ". Apply a saved template with pm create <type> <title> --template <name>.",
+      examples: ["pm create <type> <title> --template <name>"],
+    });
   }
   const unexpectedOptions = optionKeys(options);
   if (unexpectedOptions.length > 0) {

package/packages/pm-templates/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-templates",
-  "version": "2026.8.9",
+  "version": "2026.8.11",
   "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.8.9",
+  "version": "2026.8.11",
   "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.8.9",
+  "version": "2026.8.11",
   "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.8.9",
+  "version": "2026.8.11",
   "author": {
     "name": "unbrained",
     "url": "https://github.com/unbraind/pm-cli"

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

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