@unbrained/pm-cli 2026.8.20 → 2026.8.21

package/docs/RELATIONSHIP_GRAPH.md

@@ -1,6 +1,6 @@
 # Relationship graph semantics
 
-Tracked by [pm-4jqm](../.agents/pm/decisions/pm-4jqm.toon), [pm-dwj33e](../.agents/pm/decisions/pm-dwj33e.toon), [pm-ju83](../.agents/pm/features/pm-ju83.toon), [pm-8xr8](../.agents/pm/stories/pm-8xr8.toon), [pm-m2il](../.agents/pm/chores/pm-m2il.toon), [pm-jiusod](../.agents/pm/issues/pm-jiusod.toon), [pm-mfvsng](../.agents/pm/issues/pm-mfvsng.toon), [pm-9gzr4r](../.agents/pm/issues/pm-9gzr4r.toon), [pm-xvt7ps](../.agents/pm/issues/pm-xvt7ps.toon), and [pm-ouyq3n](../.agents/pm/issues/pm-ouyq3n.toon).
+Tracked by [pm-4jqm](../.agents/pm/decisions/pm-4jqm.toon), [pm-dwj33e](../.agents/pm/decisions/pm-dwj33e.toon), [pm-ju83](../.agents/pm/features/pm-ju83.toon), [pm-8xr8](../.agents/pm/stories/pm-8xr8.toon), [pm-m2il](../.agents/pm/chores/pm-m2il.toon), [pm-jiusod](../.agents/pm/issues/pm-jiusod.toon), [pm-mfvsng](../.agents/pm/issues/pm-mfvsng.toon), [pm-9gzr4r](../.agents/pm/issues/pm-9gzr4r.toon), [pm-xvt7ps](../.agents/pm/issues/pm-xvt7ps.toon), [pm-ouyq3n](../.agents/pm/issues/pm-ouyq3n.toon), [pm-ayg31c](../.agents/pm/issues/pm-ayg31c.toon), [pm-3dyec2](../.agents/pm/issues/pm-3dyec2.toon), [pm-c90tfh](../.agents/pm/issues/pm-c90tfh.toon), and [pm-ob9z4y](../.agents/pm/features/pm-ob9z4y.toon).
 
 ## Decision
 
@@ -10,7 +10,17 @@ The alternatives were rejected as follows: a closed enum cannot model applicatio
 
 ## Contract
 
-Each relationship kind declares direction, inverse, ordering and hierarchy participation, optional temporal order, incoming and outgoing cardinality, lifecycle, aliases, payload schema, self-edge policy, and compatibility version. Built-ins normalize legacy `related_to`, `depends_on`, `child_of`, `parent_child`, `epic`, and `task` spellings. Unknown custom kinds remain importable only after their definitions are registered, preventing algorithms from guessing their meaning.
+Each relationship kind declares direction, inverse, a traversal family,
+optional typed-outcome traversal direction, ordering and hierarchy
+participation, optional temporal order, incoming and outgoing cardinality,
+lifecycle, aliases, payload schema, self-edge policy, and compatibility version.
+Built-ins normalize legacy `related_to`, `depends_on`, `child_of`,
+`parent_child`, `epic`, and `task` spellings. Unknown custom kinds remain
+importable only after their definitions are registered, preventing algorithms
+from guessing their meaning. Omitted custom traversal metadata remains
+compatible: hierarchy and ordering declarations select their corresponding
+families, undirected kinds are associative, and other directed kinds are
+semantic.
 
 `recurs_from` is the canonical recurrence relation: `new --recurs_from--> old`
 means the source is a later event with the same observable failure identity as
@@ -153,10 +163,9 @@ await assertRelationshipGraphAdapterConformance(adapter, {
   workspace: "isolated-conformance-workspace",
 });
 
-const portfolio = federateRelationshipGraphSnapshots(
-  [productA, productB],
-  { createdAt: new Date().toISOString() },
-);
+const portfolio = federateRelationshipGraphSnapshots([productA, productB], {
+  createdAt: new Date().toISOString(),
+});
 ```
 
 `createRelationshipGraphScaleFixture` supplies reiterable lazy `nodes` and
@@ -251,6 +260,14 @@ for domain packages that need more than generic adjacency:
 - `enumerateRelationshipPaths` returns bounded simple paths with edge evidence,
   cost metadata, cancellation, direction/kind filters, and explicit truncation.
 
+An explicit kind filter may include `traversal: "semantic"` kinds on either
+hierarchy or ordering walks, giving package-defined lineage edges a bounded
+semantic traversal surface without pretending that they are structural or
+scheduling edges. Default walks remain family-strict when no kind filter is
+provided. Association kinds refuse these walks with an `impact --direction
+both` recovery route; selecting the other structural family points to the
+matching hierarchy or ordering commands.
+
 All semantic walks are breadth-first and deterministic. `limit`, `maxDepth`,
 and `after` provide bounded continuation for hierarchy and ordering walks;
 path enumeration separately bounds returned paths and expanded partial paths.
@@ -281,8 +298,17 @@ identities and structured rows proven to contradict scalar blocker precedence.
 censuses so repair can tighten their ceilings without weakening the
 information-bearing floor. `articulation_points` and `bridge_edges` reuse the exact cut-structure
 algorithm; outcome metrics count explicit `Milestone` titles beginning with
-`Outcome milestone:` and follow only hierarchy or `implements` edges toward
-them. Active and terminal populations are reported separately, with integer
+`Outcome milestone:` and follow the registry's declared
+`outcomeTraversal` directions toward them. The audit publishes that exact
+`outcome_reachability_basis` direction groups beside the rates, using sorted
+comma-separated kind names so consumers never infer lineage meaning from
+labels while repeated direction labels stay out of the token surface. Built-in
+hierarchy, implementation, verification,
+discovery, incident, recurrence, and supersession edges opt in explicitly;
+`supersedes` traverses both directions so an archived predecessor remains
+connected to the replacement outcome lineage. Generic `related` and ordering
+edges declare no outcome traversal and cannot satisfy the metric. Active and
+terminal populations are reported separately, with integer
 basis-point rates and all-status reachable/unreachable totals; the explicit
 outcome milestones are roots, not work subjects, and are excluded from those
 populations. Rate or
@@ -290,8 +316,7 @@ all-status floors are lifecycle-stable; an absolute active-population floor is
 invalid because completing reachable work legitimately moves it into the
 terminal population. `finding_subjects_by_code` includes every known finding
 code even when its population is zero, so assurance selectors never confuse a
-clean class with a missing contract field. Generic `related` edges cannot
-satisfy outcome reachability.
+clean class with a missing contract field.
 
 ```ts
 import {
@@ -318,6 +343,63 @@ policy findings. A VCS, company operating model, digital twin, or other
 non-project domain can replace the assembly adapter while reusing the same
 registry, traversal, event, context, and audit contracts.
 
+### Relationship assurance sources
+
+Repository assurance can ratchet graph quality without baking one project's
+policy into the graph kernel. A `dependency_kind` measurement may partition a
+canonical dependency kind by exact `source_kind`, by `source_kind_prefix`, or
+by whether provenance is present or missing. These filters are mutually
+exclusive and preserve the unfiltered measurement contract. This supports
+independent evidence-backed and uncited-edge floors or ceilings while keeping
+the dependency vocabulary extensible.
+
+The `prose_edge_gap` source measures distinct holder-target pairs where item
+descriptions, bodies, comments, notes, or learnings mention another canonical
+item but no structured relationship exists in either direction. It performs one
+bounded pass over the supplied items, resolves the collected mentions after the
+canonical id set is complete, reports the exact gap count, partitions the result
+into `explicit_subject` and `implicit_subject` pairs, and caps contributor
+diagnostics with `sample_limit`. Reasoned exemptions may name a whole holder,
+one holder-target pair, or a text fragment within one holder; an exemption
+without a non-empty reason is invalid. This makes roadmap ledgers, negative
+statements, and analysis subjects explicit policy rather than hidden
+false-positive suppression.
+
+```ts
+const evidenceBlocks = {
+  kind: "dependency_kind" as const,
+  dependency_kind: "blocks",
+  source_kind_prefix: "evidence:",
+};
+
+const unlinkedMentions = {
+  kind: "prose_edge_gap" as const,
+  sample_limit: 25,
+  exemptions: [
+    {
+      holder_id: "roadmap-ledger",
+      reason: "The ledger inventories work without asserting pairwise edges.",
+    },
+  ],
+};
+```
+
+Assurance assertions should pin these measurements to observed repository
+baselines: an evidence partition uses a non-regression floor, while uncited
+edges and prose gaps use ceilings. Negative controls must prove the observed
+value passes and a one-unit regression fails before the assertions join the
+repository's graph-composition gate.
+
+The scale acceptance runs the public SDK over one million items whose 999,999
+prose mentions each have a corresponding structured edge. It verifies an exact
+zero-gap result, bounded empty diagnostics, a 2,999,998-unit cost receipt, and
+the real item scan count:
+
+```bash
+pnpm build
+node --max-old-space-size=4096 scripts/benchmarks/prose-edge-gap-scale.mjs
+```
+
 The native workspace adapter is `pm graph <subcommand>`, also available as
 `PmClient.graph`, `runAction({ action: "graph" })`, and the MCP `pm_graph`
 tool. `ancestors`/`descendants`/`predecessors`/`successors` expose the

package/docs/SDK_PRIMITIVE_INVENTORY.md

@@ -1,6 +1,6 @@
 # SDK Primitive Inventory
 
-Tracked work: [pm-lodl](../.agents/pm/tasks/pm-lodl.toon), [pm-8778](../.agents/pm/tasks/pm-8778.toon), [pm-rjqr](../.agents/pm/features/pm-rjqr.toon), [pm-oslr](../.agents/pm/features/pm-oslr.toon), capstone [pm-9x6e](../.agents/pm/tasks/pm-9x6e.toon), parent [pm-usfg](../.agents/pm/epics/pm-usfg.toon).
+Tracked work: [pm-lodl](../.agents/pm/tasks/pm-lodl.toon), [pm-8778](../.agents/pm/tasks/pm-8778.toon), [pm-rjqr](../.agents/pm/features/pm-rjqr.toon), [pm-oslr](../.agents/pm/features/pm-oslr.toon), [pm-6qiwan](../.agents/pm/chores/pm-6qiwan.toon), capstone [pm-9x6e](../.agents/pm/tasks/pm-9x6e.toon), parent [pm-usfg](../.agents/pm/epics/pm-usfg.toon).
 
 This inventory records the completed SDK-first migration for the principle `project management = context management`.
 CLI and MCP modules now import shared host services through `src/sdk/runtime-primitives.ts`; direct `src/core` imports, type-only edges, re-exports, and computed dynamic imports are unconditionally rejected by the static quality gate. There is no allowance file or ratchet escape hatch.
@@ -18,6 +18,20 @@ CLI and MCP modules now import shared host services through `src/sdk/runtime-pri
 
 `src/sdk/runtime-primitives.ts` is the curated low-level seam for presentation hosts. It exposes filesystem, schema, history, extension-runtime, telemetry, search, output, and storage services needed to compose the shipped CLI and MCP adapters. External integrations should still prefer typed `PmClient` and top-level SDK operations; runtime primitives exist for embedded hosts that need to build an equivalent presentation layer without private imports.
 
+## Tracker Preflight Primitive
+
+`assertInitializedTracker` is the shared SDK boundary for commands that require
+an initialized project, while `assertReadableTrackerRoot` supports low-level
+metadata enumeration that intentionally accepts an empty directory. The former
+replaced 50 literal checks across 45 SDK modules. It preserves one structured
+error vocabulary and one exact recovery contract for CLI, MCP dispatch through
+the SDK runtime, first-party packages, and external SDK consumers.
+
+The preflight is public from the aggregate SDK; its four-state static recovery
+corpus is also public from `@unbrained/pm-cli/sdk/contracts`. A source-derived
+ratchet prevents the adoption count from falling below 50 and refuses the old
+inline tracker-not-initialized message anywhere under `src/sdk`.
+
 ## Promotion Partition
 
 | Promotion item | Primitive family | Primary private domains to promote |

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.20"
+    "version": "2026.8.21"
   },
   "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.20",
+      "version": "2026.8.21",
       "author": {
         "name": "unbrained",
         "url": "https://github.com/unbraind/pm-cli"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-cli",
-  "version": "2026.8.20",
+  "version": "2026.8.21",
   "description": "Git-native project management CLI for humans and agents.",
   "type": "module",
   "packageManager": "pnpm@11.10.0",

package/packages/pm-beads/package.json

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

package/packages/pm-templates/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-templates",
-  "version": "2026.8.20",
+  "version": "2026.8.21",
   "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.20",
+  "version": "2026.8.21",
   "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.20",
+  "version": "2026.8.21",
   "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.20",
+  "version": "2026.8.21",
   "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.20",
+  "version": "2026.8.21",
   "description": "Native Codex integration for pm-cli with bundled MCP tools, skills, commands, and agent workflows.",
   "author": {
     "name": "unbrained",