@unbrained/pm-cli 2026.8.10 → 2026.8.11

package/dist/types.js

@@ -5,7 +5,7 @@
  */
 /** 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]="2a2072c1-f4a7-579e-ac11-4c75758d76d3")}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]="605cf12e-6106-563a-abc0-38d648d4aa43")}catch(e){}}();
 export const BUILTIN_ITEM_TYPE_VALUES = [
     "Epic",
     "Feature",
@@ -241,4 +241,4 @@ export const CONTEXT_SECTION_VALUES = [
     "tests",
 ];
 //# sourceMappingURL=types.js.map
-//# debugId=2a2072c1-f4a7-579e-ac11-4c75758d76d3
+//# debugId=605cf12e-6106-563a-abc0-38d648d4aa43

package/docs/ASSURANCE.md

@@ -0,0 +1,132 @@
+# Project Assurance Primitives
+
+Tracker: [pm-2lex4r](../.agents/pm/features/pm-2lex4r.toon), [pm-lyfu7b](../.agents/pm/features/pm-lyfu7b.toon), [pm-wn6wot](../.agents/pm/features/pm-wn6wot.toon), [pm-91xeam](../.agents/pm/features/pm-91xeam.toon)
+
+## Agent Quick Context
+
+Assurance turns project policy into three reusable SDK-owned declarations:
+
+1. A **measurement** selects authoritative project data and produces a number or labelled set plus population, contributor, and compute-cost receipts.
+2. An **assertion** applies exactly one explicit bound, scope, lifetime, and enforcement level to a measurement. Required negative controls prove that the bound can both pass and fail.
+3. A **gate** evaluates named assertions at declared lifecycle triggers and returns one structured verdict shared by CLI, SDK, MCP, and CI callers.
+
+Declarations live in `.agents/pm/assurance.json`. Every registry mutation and non-dry gate verdict is appended through the verified workspace history stream; never edit either file directly.
+
+## Why Assurance Exists
+
+Project management is context management. A useful quality gate therefore needs more than a shell exit code: it must preserve what was measured, which population was judged, why a bound exists, who owns it, what changed the result, how expensive the evaluation was, and which immutable tree received the verdict.
+
+The assurance SDK keeps those semantics independent from presentation. Commander and MCP only normalize inputs. Package authors and CI hosts can use the same public functions without reconstructing policy in scripts.
+
+## Declaration Vocabulary
+
+Measurements support these built-in sources:
+
+| Source | Purpose |
+| --- | --- |
+| `items` | Count items matching status, type, tags, or an exact metadata field. |
+| `dependency_kind` | Count typed relationship edges such as `blocked_by` or `verifies`. |
+| `graph` | Select a numeric or labelled-set field from a public graph SDK result. |
+| `validate` | Select a validator check status or numeric detail. |
+| `health` | Select a health check status, numeric detail, or labelled set. |
+| `history` | Count immutable events by operation, author, harness, or model. |
+| `links` | Count items with present or missing file, test, or documentation evidence. |
+| `derived` | Combine numeric measurements with deterministic arithmetic and cycle detection. |
+| `provider` | Delegate a measurement to an explicitly supplied host/package resolver. |
+
+Each measurement may declare `max_cost`. Evaluation fails closed when the total abstract compute units exceed that ceiling. Every result reports units, scanned items, scanned history rows, provider calls, duration, population size, and contributors.
+
+Assertions require exactly one polarity:
+
+- `ceiling`, `floor`, `equals`, or `zero`
+- `monotone_nondecreasing` or `monotone_nonincreasing`
+- `subset_of` for labelled sets
+
+Scopes are `all`, `active`, or `filter`. A filter names another measurement whose contributors define the item population. `lifetime: hold` keeps the guarantee after its owner item becomes terminal. `lifetime: retire` retires it only after owner termination and requires `retire_reason`.
+
+Enforcement is `block`, `warn`, or `observe`. Weakening a bound, scope, lifetime, owner, source measurement, or enforcement requires `authorization_decision` naming a terminal Decision item verified by the host. The transport verifies only that explicitly named item; it never treats unrelated workspace Decisions as authorization. Tightening does not require authorization.
+
+## CLI Workflow
+
+Create a measurement:
+
+```bash
+pm assurance put measurement active-issues \
+  --definition '{"id":"active-issues","source":{"kind":"items","statuses":["open","in_progress"],"types":["Issue"]},"max_cost":5000}' \
+  --message "Track the active issue population"
+```
+
+Create an assertion with executable negative controls:
+
+```bash
+pm assurance put assertion active-issues-ceiling \
+  --definition '{"id":"active-issues-ceiling","measurement_id":"active-issues","owner_item_id":"pm-example","scope":{"kind":"active"},"ceiling":25,"lifetime":"hold","enforcement":"block","negative_control":{"cases":[{"observed":25,"expected":"pass"},{"observed":26,"expected":"fail"}]}}'
+```
+
+Create and evaluate a gate:
+
+```bash
+pm assurance put gate release-readiness \
+  --definition '{"id":"release-readiness","assertion_ids":["active-issues-ceiling"],"triggers":["ci","pre-release"]}'
+
+pm assurance run release-readiness --trigger ci --dry-run --json
+pm assurance run release-readiness --trigger pre-release --tree "$(git rev-parse HEAD)" --json
+pm assurance verdicts release-readiness --limit 20 --json
+```
+
+Registry reads and removals use the same nouns:
+
+```bash
+pm assurance list measurement --json
+pm assurance show assertion active-issues-ceiling --json
+pm assurance remove gate release-readiness
+```
+
+Referenced measurements and assertions cannot be removed. Remove the consuming gate or assertion first.
+
+## SDK and MCP
+
+The reusable client exposes the same action grammar:
+
+```ts
+import { PmClient } from "@unbrained/pm-cli/sdk";
+
+const pm = new PmClient({ pmRoot: ".agents/pm" });
+
+await pm.assurance({
+  action: "run",
+  id: "release-readiness",
+  trigger: "ci",
+  dry_run: true,
+});
+```
+
+For direct host composition, use `evaluateMeasurement`, `evaluateAssuranceGate`, `createAssuranceWorkspaceContext`, and the audited declaration/verdict helpers exported from `@unbrained/pm-cli/sdk`. A host contributes provider measurements by passing stable resolver ids to `createAssuranceWorkspaceContext`; an absent resolver fails loudly. External adapters must enforce an appropriate timeout. The core evaluator bounds concurrent assertions and expression operands, and workspace history loading uses bounded concurrency; item-only callers can explicitly skip history and Git identity resolution.
+
+Generic SDK and MCP dispatch use `action: "assurance"` with `subcommand` set to `list`, `show`, `put`, `remove`, `run`, or `verdicts`. Discover the current machine contract instead of copying parameter lists:
+
+```bash
+pm contracts --action assurance --schema-only --json
+pm contracts --command assurance --flags-only --json
+```
+
+## Verdict Contract
+
+A gate emits one object containing:
+
+- gate id, evaluated tree, trigger, timestamp, and dry-run status;
+- overall `pass`, `warn`, or `block` plus stable exit code;
+- every assertion's measurement, scope, population, observed value, structured bound, signed distance, enforcement, negative-control proof, cost, and contributors;
+- an aggregate compute receipt.
+
+Dry runs never write history. Non-dry verdicts are immutable workspace audit events and remain queryable after ordinary registry changes. Verdict reads return newest entries first and default to a bounded result; use `--limit` to select up to 1,000 matching records. A blocking verdict exits non-zero; warnings and observations remain successful while preserving their failed assertion rows.
+
+## Safety and Evolution
+
+- Use stable lowercase ids; prose belongs in descriptions and mutation messages.
+- Prefer saved measurements and derived arithmetic over duplicating queries in scripts.
+- Give expensive graph, health, validate, or provider measurements explicit cost ceilings.
+- Keep owner items and authorization Decisions linked into the project graph.
+- Treat negative controls as part of the policy, not test decoration.
+- Use `hold` unless a time-bounded guarantee has an explicit retirement rationale.
+- Use `--dry-run` while authoring or tightening a gate, then persist a verdict against an immutable tree.

package/docs/README.md

@@ -53,6 +53,7 @@ pm guide release --json
 - [Agent Provenance ADR Amendment](AGENT_PROVENANCE_ADR.md) - extensible model, effort, role, and host provenance with privacy and compatibility boundaries.
 - [SDK Agent Session and Episode Context](SDK_AGENT_SESSION_CONTEXT.md) - inherited role/topic context, cross-process episode identity, and deterministic history grouping.
 - [Improvement Ledger and History Analytics](IMPROVEMENT_ANALYTICS.md) - audited quantitative observations, live provenance coverage, and bounded observational fleet outcomes.
+- [Project Assurance Primitives](ASSURANCE.md) - SDK-owned measurements, assertions, lifecycle gates, cost receipts, and durable verdict history shared by CLI and MCP.
 - [SDK Evidence Traceability and Integrity](SDK_EVIDENCE_TRACEABILITY.md) - reverse source-to-item lookup, atomic evidence replacement, no-op history, linked-test collision classification, and telemetry drain receipts.
 - [Reproducible Workspaces and Snapshots](REPRODUCIBLE_WORKSPACES.md) - deterministic SDK recipes and content-addressed authoritative tracker restore points.
 - [Portable Corpus Shapes](CORPUS_SHAPES.md) - versioned SDK populations for realistic benchmarks, evaluations, and package tests.

package/docs/RELEASING.md

@@ -106,7 +106,7 @@ The pipeline performs:
 1. change detection + one-release-per-day guard
 2. a single `YYYY.M.D` version bump; ordinal targets and the removed
    `--allow-same-day-release` override fail closed
-3. latest `pm-changelog` install and main changelog refresh through package-owned full-history generation; the release pipeline passes `--release-version` with `--all-release-tags` so the pending release section matches post-tag CI checks
+3. latest `pm-changelog` install and main changelog refresh through package-owned full-history generation; the release pipeline passes `--release-version`, `--all-release-tags`, and the canonical `--exclude-tag changelog-exclude` policy so the pending release section matches post-tag CI checks
 4. build, clone-local merge-driver installation, then the remaining strict gates (typecheck, docs/skills freshness, coverage, static quality, compatibility, security, smoke checks, reliability gate); this ordering makes the checkout-owned CLI available before bootstrap, matches CI, and prevents fresh-clone tracker measurements from observing undeclared merge-driver repairs
 5. release note generation from changelog + pm evidence
 6. commit and tag creation (plus optional push)
@@ -265,7 +265,10 @@ git push origin v<version>
 - build, clone-local merge-driver installation, typecheck, test, and coverage
 - generated changelog verification and `pm-changelog` installation before the
   tracker-bearing static gate, so a clean checkout does not misclassify the
-  managed extension's linked files as missing
+  managed extension's linked files as missing. Recovery of an unpublished
+  immutable tag regenerates only `CHANGELOG.md` with the tagged checkout's
+  canonical package script and fails if that operation changes any other
+  tracked source path (apart from managed-extension install metadata).
 - static quality gate (shared complexity, duplication, dead/orphan module, file/folder hygiene, source/exported docstring coverage profile)
 - temporary-project compatibility gate against latest published tracker data
 - reliability threshold gate (Sentry severity threshold, bounded to a recent-activity window via `--sentry-window-days` (default `14`, `0` = unbounded) so a stale benign unresolved issue cannot block every scheduled release; `--telemetry-mode` gate policy: `off` | `best-effort` | `required`). Scheduled `auto-release.yml` failures open/update an `Auto Release blocked` GitHub issue so blocked daily releases are never silently skipped.
@@ -350,9 +353,10 @@ Use the npm registry package for maintainer global updates. Do not use `npm inst
   existing version keeps the reviewed dispatch-time `main` source and cannot
   be republished. A definitive missing-version response pins the checkout to
   the existing immutable tag, reapplies the version guard, installs the managed
-  changelog extension before tracker measurement, and permits first publication
-  only from that exact tagged source. Other registry failures stop before
-  source selection or publication.
+  changelog extension, regenerates the package changelog with the tagged
+  checkout's canonical policy under a tracked-path mutation guard, and permits
+  first publication only from that tagged source. Other registry failures stop
+  before source selection or publication.
 - If an immutable published package contains a defect that cannot be repaired
   by rerunning the same tag workflow, document the incident and ship the code
   fix in the next UTC day's release.

package/docs/SDK.md

@@ -317,7 +317,8 @@ Command/action contract exports:
 - Execution and diagnostics engines: `runTest`, `runLinkedTests`, `runTestAll`, `runStartBackgroundRun`, `runTestRunsList`, `runTestRunsStatus`, `runTestRunsLogs`, `runTestRunsStop`, `runTestRunsResume`, `runTestRunsWorker`, `runEval`, `runTelemetry`, and `runStats`. Their CLI modules are compatibility re-exports of SDK-owned implementations.
 - Execution and diagnostics contracts: `TestCommandOptions` / `TestResult` / `TestRunResult`, `TestAllCommandOptions` / `TestAllResult`, `StartBackgroundRunCommandOptions` / `StartBackgroundRunResult`, `TestRuns*CommandOptions`, `EvalOptions` / `EvalResult`, `TelemetryCommandOptions` / `TelemetrySubcommand`, and `StatsCommandOptions` / `StatsResult`.
 - Linked-test authoring primitives: `parseLinkedTestJsonEntries`, the `parseLinkedTest*` field parsers, `LINKED_TEST_PM_CONTEXT_MODE_VALUES`, `LINKED_TEST_PROTECTED_ENV_KEYS`, `classifyLinkedTestFailure`, `countFailureCategories`, and `summarizeContextPreflight` let custom hosts validate, execute, classify, and report linked tests without duplicating CLI policy.
-- Agent command primitives: `normalizeItemAddressInvocation` and `supportsItemIdAlias` project one item-id grammar across CLI adapters; `renderMissingOptionRetry` and `resolveMissingOptionPlaceholder` preserve attempted argv while deriving enum, boolean, and scalar recovery arity from flag contracts; `rankCommandPaths` and `scoreCommandPathMatch` provide deterministic synonym/edit-distance/substring ranking; `resolveCreateExplicitEmptyFlag` and `supportsCreateExplicitEmpty` model a considered-but-empty strict repeatable input without inventing metadata or graph edges.
+- Agent command primitives: `normalizeItemAddressInvocation` and `supportsItemIdAlias` project one item-id grammar across CLI adapters; `renderMissingOptionRetry` and `resolveMissingOptionPlaceholder` preserve attempted argv while deriving enum, boolean, and scalar recovery arity from flag contracts; `createUnknownSubcommandError` provides one typed positional refusal with complete allowed values and deterministic nearest retry; `rankCommandPaths` and `scoreCommandPathMatch` provide deterministic synonym/edit-distance/substring ranking; `resolveCreateExplicitEmptyFlag` and `supportsCreateExplicitEmpty` model a considered-but-empty strict repeatable input without inventing metadata or graph edges.
+- Refusal reachability primitives: generated `PmErrorCodeContract.owned_states` declarations bind stable codes to concrete states, probe ids, entrypoints, and exit classes; `verifyPmRefusalReachability` compares those declarations with real CLI, SDK, MCP, or package observations and fails closed for missing, duplicate, wrong-entrypoint, mismatched, or undeclared probes.
 - Typed plan workflow primitives on `PmClient`: `plan`, `planCreate`, `planShow`, `planAddStep`, `planUpdateStep`, `planCompleteStep`, `planBlockStep`, `planReorderStep`, `planRemoveStep`, `planLink`, `planUnlink`, `planDecision`, `planDiscovery`, `planValidation`, `planResume`, `planApprove`, and `planMaterialize`
 - Plan contracts: `PlanSubcommand`, `PlanCommandOptions`, `PlanCommandResult`, `PlanResultPlan`, `PlanStepSummary`, `PlanShowDepth`, and `PlanTemplateName`
 - Typed package and extension lifecycle primitives on `PmClient`: `extension`, `extensionList`, `extensionActivate`, `extensionDeactivate`, `package`, `packageList`, `packageInstall`, `packageUninstall`, `packageDoctor`, `packageManage`, `packageDescribe`, `packageReload`, `packageCatalog`, `packageActivate`, `packageDeactivate`, `packageMigrate`, and `upgrade`; one-shot `extensionMigrate` and `packageMigrate` helpers mirror those lifecycle actions.
@@ -3274,6 +3275,10 @@ For SDK and automation consumers, the key runtime change is the optional `recove
 - `normalized_args`
 - `provided_fields`
 - `missing`
+- `allowed_values`
+- `candidate_commands`
+- `candidate_commands_total`
+- `candidate_commands_truncated`
 - `suggested_retry`
 
 Treat `recovery.suggested_retry` as the first-choice deterministic replay
@@ -3287,6 +3292,12 @@ interpreted as a missing input. Strict close validation reports missing
 resolution fields first and suggests a targeted `pm update` before retrying the
 original close invocation.
 
+Unknown-option envelopes rank command paths that accept the rejected flag by
+shared vocabulary and include explicit total/truncation metadata. They are
+contract-discovery hints, not permission to change the requested operation.
+Unknown positional subcommands expose the complete `allowed_values` vocabulary
+and use `suggested_retry` only when a deterministic nearby value exists.
+
 ## Authoring Pattern
 
 - Keep handlers deterministic and JSON-like.

package/docs/SDK_AGENT_SESSION_CONTEXT.md

@@ -85,10 +85,38 @@ values are ignored instead of polluting analytics. Presence-only harness flags,
 including `CLAUDE_CODE_CHILD_SESSION=1`, are detection evidence and are never
 persisted as semantic roles.
 
-For ordinary CLI mutations, the detector can infer an `implementer` or
-`reviewer` role from the bounded command verb and a topic from an explicit
-`pm-...` item argument. Explicit overrides, session declarations, and trusted
-host declarations retain precedence over this inference.
+## Infer semantic context from lifecycle state
+
+Successful `claim`, `release`, and `focus` operations maintain a bounded,
+checkout-local semantic workset. Later CLI and SDK mutations can therefore
+record useful role and topic provenance without repeating identity flags or
+retaining prompt text:
+
+- a claim records the item and at most 16 canonical parent ancestors, infers
+  `role=implementer`, and uses the item or stable multi-item workset as topic;
+- an explicit focus becomes the high-confidence topic and infers
+  `role=planner`;
+- a release removes only that claim and records `role=release-operator` while
+  other active claims remain; and
+- clearing the final claim and focus removes the inferred session record.
+
+At most 64 active item ids and 32 evidence rows are retained. Multi-item topics
+are deterministically bounded and hashed when their full identity would exceed
+the provenance limit. The state is partitioned by the privacy-safe agent
+instance when available, otherwise by a truncated hash of the resolved author.
+It lives in the gitignored runtime session file and malformed records fail open.
+
+The same workset feeds `pm context` as `claim_focus` relevance: claimed and
+focused items receive affinity `1`, while bounded canonical ancestors receive
+`0.75`. Active work is preserved by the context packer under its existing token
+ceiling; the inference never raises the requested budget.
+
+Explicit overrides, declared session context, command flags, environment,
+MCP-client declarations, host declarations, and configured probes all retain
+precedence. Automatic observations use `source=inferred`, `rule_version=v2`,
+and carry the bounded claim/focus/lineage evidence that supports them. The pure
+`semanticAttributionAffinity()` helper and lifecycle recording primitives are
+public SDK exports for custom hosts.
 
 ## Diagnose missing provenance
 
@@ -145,6 +173,11 @@ declared a dimension but supplied no value. The compatibility helper
 `summarizeAgentModelProvenance(entries)` remains available for model-only
 consumers.
 
+`evaluateSemanticAttributionCoverage(entries, options)` groups role/topic
+availability by harness and precedence source. Its explicit minimum-entry and
+minimum-coverage ratchet fails empty corpora, making a negative control part of
+the contract instead of allowing an unobserved harness to pass vacuously.
+
 `groupHistoryByEpisode(entries)` returns deterministic nested groups:
 
 - recorded episode keys produce `source: "declared"`;
@@ -166,3 +199,6 @@ channel. Do not put tokens, private hostnames, signed URLs, or raw external
 payloads in ids, labels, roles, or topics. Session ids used to derive
 `agent_instance` remain transient and are not persisted. Every new history
 field is optional, so existing streams and packages remain readable.
+Automatic semantic attribution is likewise restricted to item ids, controlled
+roles, rule metadata, and canonical lineage ids. It never persists argv,
+environment values, prompts, filesystem contents, or raw harness session ids.

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/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.10"
+    "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.10",
+      "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.10",
+  "version": "2026.8.11",
   "description": "Git-native project management CLI for humans and agents.",
   "type": "module",
   "packageManager": "pnpm@11.10.0",
@@ -211,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.10",
+  "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.10",
+  "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.10",
+  "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.10",
+  "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.10",
+  "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.10",
+  "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.10",
+  "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.10",
+  "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.10",
+  "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.10",
+  "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.10",
+  "version": "2026.8.11",
   "private": true,
   "type": "module",
   "description": "First-party pm package for reusable create templates.",