@unbrained/pm-cli 2026.10.11 → 2026.10.13

package/dist/types.js

@@ -1,2 +1,2 @@
-(function(){try{var e=typeof window<"u"?window:typeof global<"u"?global:typeof globalThis<"u"?globalThis:typeof self<"u"?self:{},n=new e.Error().stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="e6847fdd-b2c1-5503-b510-56fdfdcf933f")}catch{}})();const BUILTIN_ITEM_TYPE_VALUES=["Epic","Feature","Task","Chore","Issue","Decision","Event","Reminder","Milestone","Meeting","Plan"],ITEM_TYPE_VALUES=BUILTIN_ITEM_TYPE_VALUES,STATUS_VALUES=["draft","open","in_progress","blocked","closed","canceled"],RUNTIME_STATUS_ROLE_VALUES=["draft","active","blocked","terminal","terminal_done","terminal_canceled","default_open","default_close","default_cancel"],RUNTIME_FIELD_TYPE_VALUES=["string","number","boolean","string_array","array","object"],RUNTIME_FIELD_COMMAND_VALUES=["create","update","update_many","list","search","calendar","context"],RUNTIME_UNKNOWN_FIELD_POLICY_VALUES=["allow","warn","reject"],DEPENDENCY_KIND_VALUES=["blocks","parent","child","parent_child","child_of","related","related_to","discovered_from","blocked_by","incident_from","epic","implements","recurs_from","supersedes","task","verifies"],SCOPE_VALUES=["project","global"],RISK_VALUES=["low","medium","high","critical"],ISSUE_SEVERITY_VALUES=["low","medium","high","critical"],CONFIDENCE_TEXT_VALUES=["low","medium","high"],ITEM_FORMAT_VALUES=["toon","json_markdown"],SPRINT_RELEASE_FORMAT_POLICY_VALUES=["warn","strict_error"],PARENT_REFERENCE_POLICY_VALUES=["warn","strict_error"],VALIDATE_METADATA_PROFILE_VALUES=["core","strict","custom"],GOVERNANCE_PRESET_VALUES=["minimal","default","strict","custom"],GOVERNANCE_OWNERSHIP_ENFORCEMENT_VALUES=["none","warn","strict"],GOVERNANCE_CREATE_MODE_DEFAULT_VALUES=["progressive","strict"],GOVERNANCE_CLOSE_VALIDATION_DEFAULT_VALUES=["off","warn","strict"],GOVERNANCE_WORKFLOW_ENFORCEMENT_VALUES=["off","warn","strict"],GOVERNANCE_DUPLICATE_DETECTION_MODE_VALUES=["off","advisory","strict"],VALIDATE_METADATA_REQUIRED_FIELD_VALUES=["author","acceptance_criteria","estimated_minutes","close_reason","reviewer","risk","confidence","sprint","release"],RECURRENCE_FREQUENCY_VALUES=["daily","weekly","monthly","yearly"],RECURRENCE_WEEKDAY_VALUES=["mon","tue","wed","thu","fri","sat","sun"];function weekdayOrderIndex(value){return RECURRENCE_WEEKDAY_VALUES.indexOf(value)}const PLAN_MODE_VALUES=["draft","research","review","approved","executing","paused","completed","superseded"],PLAN_STEP_STATUS_VALUES=["pending","in_progress","completed","blocked","skipped","superseded"],PLAN_HARNESS_VALUES=["codex","claude-code","cursor","generic"],PLAN_STEP_LINK_KIND_VALUES=["related","blocks","blocked_by","depends_on","discovered_from","implements","recurs_from","verifies","supersedes"],CONTEXT_DEPTH_VALUES=["brief","standard","deep","full"],CONTEXT_SECTION_VALUES=["hierarchy","activity","progress","recently_created","unparented","blockers","files","workload","staleness","tests"];export{BUILTIN_ITEM_TYPE_VALUES,CONFIDENCE_TEXT_VALUES,CONTEXT_DEPTH_VALUES,CONTEXT_SECTION_VALUES,DEPENDENCY_KIND_VALUES,GOVERNANCE_CLOSE_VALIDATION_DEFAULT_VALUES,GOVERNANCE_CREATE_MODE_DEFAULT_VALUES,GOVERNANCE_DUPLICATE_DETECTION_MODE_VALUES,GOVERNANCE_OWNERSHIP_ENFORCEMENT_VALUES,GOVERNANCE_PRESET_VALUES,GOVERNANCE_WORKFLOW_ENFORCEMENT_VALUES,ISSUE_SEVERITY_VALUES,ITEM_FORMAT_VALUES,ITEM_TYPE_VALUES,PARENT_REFERENCE_POLICY_VALUES,PLAN_HARNESS_VALUES,PLAN_MODE_VALUES,PLAN_STEP_LINK_KIND_VALUES,PLAN_STEP_STATUS_VALUES,RECURRENCE_FREQUENCY_VALUES,RECURRENCE_WEEKDAY_VALUES,RISK_VALUES,RUNTIME_FIELD_COMMAND_VALUES,RUNTIME_FIELD_TYPE_VALUES,RUNTIME_STATUS_ROLE_VALUES,RUNTIME_UNKNOWN_FIELD_POLICY_VALUES,SCOPE_VALUES,SPRINT_RELEASE_FORMAT_POLICY_VALUES,STATUS_VALUES,VALIDATE_METADATA_PROFILE_VALUES,VALIDATE_METADATA_REQUIRED_FIELD_VALUES,weekdayOrderIndex};
+(function(){try{var e=typeof window<"u"?window:typeof global<"u"?global:typeof globalThis<"u"?globalThis:typeof self<"u"?self:{},n=new e.Error().stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="459c0cce-212f-5285-9c3b-13676d2388af")}catch{}})();const BUILTIN_ITEM_TYPE_VALUES=["Epic","Feature","Task","Chore","Issue","Decision","Event","Reminder","Milestone","Meeting","Plan"],ITEM_TYPE_VALUES=BUILTIN_ITEM_TYPE_VALUES,STATUS_VALUES=["draft","open","in_progress","blocked","closed","canceled"],RUNTIME_STATUS_ROLE_VALUES=["draft","active","blocked","terminal","terminal_done","terminal_canceled","default_open","default_close","default_cancel"],RUNTIME_FIELD_TYPE_VALUES=["string","number","boolean","string_array","array","object"],RUNTIME_FIELD_COMMAND_VALUES=["create","update","update_many","list","search","calendar","context"],RUNTIME_UNKNOWN_FIELD_POLICY_VALUES=["allow","warn","reject"],DEPENDENCY_KIND_VALUES=["blocks","parent","child","parent_child","child_of","related","related_to","discovered_from","blocked_by","incident_from","epic","implements","recurs_from","supersedes","task","verifies"],SCOPE_VALUES=["project","global"],RISK_VALUES=["low","medium","high","critical"],ISSUE_SEVERITY_VALUES=["low","medium","high","critical"],CONFIDENCE_TEXT_VALUES=["low","medium","high"],ITEM_FORMAT_VALUES=["toon","json_markdown"],SPRINT_RELEASE_FORMAT_POLICY_VALUES=["warn","strict_error"],PARENT_REFERENCE_POLICY_VALUES=["warn","strict_error"],VALIDATE_METADATA_PROFILE_VALUES=["core","strict","custom"],GOVERNANCE_PRESET_VALUES=["minimal","default","strict","custom"],GOVERNANCE_OWNERSHIP_ENFORCEMENT_VALUES=["none","warn","strict"],GOVERNANCE_CREATE_MODE_DEFAULT_VALUES=["progressive","strict"],GOVERNANCE_CLOSE_VALIDATION_DEFAULT_VALUES=["off","warn","strict"],GOVERNANCE_WORKFLOW_ENFORCEMENT_VALUES=["off","warn","strict"],GOVERNANCE_DUPLICATE_DETECTION_MODE_VALUES=["off","advisory","strict"],VALIDATE_METADATA_REQUIRED_FIELD_VALUES=["author","acceptance_criteria","estimated_minutes","close_reason","reviewer","risk","confidence","sprint","release"],RECURRENCE_FREQUENCY_VALUES=["daily","weekly","monthly","yearly"],RECURRENCE_WEEKDAY_VALUES=["mon","tue","wed","thu","fri","sat","sun"];function weekdayOrderIndex(value){return RECURRENCE_WEEKDAY_VALUES.indexOf(value)}const PLAN_MODE_VALUES=["draft","research","review","approved","executing","paused","completed","superseded"],PLAN_STEP_STATUS_VALUES=["pending","in_progress","completed","blocked","skipped","superseded"],PLAN_HARNESS_VALUES=["codex","claude-code","cursor","generic"],PLAN_STEP_LINK_KIND_VALUES=["related","blocks","blocked_by","depends_on","discovered_from","implements","recurs_from","verifies","supersedes"],CONTEXT_DEPTH_VALUES=["brief","standard","deep","full"],CONTEXT_SECTION_VALUES=["hierarchy","activity","progress","recently_created","unparented","blockers","files","workload","staleness","tests"];export{BUILTIN_ITEM_TYPE_VALUES,CONFIDENCE_TEXT_VALUES,CONTEXT_DEPTH_VALUES,CONTEXT_SECTION_VALUES,DEPENDENCY_KIND_VALUES,GOVERNANCE_CLOSE_VALIDATION_DEFAULT_VALUES,GOVERNANCE_CREATE_MODE_DEFAULT_VALUES,GOVERNANCE_DUPLICATE_DETECTION_MODE_VALUES,GOVERNANCE_OWNERSHIP_ENFORCEMENT_VALUES,GOVERNANCE_PRESET_VALUES,GOVERNANCE_WORKFLOW_ENFORCEMENT_VALUES,ISSUE_SEVERITY_VALUES,ITEM_FORMAT_VALUES,ITEM_TYPE_VALUES,PARENT_REFERENCE_POLICY_VALUES,PLAN_HARNESS_VALUES,PLAN_MODE_VALUES,PLAN_STEP_LINK_KIND_VALUES,PLAN_STEP_STATUS_VALUES,RECURRENCE_FREQUENCY_VALUES,RECURRENCE_WEEKDAY_VALUES,RISK_VALUES,RUNTIME_FIELD_COMMAND_VALUES,RUNTIME_FIELD_TYPE_VALUES,RUNTIME_STATUS_ROLE_VALUES,RUNTIME_UNKNOWN_FIELD_POLICY_VALUES,SCOPE_VALUES,SPRINT_RELEASE_FORMAT_POLICY_VALUES,STATUS_VALUES,VALIDATE_METADATA_PROFILE_VALUES,VALIDATE_METADATA_REQUIRED_FIELD_VALUES,weekdayOrderIndex};
 //# sourceMappingURL=types.js.map

package/docs/BUILD_AND_RELEASE_ACCEPTANCE.md

@@ -7,7 +7,7 @@ Trackers: [pm-cxc4jc](../.agents/pm/tasks/pm-cxc4jc.toon),
 
 ## Build ownership
 
-Build/test/coverage sessions own `.cache/build-lease` through completion;
+Build/test/coverage and distribution-packing sessions own `.cache/build-lease` through completion;
 other producers/consumers wait twenty minutes. Nested readers inherit a verified
 PID/token receipt; nested builds require independent workspaces. Direct stages
 and arbitrary `dist` reads bypass this protocol.
@@ -16,7 +16,10 @@ Leases never expire or get stolen. Two matching reads proving PID absence fail
 promptly with recovery guidance. Missing/malformed/changing/ambiguous receipts
 use the timeout; PID reuse is ambiguous. Inspect owner and children before
 abandoned-lease removal. Failed builds leave `.cache/build-incomplete`; prebuilt
-tests refuse it until a successful build.
+tests and distribution packing refuse it until a successful build. Packing holds
+the lease from source inventory through isolated staging and the final archive;
+its asynchronous helper validates inherited consumer receipts in the same
+physical workspace. See [SDK consumer receipts](SDK_CONSUMER_RECEIPTS.md).
 
 Interrupts stop the child and stage admission, allowing five seconds for
 settlement, lease release and cleanup; unsettled children retain storage.

package/docs/DEFECT_RECURRENCE.md

@@ -51,6 +51,18 @@ Each report explains its exact matching signals, returns deduplicated local and
 
 `assurance risk` accepts one JSON request through the same `definition` transport already used by SDK and MCP hosts:
 
+Discovery recovery is tracked by [pm-assurance-risk-help-policy](../.agents/pm/issues/pm-assurance-risk-help-policy.toon).
+Both `policy` and `change` are required. Help includes an executable minimal
+example with an explicitly empty family list; it demonstrates the request
+shape and makes no project coverage claim. Use the project's declared policy
+for real decisions, as below. A missing or invalid policy object returns
+structured help recovery without choosing a policy on the caller's behalf.
+SDK policy parsing throws `DefectRecurrencePolicyParseError`, a `TypeError`
+subclass exported by the root and governance entrypoints. This identifies
+policy validation without depending on message text; its stable `code` is
+`defect_recurrence_policy_invalid`. Change and lineage
+validation retain their separate error contracts.
+
 ```bash
 risk_request=$(jq -cn \
   --slurpfile policy config/defect-recurrence-policy.json \

package/docs/EXTENSIONS.md

@@ -304,12 +304,12 @@ Doctor JSON also includes `triage.collision_plan` with grouped surfaces, ranked
 Use the public SDK barrel. Do not deep-import from `src/core` or `dist/core`.
 
 - `api.extension` is a read-only identity (`name`, `layer`, `version`, `capabilities`, `pm_min_version?`, `pm_max_version?`, `source_package?`) for self-identifying logs and version gating without re-reading the manifest.
-- `api.registerCommand(definition)` adds package-owned commands.
+- `api.registerCommand(definition)` adds package-owned commands; `read_output` opts readers into the [SDK output contract](SDK.md#minimal-command-extension).
 - `api.registerFlags(command, flags)` adds runtime command flags. A flag may declare `value_type` (canonical; the legacy `type` alias is honored only when `value_type` is absent), `list: true` to accumulate repeated/comma-joined values like core `--tags`, and a `default` applied when the flag is omitted.
 - `api.registerItemFields(fields)` adds custom metadata fields. Agents can set declared fields with repeatable `pm create --field name=value` and `pm update <id> --field name=value`; undeclared names are rejected. `SchemaFieldDefinition.type` is the same closed union used by `pm schema add-field`: `string | number | boolean | string_array | array | object`. Unsupported values fail at compile time for TypeScript authors and at activation for JavaScript packages, with a did-you-mean hint on typos. `string_array` is the repeatable string collection; `array` and `object` require JSON containers.
 - Custom fields whose camel-case option name is already owned by a canonical MCP input remain usable through `options.<name>`, but authoring surfaces report the collision instead of allowing silent top-level shadowing. `pm schema add-field`, `pm profile lint`, and `pm package doctor` name the field, canonical `mcp_tool_input` owner, and nested recovery path. SDK authors can preflight the same rule with `resolvePmToolCustomFieldCollision`.
 - `api.registerItemTypes(types)` adds custom item types.
-- `api.registerRelationshipKinds(definitions)` adds validated graph semantics. Definitions declare direction, inverse spelling, ordering/precedence, hierarchy, cardinality, lifecycle, aliases, payload schema, compatibility version, and self-edge policy. Active definitions are merged into native CLI, MCP, and SDK workspace graph assembly. Requires the `schema` capability and is governed by the `schema.relationshipkinds` policy surface.
+- `api.registerRelationshipKinds(definitions)` adds validated graph semantics. Definitions declare direction, inverse spelling, ordering/precedence, hierarchy, cardinality, lifecycle, aliases, payload schema, compatibility version, and self-edge policy. Active definitions govern CLI, MCP, and SDK dependency mutation admission as well as workspace graph assembly; mutation aliases are stored canonically. Requires the `schema` capability and is governed by the `schema.relationshipkinds` policy surface. See [relationship mutation admission](RELATIONSHIP_GRAPH.md#contract), tracked by [pm-7dsolo](../.agents/pm/issues/pm-7dsolo.toon).
 - `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.

package/docs/LINKED_TEST_EDITS.md

@@ -0,0 +1,79 @@
+# Linked-test metadata edits and configuration refusals
+
+Trackers: [pm-9djr6d](../.agents/pm/tasks/pm-9djr6d.toon),
+[pm-gh1440](../.agents/pm/issues/pm-gh1440.toon).
+
+Correct a linked test without removing and re-adding it:
+
+```bash
+pm test <item-id> --list
+pm test <item-id> --update-index 1 --set-json '{"note":"Verified coverage gate","timeout_seconds":900}'
+pm test <item-id> --update 'command=node scripts/check.mjs' --set-json '{"note":"Updated evidence"}'
+pm test <item-id> --update 'path=tests/check.mjs' --set-json '{"note":null}'
+```
+
+Each edit patches only explicit metadata fields. The entry keeps its position,
+command and original `provenance`; changed entries gain `updated_by` and
+`updated_at`. An unchanged normalized retry writes no item or history bytes.
+One `tests_update` history event carries field-level patches plus the edited
+index and metadata field names in `context.linked_test_update`.
+
+Use `null` to clear an optional field, such as a note, path or timeout. Scope is
+required and cannot be cleared. Every entry must retain a nonblank command or path:
+replace a path-only entry's path rather than clearing its last identity.
+Unknown fields, command changes, provenance
+changes and editor-stamp overrides are refused. To change the command, remove
+and add it through the ordinary provenance-recording workflow. Editing context
+or environment controls changes the clone-local trust fingerprint, so any prior
+acknowledgment must be reviewed again.
+
+Exactly one selector must match the current collection under the item lock.
+Absent selectors and ambiguous command/path matches refuse the whole edit and
+retain authoritative bytes; ambiguity names matching indexes. An index addresses
+the current list position. Durable metadata-fragment references remain tracked
+separately by [pm-gh1381](../.agents/pm/features/pm-gh1381.toon).
+Apply edits separately from listing, additions, removals, execution options,
+measurements, metric filters and trust acknowledgment. Run-level `--timeout`
+and `--progress` are refused on edits; change stored `timeout_seconds` in the
+metadata patch when needed. `--list` remains a separate read-only operation.
+
+The public SDK owns the same operation:
+
+```typescript
+import { updateLinkedTest } from "@unbrained/pm-cli/sdk/core";
+
+const receipt = await updateLinkedTest(itemId, {
+  selector: { command: "node scripts/check.mjs" },
+  patch: { note: "Verified coverage gate", timeout_seconds: 900 },
+}, { path: trackerRoot });
+```
+
+The aggregate SDK exports the same function. `PmClient.run("test", ...)` and the MCP `test`
+action accept `update` or `updateIndex` with `setJson`, matching CLI flags. The
+receipt exposes `updated_index`, `updated_fields`, and `changed`.
+For extension-owned item types, fields or mutation hooks, wrap a direct primitive
+with `runWithActiveExtensions({ cwd: projectRoot }, callback)` as described in
+[SDK transaction composition](SDK.md#schema-evolution-and-workspace-history).
+The `PmClient` action dispatcher owns this scope automatically.
+
+Linked-test mutations through `test`, `create`, `update` and the SDK refuse
+`pm_context_mode=none` unless the stored `workspace_context_mode` is `isolated`
+or `snapshot`. For example:
+
+```bash
+pm test <item-id> --add-json '{"command":"node scripts/self-isolated-check.mjs","pm_context_mode":"none","workspace_context_mode":"isolated"}'
+```
+
+The refusal code is `linked_test_context_invalid` and includes a concrete recovery
+example. Legacy invalid records remain readable. Running such a record returns
+`status: refused`, `failure_category: config_refusal`, and `exit_code: null`;
+the command never runs. The item, aggregate and background run remain unsuccessful.
+Actual child-process failures retain their observed exit code and ordinary
+execution failure category.
+
+SDK consumers with exhaustive `TestRunResult.status` or failure-category switches
+must handle `refused` and `config_refusal`. Treat a refusal as an unsuccessful
+gate, and display its recovery message; `exit_code: null` means no subprocess ran.
+Context mismatches and a missing required PM assertion also use this result.
+The `TestRunResult.exit_code` type now allows null, and `TestCommandOptions` and
+`TestResult` include the optional editor flags and receipt fields described above.

package/docs/MERGE_SAFETY.md

@@ -195,6 +195,20 @@ same complete receipt summary and disposition. An absent, unreadable, invalid,
 unsealed, or mismatched audit keeps the receipt pending in memory; inspection
 rewrites neither receipt nor history. History is verified once per affected
 item in each receipt scan.
+Historical receipt recovery is tracked by [pm-tknnzp](../.agents/pm/issues/pm-tknnzp.toon).
+Historical item-state hashes do not authenticate audit context. An older
+unsealed `merge_reconcile` summary therefore cannot retain settled state,
+even when its receipt identity, fields, and value hashes match. Editing that
+context leaves the legacy item chain valid. Keep these receipts pending for
+explicit reviewed migration to a modern sealed audit; never retroactively
+trust the old summary or synthesize an old signature during inspection.
+If compaction removed the audit, the receipt also stays pending. Preview with
+`pm merge reconcile --dry-run`; review its summaries and repair failures and
+re-apply any intended discarded values. Only with explicit review authority,
+use `pm merge reconcile --force --message "<reviewed receipt disposition and rationale>"`.
+That command appends acceptance evidence; it cannot recover missing evidence
+or restore discarded values. This migration guidance also applies to a
+lossless receipt whose snapshot proof is unavailable.
 Copy provenance includes normalized `requested_preference_applied`, so copies
 that disagree on whether preference participated cannot share lifecycle state
 even if history matches one copy. Inspection reports `copy_provenance_mismatch`,
@@ -210,6 +224,18 @@ pm merge report --include-reconciled
 
 The underlying public SDK exports are `mergeItemDocuments`, `mergeHistoryStreams`, `mergeRelationshipEventStreams`, `mergeJsonDocuments`, `runMergeDriver`, `runMergeInstall`, `installMergeFence`, `findGitWorkspaceRoot`, `runMergeReconcile`, `runMergeReceiptReport`, `runMergeReceiptEvidenceReport`, `inspectMergeReceiptEvidence`, `listMergeReceipts`, `auditMergeDriverConfiguration`, `refreshMergeAttributeFenceIfInstalled`, `buildMergeAttributePatterns`, and `auditMergeAttributeFence` from `@unbrained/pm-cli/sdk`. `installMergeFence` accepts explicit tracker and workspace roots, so custom init hosts do not depend on process cwd or CLI globals.
 
+Collection projection is tracked by [pm-pftgcz](../.agents/pm/issues/pm-pftgcz.toon).
+History union reconstructs each event in its original branch before merging
+collection values with the item driver's shared policy. Positional comment,
+doc and test patches from an earlier reconciliation therefore cannot overwrite
+an unrelated entry at the same array index on another branch. Original event
+attribution and patches remain in sealed rewrite evidence; replayed collections
+use the canonical item order and receiving-side linked-test provenance.
+The SDK reanchor primitive accepts `projectPatch` for this explicit projection
+boundary. It retains the replaced patch rather than erasing its source.
+Exact receipt settlement still requires an authoritative matching snapshot,
+and newly merged executable tests still require clone-local trust acknowledgement.
+
 `listMergeReceipts` is the compatibility projection for callers that only need
 validated receipts. It cannot distinguish an empty evidence store from a store
 whose candidates were all rejected. Gates and diagnostic integrations should
@@ -495,7 +521,7 @@ pm history-repair <item-id>
 pm merge reconcile --dry-run --json
 ```
 
-`history-repair` records the reconciliation patch and classifies its changed fields against the final item. Append-only collection unions and deterministic reordering are reported as preserved context without a data-loss warning. Fields whose replayed values are actually removed or replaced remain loud with discarded event authors/operations and recovery guidance. Re-apply any intended losing mutation as a normal `pm update` so it remains explicit and auditable.
+`history-repair` records the reconciliation patch and classifies its changed fields against the final item. Append-only collection unions and deterministic reordering are reported as preserved context without a data-loss warning. For native comments, docs and tests, duplicate copies of the same identified record and changes between the known `local_mutation`/`merge_union` display markers are also reported as preserved context. Author, creation time, origin, payload and unknown-field changes remain significant. This diagnosis does not authorize linked commands or relax exact receipt hashes. Fields whose replayed values are actually removed or replaced remain loud with discarded event authors/operations and recovery guidance. Re-apply any intended losing mutation as a normal `pm update` so it remains explicit and auditable.
 
 History events now declare an item-hash epoch. Epochs are immutable writer
 contracts, not aliases for the current item serializer: epoch 1 sorts linked

package/docs/RECURRENCE_RECOVERY_CONTRACTS.md

@@ -6,6 +6,8 @@ Tracked by [pm-83cz0o](../.agents/pm/features/pm-83cz0o.toon),
 [pm-h8tpeh](../.agents/pm/features/pm-h8tpeh.toon), and
 [pm-f05lsg](../.agents/pm/features/pm-f05lsg.toon).
 
+Planning recovery: [pm-reopen-planning-recovery](../.agents/pm/tasks/pm-reopen-planning-recovery.toon).
+
 ## Agent Quick Context
 
 - Reuse an active matching item; reopen a terminal matching item.
@@ -21,17 +23,28 @@ Tracked by [pm-83cz0o](../.agents/pm/features/pm-83cz0o.toon),
 
 ```bash
 pm item reopen pm-a1b2 "The production failure recurred after deployment"
-pm item reopen pm-a1b2 "The customer reproduced the issue" --status in_progress
+pm item reopen pm-a1b2 "The customer reproduced the issue" --status in_progress \
+  --expected-result "The recurrence is repaired and its regression passes"
 ```
 
 The command accepts only the workspace open or in-progress status. While
 holding the item lock it verifies that the current status is terminal, records
 one `reopen` history event with structured recurrence context, and delegates the
 state change to the normal update pipeline. Active metadata drops stale
-`closed_at`, `completed_at`, `close_reason`, `resolution`, `expected_result`,
-`actual_result`, and `fixed_version` values. Earlier history retains the exact
+`closed_at`, `completed_at`, `close_reason`, `resolution`, `actual_result`, and
+`fixed_version` values. It clears the prior `expected_result` and retains a new
+current expectation when explicitly supplied. Earlier history retains the exact
 closure values.
 
+Supply `--expected-result` (`--expected`) for the current active expectation.
+The SDK option and MCP parameter are `expectedResult`. This explicitly supplied
+planning value survives the reopen, while the previous terminal expectation
+remains in `recurrence.previous_terminal` and immutable history. Without the
+option, the compact receipt supplies `recovery.suggested_retry_args` for an
+update of the same tracker and item. Replace its outcome placeholder before
+executing it, then claim/start the item. Reopening does not infer a new
+expectation from the old closure or relax active planning assurance.
+
 Compact output keeps the recurrence receipt because the prior and next status,
 reason, and terminal evidence are the proof that this was a recurrence rather
 than a generic edit. An already-active item fails with
@@ -47,7 +60,7 @@ const pm = new PmClient({ pmRoot: "/workspace/.agents/pm" });
 const viaClient = await pm.reopen(
   "pm-a1b2",
   "The production failure recurred",
-  { status: "in_progress" },
+  { status: "in_progress", expectedResult: "The recurrence regression passes" },
 );
 
 const viaFunction = await reopen(

package/docs/RELATIONSHIP_GRAPH.md

@@ -10,6 +10,32 @@ The alternatives were rejected as follows: a closed enum cannot model applicatio
 
 ## Contract
 
+Dependency mutation admission is tracked by [pm-7dsolo](../.agents/pm/issues/pm-7dsolo.toon).
+`create --dep`, `update --dep`, `update --dep-remove`, bulk updates, and their
+SDK actions resolve kinds and aliases through the active workspace registry.
+For example, an extension can register `ships_before` with alias
+`precedes_ship`, then use `--dep id=<target>,kind=precedes_ship`; storage and
+history record `ships_before`. Ordering advice, self-edge refusals, and
+hierarchy validation use those same registered semantics. Disabling or
+uninstalling the registration refuses new dependency writes before item or history changes.
+The refusal lists active canonical kinds and explains how to enable the owning
+extension. `DependencyKind` is a string identifier: `DEPENDENCY_KIND_VALUES`
+describes built-in spellings rather than the complete workspace vocabulary.
+
+Non-hierarchy kinds with `outgoing: "one"` or `incoming: "one"` also reject
+new conflicting logical endpoints before persistence. Duplicate provenance
+rows do not consume another logical endpoint; unchanged historical debt and
+strict repairs remain allowed. One removal plus one addition is validated as
+the final dependency set. Limited-cardinality writers share the workspace
+integrity lock with hierarchy writers, so concurrent updates cannot both
+validate against the same empty snapshot.
+`assertNonHierarchyCardinalityMutationAllowed` and `RelationshipCardinalityItem`
+are public root/graph SDK exports for comparing minimal immutable item
+projections. The guard reports `dependency_cardinality_created` with a typed
+`relationship_cardinality` context. Native mutations compose it with the
+existing richer hierarchy validator; it does not infer semantics for an
+inactive or unknown kind.
+
 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,

package/docs/RELEASING.md

@@ -148,8 +148,13 @@ configuration belong in private operator documentation.
 - protected-branch pushes require `RELEASE_PAT`; Auto Release fails fast before the expensive release gates when `push=true`, `dry_run=false`, and that secret is not configured
 - release reliability gating requires `SENTRY_PERSONAL_ADMIN_TOKEN` for issue-threshold checks; Auto Release fails before creating the version commit/tag when the token is missing and `push=true`, while sourcemap upload remains optional through `SENTRY_AUTH_TOKEN`
 - after creating and pushing a new tag, auto-release waits for the tag-push `.github/workflows/release.yml` run to finish instead of dispatching a second publish workflow
-- scheduled failure issues include the preflight state (`push`, `dry_run`, `release_pat_configured`, and `sentry_personal_admin_token_configured`) plus a detected cause so agents can distinguish missing release secrets from Sentry gate failures without scanning the full workflow log first
-- when scheduled failures continue across multiple UTC days, auto-release supersedes a stale open blocker with a fresh current-day blocker so same-day retry detection follows the latest scheduled failure
+- native scheduled and declared morning-dispatcher failures open or update the
+  same daily blocker with trigger origin, preflight state (`push`, `dry_run`,
+  `release_pat_configured`, and `sentry_personal_admin_token_configured`) and
+  detected cause. Successful automatic recovery closes it only after exact
+  publication verification; operator dispatch does not manage this lifecycle.
+  This behavior is tracked by [pm-automatic-release-alerts](../.agents/pm/tasks/pm-automatic-release-alerts.toon).
+- when either automatic origin fails across multiple UTC days, auto-release supersedes a stale open blocker with a fresh current-day blocker so same-day retry detection follows the latest automatic failure
 - closing the exact bot-created `Auto Release blocked: scheduled run failed`
   issue as a maintainer or agent records a same-day retry marker, then either
   retries preparation when no tag exists or watches an active exact-tag Release
@@ -432,6 +437,12 @@ maintainer supplies
 pair that acknowledgement with migration guidance, compatible extension
 version bounds where applicable, and the next eligible date-based release.
 
+Build finalization removes redundant indentation from emitted `.d.ts` files
+([pm-chw71s](../.agents/pm/tasks/pm-chw71s.toon)). String and template type
+contents, comments, JSDoc, symbols and module boundaries retain their original
+tokens. Source declarations remain readable, and packed TypeScript consumers
+verify the emitted surface before publication. Artifact ceilings remain unchanged.
+
 5. Land the implementation through a reviewed pull request, then use hosted
    preparation for publication.
 
@@ -592,12 +603,18 @@ Use the npm registry package for maintainer global updates. Do not use `npm inst
   ordinal recovery version. Rerun `.github/workflows/release.yml` with
   `workflow_dispatch` and `tag=v<version>` (or close the current bot-created
   blocker once to trigger the guarded exact-run recovery). The workflow skips
-  duplicate npm publication for an anonymously visible version. Before
-  installing or running gates, dispatch performs an isolated anonymous
-  exact-version probe. An
-  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
+  npm publication for a version visible to its isolated anonymous probe, keeping
+  reviewed dispatch-time `main`. A definitive missing-version response can pin
+  source to the immutable tag only after admission reads complete workflow and
+  job inventories, validates totals and unique identities, and checks matching
+  attempts. Prior successful `Publish to npm` evidence refuses
+  publication while metadata is unavailable: acceptance can precede visibility.
+  Unavailable, malformed, incomplete or inconsistent evidence also refuses it.
+  Only the executing attempt is excluded; its earlier attempts remain checked.
+  This admission check also runs before first publication, using reviewed
+  controls retained outside recovery checkout. Push and dispatch publishers
+  share exact-tag concurrency. See [pm-publication-acceptance-fence](../.agents/pm/issues/pm-publication-acceptance-fence.toon).
+  A never-published tag then reapplies the version guard, installs the managed
   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. Ordinary tag-push releases