@unbrained/pm-cli 2026.8.20 → 2026.8.22

package/docs/COMMANDS.md

@@ -6,6 +6,8 @@ Tracked implementation updates: [pm-52eh](../.agents/pm/features/pm-52eh.toon),
 
 Workspace-integrity contracts are tracked by [pm-22rzjp](../.agents/pm/issues/pm-22rzjp.toon), [pm-76fkpp](../.agents/pm/issues/pm-76fkpp.toon), [pm-igdvfq](../.agents/pm/issues/pm-igdvfq.toon), [pm-643e0k](../.agents/pm/issues/pm-643e0k.toon), and [pm-larv4r](../.agents/pm/issues/pm-larv4r.toon).
 
+Create-safe init prefix normalization is tracked by [pm-gh1073](../.agents/pm/issues/pm-gh1073.toon).
+
 ```bash
 pm <command> --help
 pm <command> --help --json
@@ -49,21 +51,21 @@ JSON ceiling; TOON uses the smaller default agent ceiling.
 
 ## Command Families
 
-| Family       | Commands                                                                                                                       | Purpose                                                                                                                                                                                                                                                |
-| ------------ | ------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| Bootstrap    | `init`, `config`, `health`, `telemetry`                                                                                        | create and inspect tracker setup                                                                                                                                                                                                                       |
+| Family       | Commands                                                                                                                                      | Purpose                                                                                                                                                                                                                                                |
+| ------------ | --------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Bootstrap    | `init`, `config`, `health`, `telemetry`                                                                                                       | create and inspect tracker setup                                                                                                                                                                                                                       |
 | Lifecycle    | `create`, `copy`, `focus`, `claim`, `update`, `item reopen`, `append`, `close`, `release`, `delete`, `start-task`, `pause-task`, `close-task` | mutate item state, including terminal-work recurrence without duplicate creation                                                                                                                                                                       |
-| Bulk         | `item mutate`, `item complete`, `update-many`, `close-many`                                                                    | atomically commit heterogeneous SDK mutation batches or evidence-backed completion, or apply one change across a matched, dry-run-previewed set with a rollback checkpoint                                                                             |
-| Scheduling   | `meet`, `event`, `remind`                                                                                                      | low-friction Meeting/Event/Reminder creation                                                                                                                                                                                                           |
-| Planning     | `plan create`, `plan add-step`, `plan update-step`, `plan complete-step`, `plan link`, `plan approve`, `plan materialize`      | agent-optimized living plans with ordered steps, evidence, decisions, validation, and materialization                                                                                                                                                  |
-| Links        | `files`, `docs`, `test`, `deps`                                                                                                | connect items to artifacts, tests, and relationships                                                                                                                                                                                                   |
-| Verification | `test`, `test-all`, `test-runs`†, `validate`, `gc`                                                                             | run linked tests and repository checks                                                                                                                                                                                                                 |
-| History      | `history`, `history-compact`, `history-redact`, `history-repair`, `activity`, `restore`, `stats`                               | inspect, compact, redact, re-anchor, and recover item state                                                                                                                                                                                            |
-| Schema       | `schema add/remove-*` / `rename-type` / `rename-field` / `remap-status` / `apply-preset`                                       | manage config-driven types, statuses, and fields; losslessly migrate existing items when definitions evolve; adopt presets or infer types                                                                                                              |
-| Profiles     | `profile list` / `show` / `apply` / `lint`                                                                                     | compose item types, statuses, fields, workflows, config, templates, and recommended packages into archetype bundles (agile/ops/research); `apply` stages every dimension idempotently; `lint` reports author-time consistency findings without writing |
-| Calendar     | `calendar`, `cal`                                                                                                              | project deadlines, reminders, and events                                                                                                                                                                                                               |
-| Packages     | `install`, `upgrade`, `package`, `packages`, `extension`, package/extension command groups                                     | install, upgrade, manage, and run package-backed extension commands                                                                                                                                                                                    |
-| Machines     | `contracts`, `help`, optional `guide`/`completion`                                                                             | command contracts plus optional guide-shell docs routing and shell helpers                                                                                                                                                                             |
+| Bulk         | `item mutate`, `item complete`, `update-many`, `close-many`                                                                                   | atomically commit heterogeneous SDK mutation batches or evidence-backed completion, or apply one change across a matched, dry-run-previewed set with a rollback checkpoint                                                                             |
+| Scheduling   | `meet`, `event`, `remind`                                                                                                                     | low-friction Meeting/Event/Reminder creation                                                                                                                                                                                                           |
+| Planning     | `plan create`, `plan add-step`, `plan update-step`, `plan complete-step`, `plan link`, `plan approve`, `plan materialize`                     | agent-optimized living plans with ordered steps, evidence, decisions, validation, and materialization                                                                                                                                                  |
+| Links        | `files`, `docs`, `test`, `deps`                                                                                                               | connect items to artifacts, tests, and relationships                                                                                                                                                                                                   |
+| Verification | `test`, `test-all`, `test-runs`†, `validate`, `gc`                                                                                            | run linked tests and repository checks                                                                                                                                                                                                                 |
+| History      | `history`, `history-compact`, `history-redact`, `history-repair`, `activity`, `restore`, `stats`                                              | inspect, compact, redact, re-anchor, and recover item state                                                                                                                                                                                            |
+| Schema       | `schema add/remove-*` / `rename-type` / `rename-field` / `remap-status` / `apply-preset`                                                      | manage config-driven types, statuses, and fields; losslessly migrate existing items when definitions evolve; adopt presets or infer types                                                                                                              |
+| Profiles     | `profile list` / `show` / `apply` / `lint`                                                                                                    | compose item types, statuses, fields, workflows, config, templates, and recommended packages into archetype bundles (agile/ops/research); `apply` stages every dimension idempotently; `lint` reports author-time consistency findings without writing |
+| Calendar     | `calendar`, `cal`                                                                                                                             | project deadlines, reminders, and events                                                                                                                                                                                                               |
+| Packages     | `install`, `upgrade`, `package`, `packages`, `extension`, package/extension command groups                                                    | install, upgrade, manage, and run package-backed extension commands                                                                                                                                                                                    |
+| Machines     | `contracts`, `help`, optional `guide`/`completion`                                                                                            | command contracts plus optional guide-shell docs routing and shell helpers                                                                                                                                                                             |
 
 `†` `test-runs` subcommands are provided by the optional `linked-test-adapters` package (`pm install linked-test-adapters --project`).
 
@@ -89,6 +91,15 @@ ID prefix without relying on the legacy positional form. `pm init ops` remains
 compatible, and supplying both forms is accepted only when they normalize to the
 same prefix; conflicting values fail with `init_id_prefix_conflict` instead of
 silently choosing one.
+Prefixes normalize through the same primitive used by item creation: letters
+become lowercase, each run of whitespace or punctuation becomes one `-`, edge
+separators are removed, and exactly one trailing `-` is stored. For example,
+`"Release Candidate"` persists as `release-candidate-`; an input with no ASCII
+letters or digits falls back to `pm-`. Path-like values remain invalid tracker
+prefixes when passed through `--id-prefix`; a path-like positional value remains
+the advanced tracker-root target described below. To repair an older unsafe
+value, rerun init with a safe prefix and explicit replacement intent, for example
+`pm init --id-prefix "release candidate" --force --defaults`.
 Use `pm init --workspace <dir>` when `<dir>` is a project root; it creates `<dir>/.agents/pm`. A path-like positional remains the advanced tracker-root form and writes tracker files directly at that path. Both explicit target forms return `target.mode`, `target.tracker_root`, and tracker-scoped executable `next_steps` so agents can run the suggestions from any working directory.
 Implicit init discovery also reports whether the selected tracker is local or was found in an ancestor. If `pm init <name>` would change an ancestor tracker, the refusal names both directories and gives the safe current-directory retry: `pm init <name> --pm-path "$PWD/.agents/pm" --defaults`.
 `pm init --agent-guidance ask` is the default behavior: prompt in TTY only when AGENTS/CLAUDE guidance is missing and no decline is recorded.
@@ -163,6 +174,10 @@ Use `duplicates --status all` for a true whole-history duplicate check. The
 result echoes `filters.statuses: null` for the unrestricted corpus; named or
 custom statuses are normalized through the runtime status registry and an
 unknown status fails instead of returning a false-clean result.
+As a read-only structured surface, `duplicates` accepts the universal output
+controls, including `--output-format json`, `--lean`, projection/amount
+controls, and token accounting, while its default TOON output remains bounded.
+Tracked by [pm-gh1076](../.agents/pm/issues/pm-gh1076.toon).
 Use `pm get <id>` to read a single item by ID — the single-item read primitive used throughout the agent loop. It accepts `--fields <list>` and `--depth brief|standard|deep|full` for token-minimal projections, and `--tree`/`--tree-depth <n>` to include descendants. Standard/deep reads expose a normalized `schedule` facet (`deadline`, `start_at`, `end_at`, `location`, reminders, and events) when scheduling metadata exists. Container-oriented built-ins (Epic, Feature, Milestone, and Plan) plus custom types automatically expose type-agnostic child counts and continuation metadata. Standard depth keeps that rollup counts-only; `--depth deep|full` or an explicit `--fields id,children` request adds the deterministic bounded child sample. Built-in leaf reads avoid a workspace scan unless children are explicitly requested. `pm get <id> --json` returns the `body` inside the `item` object (`.item.body`); see [Full results, totals, and bodies](#full-results-totals-and-bodies). To duplicate an existing item as a starting point, `pm copy <id> --title "New title"` clones it into a fresh id with lifecycle fields reset.
 
 When the strongest duplicate match is terminal because the same work recurred,

package/docs/DEPENDENCY_KIND_CONTRACT.md

@@ -1,6 +1,6 @@
 # Dependency-kind contract
 
-Tracker: [pm-4020c5](../.agents/pm/issues/pm-4020c5.toon), [pm-jkbqt8](../.agents/pm/issues/pm-jkbqt8.toon), [pm-q6n8sj](../.agents/pm/issues/pm-q6n8sj.toon), [pm-ouyq3n](../.agents/pm/issues/pm-ouyq3n.toon)
+Tracker: [pm-4020c5](../.agents/pm/issues/pm-4020c5.toon), [pm-jkbqt8](../.agents/pm/issues/pm-jkbqt8.toon), [pm-q6n8sj](../.agents/pm/issues/pm-q6n8sj.toon), [pm-ouyq3n](../.agents/pm/issues/pm-ouyq3n.toon), [pm-gos426](../.agents/pm/issues/pm-gos426.toon), [pm-flnefm](../.agents/pm/issues/pm-flnefm.toon), [pm-rggtvd](../.agents/pm/issues/pm-rggtvd.toon), and [pm-vk7zek](../.agents/pm/issues/pm-vk7zek.toon).
 
 Dependency rows have one canonical stored spelling per relationship meaning. Command inputs remain compatibility-friendly: hyphens normalize to underscores and the aliases below are accepted, but `pm create` and `pm update` persist the canonical kind. Existing historical rows are never rewritten implicitly.
 
@@ -15,6 +15,45 @@ Dependency rows have one canonical stored spelling per relationship meaning. Com
 
 The SDK relationship registry is authoritative. `canonicalizeRelationshipKind()` rejects unknown spellings, while `resolveCanonicalRelationshipKind()` supports validation flows that need an undefined result. `pm contracts` publishes `relationship_kind_contracts` with canonical names, aliases, inverses, and ordering/hierarchy semantics.
 
+Extension kinds may opt into both ordering and hierarchy semantics. Unless they
+declare an explicit `traversal`, ordering is the primary traversal and context
+role family; hierarchy direction and cardinality remain enforceable integrity
+constraints. This ordering-first precedence is shared by registry snapshots and
+direct-edge context explanations.
+
+Dependency additions and removals share the same lossless input grammar. A
+bare value is an item id; structured removal input uses `id=<id>` plus optional
+canonical `kind` (with `type` accepted only as an input alias), `source_kind`, `author`, and ISO `created_at`
+selectors. Supplying all stored coordinates retires exactly one dependency row
+without deleting siblings that share an id and kind. Punctuation-shaped shorthand such as
+`OTHER,related` is rejected with `dependency_flag_value_invalid` on both
+`--dep` and `--dep-remove`, before prefix normalization can turn it into a
+dangling id. A removal selector that matches no stored row fails with
+`dependency_remove_no_match` and returns the unmatched selectors plus compact
+available identities. Re-adding a stored dependency identity is idempotent; if
+legacy storage contains that exact identity more than once, the same mutation
+collapses the touched copies to one without creating an edge-absence window.
+The stored identity includes normalized `id`, `kind`, `source_kind`, `author`,
+and creation instant, so provenance-distinct sibling rows remain independent.
+
+## Hierarchy integrity
+
+The registry's `hierarchy`, `hierarchyDirection`, `outgoing`, and `incoming`
+fields are executable contracts. Scalar `parent` metadata and every registered
+hierarchy dependency spelling normalize into the same parent-to-child relation.
+That normalized relation powers `pm list --parent`, list/get tree projections,
+child rollups, graph traversal, graph analysis, graph audit, validate, and
+health. Extensions therefore gain hierarchy behavior by registering semantics;
+consumers do not hard-code kind names.
+
+Create and update transactions reject a newly introduced hierarchy cycle,
+registry cardinality violation, or scalar/dependency direction contradiction
+before persistence. Existing debt remains readable and repairable. Active debt
+is gate-failing in graph governance and health; defects confined to terminal
+items are labeled legacy and are never mutated automatically. `pm validate`
+reports cycle, cardinality, and parent-divergence counts and exact bounded rows,
+while `pm graph analyze` exposes a compact `hierarchy` summary.
+
 `recurs_from` has no alias: a later occurrence points to an earlier occurrence.
 It is persistent after both items become terminal and carries temporal identity,
 not execution precedence. `supersedes` keeps replacement semantics, while

package/docs/DIAGNOSTIC_OUTPUT_CONTRACTS.md

@@ -0,0 +1,98 @@
+# Diagnostic Output Contracts
+
+Tracker references: [pm-cha95z](../.agents/pm/tasks/pm-cha95z.toon), [pm-5t33or](../.agents/pm/features/pm-5t33or.toon), [pm-f05lsg](../.agents/pm/features/pm-f05lsg.toon), and [pm-h8tpeh](../.agents/pm/features/pm-h8tpeh.toon).
+
+## Agent Quick Context
+
+Failures are context-management surfaces. Every diagnostic family now declares
+a format-aware token ceiling and one degradation ladder in the public SDK:
+
+| Class                | Text | JSON | Corrective action that survives degradation |
+| -------------------- | ---: | ---: | ------------------------------------------- |
+| `error`              |  768 | 2000 | required action, retry/domain, or next step |
+| `warning`            |  768 | 2000 | required action, retry/domain, or next step |
+| `validation_summary` | 1500 | 3000 | required action, retry/domain, or next step |
+| `recovery_bundle`    |  768 | 2000 | required action, retry/domain, or next step |
+
+The smallest explicit ceiling is 192 estimated tokens. At that floor, the
+projector may reduce the diagnostic to its code, required action, compact
+recovery, and exit status. It never removes the first corrective action.
+
+## SDK Contract
+
+Use the public contract surface rather than maintaining a package-local error
+budget:
+
+```ts
+import {
+  PM_DIAGNOSTIC_OUTPUT_BUDGET_CONTRACTS,
+  projectPmDiagnosticOutput,
+  projectPmDiagnosticText,
+  resolvePmDiagnosticOutputBudget,
+} from "@unbrained/pm-cli/sdk/contracts";
+
+const contract = resolvePmDiagnosticOutputBudget("error");
+const projected = projectPmDiagnosticOutput(
+  {
+    code: "invalid_argument_value",
+    required: "Use --status open and retry.",
+    recovery: { suggested_retry: "pm list --status open" },
+    detail: "The supplied status is not declared.",
+    exit_code: 2,
+  },
+  { maxEstimatedTokens: contract.minimum_max_estimated_tokens },
+);
+
+const text = projectPmDiagnosticText(
+  "A long rendered diagnostic",
+  "Use --status open and retry.",
+).output;
+```
+
+The JSON projector orders `code`, `required`, recovery, and next steps before
+explanation. Untruncated diagnostics add no per-call receipt overhead; their
+binding declaration is discoverable from `pm contracts --full --json` under
+`diagnostic_output_contracts`. When degradation occurs, the returned
+`diagnostic_output` receipt records the effective budget, original and emitted
+estimates, applied stages, and omitted top-level fields. Minimal fallbacks bound
+the named omission list and disclose any additional count through
+`omitted_fields_overflow_count`.
+
+The deterministic ladder is:
+
+1. full diagnostic;
+2. omit explanation;
+3. limit diagnostic collections;
+4. compact recovery to actionable keys;
+5. retain the action-only envelope.
+
+Human diagnostics lead with `What is required` and next steps before explaining
+what happened. If their declared ceiling binds, the compact text still begins
+with the required action and points to structured JSON for the bounded recovery
+envelope.
+
+## Executable Assurance
+
+`pnpm quality:recovery-closure` builds the current CLI and replays 22 refusal
+contracts in isolated trackers. Ten representative, high-frequency failure
+paths are also ratcheted by
+`scripts/release/diagnostic-output-baseline.json`. The gate requires every row
+to remain within the SDK-declared JSON ceiling and retain a mechanically
+actionable correction. It reports the aggregate original and emitted token
+estimates without claiming a reduction when no degradation was required.
+
+The baseline is a coverage ratchet, not permission to weaken a ceiling. Its
+negative control requires a missing baseline probe to fail. The existing
+refusal-closure negative controls independently prove that incomplete domains,
+broken retries, and malformed recovery envelopes remain blocking findings.
+
+Run the focused proof with:
+
+```bash
+pnpm build
+node scripts/release/refusal-closure-gate.mjs
+node scripts/run-tests.mjs test -- \
+  tests/unit/sdk/agent-output-contracts.spec.ts \
+  tests/unit/cli/error-guidance.spec.ts \
+  tests/unit/scripts/refusal-closure-gate.spec.ts
+```

package/docs/EXTENSIONS.md

@@ -45,6 +45,7 @@ pm install kanban --project
 External registry packages are installed by exact package name. If `npm:<name>` returns a registry 404, JSON error output includes `fallback_candidates` and `next_best_command`; unpublished first-party packages fall back to `pm install --project github.com/unbraind/<name>`. Install results include package-owned `command_paths`, `action_paths`, `contributions`, `command_discovery`, and a light `verification` block covering the target tracker, activation status, registered commands/actions/item types, and health verdict. Agents should consume those fields instead of guessing from the package name or immediately spending another invocation on doctor. A successful activation persists the versioned contribution inventory in `.managed-extensions.json`; subsequent discovery can enumerate command handlers, hooks, parser/renderer targets, schema names, and the other registered surfaces without importing the package module. A failed runtime activation returns `ok: false`, `activated: false`, a non-zero CLI exit, and actionable diagnostics; missing SDK resolution adds an explicit dependency recovery step. Local installs are containment-safe when the extension destination is nested inside the source checkout: pm stages the package outside the source and prunes the destination, `.agents`, `node_modules`, and install-backup directories before copying, so reinstalling cannot recursively copy tracker history, host dependencies, or prior backups.
 Local `.tgz` and `.tar.gz` npm archives are inspected and extracted in an isolated temporary directory without invoking a shell. Archives must contain one `package/package.json` root, regular files/directories only, and bounded entry and expanded-byte totals. Absolute paths, traversal, alternate roots, links, device entries, oversized entries, and decompression-ratio abuse fail before installation. The managed source remains the original archive path, so reload and upgrade provenance do not point at a temporary extraction directory.
 Registry dependency names and versions are parsed as npm package specs before the install subprocess starts. Leading-option names and shell control syntax are rejected. npm reads those validated dependencies from an isolated runtime-only manifest; no caller-controlled spec is forwarded through the Windows command shell, and the fixed invocation still ends option parsing with `--`. Runtime verification then activates a temporary snapshot of the complete installed extension directory, so an upgrade cannot silently reuse stale transitive ESM dependencies from the current process. Successful install details expose `module_graph_verification: "fresh_snapshot"` for this check.
+pm-owned npm subprocesses clear any inherited, case-insensitive `npm_config_allow_scripts` value while retaining registry, auth, proxy, and executable-path environment; `--ignore-scripts` remains authoritative. Tracked by [pm-gh1072](../.agents/pm/issues/pm-gh1072.toon).
 An explicit `--pm-path` scopes project installs to that tracker root, including extension files, managed state, settings, type-folder scaffolding, and verification output. This is the safe form for temporary package testing from inside another repository checkout.
 
 ```bash
@@ -308,7 +309,7 @@ Common APIs:
 - `api.registerMigration(definition)` adds schema migrations.
 - `api.registerProfile(profile)` contributes a project profile — a declarative archetype bundling item types, statuses, fields, per-type workflows, config, templates, and package recommendations. Once active it resolves by name through `pm profile list/show/apply` alongside the core `agile`/`ops`/`research` archetypes (built-in names are reserved; a colliding registration is ignored with a warning). Requires the `schema` capability.
 - `api.registerAssuranceMeasurementProvider(provider)` contributes typed measurements to assurance. It requires `services`; network providers also require manifest `permissions.network: true`. Gates allow providers and cost/network limits per trigger. See [Project Assurance Primitives](ASSURANCE.md#extension-measurement-providers) for examples.
-- `api.registerService("output_format", handler)` customizes output formatting through the service override API. Use `handleServiceOverride(result)` to claim a payload and return the scaffold-compatible literal `{ handled: false }` (or `declineServiceOverride()`) for commands the extension does not own. Legacy `null`/`undefined` declines remain supported; returning the original payload is now an unambiguous handled result.
+- `api.registerService("output_format", handler, ownership?)` customizes output formatting through the service override API. Use `handleServiceOverride(result)` to claim a payload and return the scaffold-compatible literal `{ handled: false }` (or `declineServiceOverride()`) for commands the extension does not own. An override that is unconditionally inert can declare `{ passThrough: true }`; the host then ignores and diagnoses any handled result, and package doctor treats the registration as statically safe. Legacy `null`/`undefined` declines remain supported; returning the original payload is now an unambiguous handled result. Tracked by [pm-gh1074](../.agents/pm/issues/pm-gh1074.toon).
 - `api.registerRenderer("toon" | "json", renderer, ownership?)` adds format-specific renderers. Scope ownership with `commands` and/or a `resultDiscriminator`; the host checks both before invoking the renderer and falls back to native rendering for unrelated output. The legacy unscoped callback remains supported, but doctor warns because package ownership cannot be proven statically.
 - `suppressHostOutput(result?)` from `@unbrained/pm-cli/sdk` marks commands that already wrote output, preventing a second CLI payload while retaining the optional result for hooks, telemetry, and embedded hosts.
 - `api.hooks.beforeCommand(handler)`, `api.hooks.beforeMutation(handler)`, `api.hooks.afterCommand(handler)`, `api.hooks.onWrite(handler)`, `api.hooks.onRead(handler)`, and `api.hooks.onIndex(handler)` add lifecycle hooks.

package/docs/README.md

@@ -51,6 +51,7 @@ pm guide release --json
 - [SDK Context Platform](SDK_CONTEXT.md) - task-oriented entry point for authoritative reads, ranking, package workflows, diagnostics, recovery, and verification.
 - [Self-Describing Context Contracts](SELF_DESCRIBING_CONTEXT_CONTRACTS.md) - intent-scoped reads, semantic flag invocation metadata, visibility parity, and generated error vocabulary.
 - [Universal Read Output Contracts](READ_OUTPUT_CONTRACTS.md) - cross-command include, amount, cost, and encoding controls for CLI, SDK, MCP, and packages.
+- [Diagnostic Output Contracts](DIAGNOSTIC_OUTPUT_CONTRACTS.md) - action-first error budgets, deterministic degradation, SDK projection, and executable refusal assurance.
 - [Mutation Integrity](MUTATION_INTEGRITY.md) - shared CLI/SDK/MCP author, secret, append-only disposition, and stale-work guardrails.
 - [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.

package/docs/READ_OUTPUT_CONTRACTS.md

@@ -1,6 +1,6 @@
 # Universal Read Output Contracts
 
-Tracker references: [pm-hb7ug8](../.agents/pm/features/pm-hb7ug8.toon), [pm-cxr0jb](../.agents/pm/features/pm-cxr0jb.toon), [pm-hid9g1](../.agents/pm/features/pm-hid9g1.toon), [pm-h8tpeh](../.agents/pm/features/pm-h8tpeh.toon), [pm-5t33or](../.agents/pm/features/pm-5t33or.toon), [pm-sb0tns](../.agents/pm/issues/pm-sb0tns.toon), [pm-gjjurs](../.agents/pm/issues/pm-gjjurs.toon), [pm-eugaqy](../.agents/pm/issues/pm-eugaqy.toon), [pm-jt8aa2](../.agents/pm/issues/pm-jt8aa2.toon), [pm-kyjdne](../.agents/pm/issues/pm-kyjdne.toon), [pm-8nev0o](../.agents/pm/issues/pm-8nev0o.toon), [pm-e5gl05](../.agents/pm/issues/pm-e5gl05.toon), [pm-cha95z](../.agents/pm/tasks/pm-cha95z.toon), and [pm-2qvq7a](../.agents/pm/issues/pm-2qvq7a.toon).
+Tracker references: [pm-hb7ug8](../.agents/pm/features/pm-hb7ug8.toon), [pm-cxr0jb](../.agents/pm/features/pm-cxr0jb.toon), [pm-hid9g1](../.agents/pm/features/pm-hid9g1.toon), [pm-h8tpeh](../.agents/pm/features/pm-h8tpeh.toon), [pm-5t33or](../.agents/pm/features/pm-5t33or.toon), [pm-srns](../.agents/pm/issues/pm-srns.toon), [pm-sb0tns](../.agents/pm/issues/pm-sb0tns.toon), [pm-gjjurs](../.agents/pm/issues/pm-gjjurs.toon), [pm-eugaqy](../.agents/pm/issues/pm-eugaqy.toon), [pm-jt8aa2](../.agents/pm/issues/pm-jt8aa2.toon), [pm-kyjdne](../.agents/pm/issues/pm-kyjdne.toon), [pm-8nev0o](../.agents/pm/issues/pm-8nev0o.toon), [pm-e5gl05](../.agents/pm/issues/pm-e5gl05.toon), [pm-cha95z](../.agents/pm/tasks/pm-cha95z.toon), and [pm-2qvq7a](../.agents/pm/issues/pm-2qvq7a.toon).
 
 ## Agent Quick Context
 
@@ -140,7 +140,7 @@ pm stats --output-row-contract
 pm contracts --full --json
 ```
 
-Every projected result carries a `read_output` receipt with the requested dimensions, precedence, observed compatibility aliases, deterministic estimated token count, string/row compaction signals, and budget outcome. Budget degradation discovers nested arrays as well as declared result rows, so validation diagnostics and other governance payloads compact their inner findings before the useful result is omitted. `compacted_row_paths` names every reduced collection without redefining those nested arrays as ordinary pagination rows.
+Every projected result carries a `read_output` receipt with the requested dimensions, precedence, observed option provenance, deterministic estimated token count, string/row compaction signals, and budget outcome. When canonical controls are present, `canonical_options_used` records spellings such as `--output-include`; the optional field is omitted when no canonical control was supplied so minimum-budget session receipts remain compact. `legacy_aliases_used` and `migration_hints` record only compatibility flags the caller actually supplied. A command-local flag synthesized internally to execute a canonical projection mode is therefore never misreported as deprecated syntax. When both spellings are supplied, both provenance arrays report that mixed invocation. Budget degradation discovers nested arrays as well as declared result rows, so validation diagnostics and other governance payloads compact their inner findings before the useful result is omitted. `compacted_row_paths` names every reduced collection without redefining those nested arrays as ordinary pagination rows.
 
 When rows are dropped to satisfy a ceiling, the result also carries `output_budget_truncation`, naming the binding budget and its source, any explicitly requested dimension the budget overrode, every compacted collection path, and executable CLI/SDK/MCP recovery options — a default ceiling can override an explicit `--output-limit unbounded`, and that override is reported rather than silent. If a producer supplied an opaque item-page cursor, compaction rebases it to the last row actually returned and reports `continuation_cursor_rebased: true`; following the cursor therefore cannot skip rows removed from the middle of a producer page. If no useful content can fit, `PmReadOutputBudgetExceeded` provides a discriminated omission result, a compact `{ outputBudget: "unbounded" }` recovery object, and `omitted_result_estimated_tokens`, the last useful-result estimate before omission; use `isReadOutputBudgetExceeded` before accessing result-specific fields. Universal controls are rejected on mutation commands and on the mutation mode of hybrid commands such as `comments`, `notes`, `files`, and `docs`.
 
@@ -179,6 +179,13 @@ key. Health retains at most 100 warning rows and reports `warning_count`,
 projection unless `--full` is explicit, keeping the failing check identities
 and warning codes inside the ordinary budget.
 
+Failure transports use the companion
+[Diagnostic Output Contracts](DIAGNOSTIC_OUTPUT_CONTRACTS.md). Those contracts
+bind errors, warnings, validation summaries, and recovery bundles independently
+from successful command results. Corrective actions precede explanation and
+survive every degradation stage, while untruncated JSON avoids a per-call
+receipt tax.
+
 ## SDK and Package Usage
 
 Typed `PmClient` read methods accept `PmReadOutputOptions` directly:

package/docs/RECURRENCE_RECOVERY_CONTRACTS.md

@@ -65,6 +65,43 @@ Generic action hosts use `item-reopen` with required `id` and `reason` fields.
 The action participates in the generated action schema, SDK dispatch coverage,
 CLI/SDK parameter parity, command grammar, and MCP `pm_run` surface.
 
+## Tracker Preflight Recovery
+
+Every SDK command that requires project state now enters through one shared
+filesystem preflight instead of maintaining a command-local settings check.
+The public aggregate SDK exposes the same primitive for packages and embedded
+hosts:
+
+```ts
+import {
+  assertInitializedTracker,
+  assertReadableTrackerRoot,
+} from "@unbrained/pm-cli/sdk";
+
+await assertReadableTrackerRoot(candidateRoot); // an empty directory is valid
+await assertInitializedTracker(projectRoot); // settings.json is required
+```
+
+The refusal contract distinguishes four states before any command-specific
+read or mutation begins:
+
+| Selected root state | Code | Exit | Recovery |
+| --- | --- | ---: | --- |
+| Path does not exist | `tracker_root_missing` | 3 | Tokenized, non-interactive `pm --pm-path <path> init --defaults --agent-guidance skip` |
+| Directory exists but `settings.json` does not | `tracker_not_initialized` | 3 | The same initialization retry |
+| Path or ancestor is a regular file | `tracker_root_not_directory` | 2 | Select a directory; never suggest `pm init` against the file |
+| Directory cannot be read or searched | `tracker_root_unreadable` | 1 | Repair permissions, then retry the same selected root |
+
+`listTrackerPreflightRecoveryContracts` publishes this four-state corpus from
+`@unbrained/pm-cli/sdk/contracts`.
+`scoreTrackerPreflightRecoveryClosure` verifies code, exit class, recovery kind,
+and executable retry evidence. The repository recovery gate runs these probes
+beside the 18 closed-domain probes, so its ratcheted corpus is 22 and a removed
+state, failed retry, or unsafe file-path initialization suggestion blocks the
+release. The surface-replication gate separately requires at least 50 shared
+preflight invocations across the 45 migrated SDK modules and forbids the former
+inline error body from returning.
+
 ## Duplicate Intake
 
 Create and copy similarity governance inspect all lifecycle statuses. The

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,17 +298,28 @@ 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
 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.
+terminal population. Detailed output's nested SDK profile census,
+`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. The top-level audit and persisted-baseline census is
+`affected_subjects_by_code`; both fields count affected subjects, but their
+locations and consumers differ and neither is an alias for the other.
 
 ```ts
 import {
@@ -318,6 +346,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/docs/TESTING.md

@@ -366,6 +366,18 @@ The manifest records baseline bytes and estimated tokens for visible review
 deltas. Updating it cannot raise answer ceilings, which remain owned by
 `PM_COMMAND_OUTPUT_BUDGET_CONTRACTS`.
 
+Diagnostic ceilings share the executable refusal gate:
+
+```bash
+pnpm quality:recovery-closure
+```
+
+The gate replays 22 refusal contracts and ratchets ten representative failure
+paths against `PM_DIAGNOSTIC_OUTPUT_BUDGET_CONTRACTS`. Every diagnostic must fit
+its declared JSON ceiling and preserve a mechanically actionable correction;
+the missing-probe negative control proves that the diagnostic corpus cannot
+silently shrink.
+
 The gate derives every supported harness, model, session, and provenance
 environment key from the SDK-owned harness descriptor registry. It deletes
 those host inputs before each fixture invocation, then supplies only the
@@ -480,6 +492,9 @@ pm test <item-id> --metric-below coverage=100 --metric-diff p95_latency
 
 Measurements are stored on the producing `test_runs` row, retained with the
 bounded run history, and exposed consistently by CLI, SDK, MCP, and contracts.
+Each recorded row also keeps a bounded `executions` list with the exact linked
+command plus its requested and effective `pm_context_mode`, so tracker-backed
+verification remains attributable after the transient process logs are gone.
 
 ## Linked-Test Assertions
 

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.22"
   },
   "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.22",
       "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.22",
   "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.22",
   "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.22",
   "private": true,
   "type": "module",
   "description": "First-party pm package for calendar and agenda views.",