@unbrained/pm-cli 2026.9.7 → 2026.9.9

package/docs/PLANNING_MEASUREMENTS.md

@@ -0,0 +1,183 @@
+# Planning measurements
+
+Tracked by [pm-6olc95](../.agents/pm/issues/pm-6olc95.toon),
+[pm-398z0u](../.agents/pm/issues/pm-398z0u.toon), and
+[pm-d2wfig](../.agents/pm/features/pm-d2wfig.toon). Distribution work is tracked
+by [pm-fx0rcb](../.agents/pm/tasks/pm-fx0rcb.toon).
+
+These SDK primitives make three planning questions reproducible: which recorded
+populations have relationship context, how many items belong to each category,
+and whether estimated prerequisite work fits an authored deadline. The CLI and
+MCP use the same SDK implementations.
+
+## Relationship coverage across lifecycle states
+
+```bash
+pm graph audit --summary
+pm graph audit --save-baseline --summary
+```
+
+`--summary` retains recorded population totals, acyclicity, and lifecycle
+connectivity counts. Use `--full` for degree histograms, status/type distributions,
+edge-kind shares, and reachability detail. Baselines always persist the full census.
+The summary omission receipt declares `--full` as the recovery path.
+
+`profile.coverage_by_lifecycle` reports `all`, `active`, and `terminal` populations.
+`profile.coverage_by_status` reports the actual schema statuses, including
+`closed`, `canceled`, and custom terminal states. Every population reports:
+
+- `nodes`: recorded items, excluding missing and external placeholders.
+- `isolated` and `degree_leq_one`: items with zero or at most one incident edge.
+- `semantic_nodes` and `without_semantic_edges`: presence or absence of incident
+  provenance or verification edges, using the audit's semantic-kind definition.
+- `degree_histogram`: exact incident directed-edge counts and their populations.
+
+The existing active-only counters and type profiles retain their meanings.
+Population measurements include policy-exempt isolates; exemptions affect
+findings, not census denominators. Incident edges use the assembled graph's
+normalized, deduplicated directed basis. Reciprocal spellings can still be
+reported separately by duplicate-edge findings.
+
+`ordering_acyclic` states whether the complete ordering graph is acyclic.
+`active_ordering_acyclic` states whether any detected ordering cycle touches
+active or unknown-lifecycle work. A historical cycle remains a structural cycle
+even when the historical-debt policy gives its finding informational severity.
+Missing-reference findings retain their separate active and terminal populations.
+
+After a saved baseline, signed lifecycle and status deltas measure backfill
+progress. An older baseline that never measured these populations reports
+`lifecycle_comparable: false`; it does not imply that the historical population
+was empty. Save a new baseline to begin comparable measurements. Malformed new
+census fields invalidate a persisted baseline rather than producing misleading
+comparisons. Rebuildable query-cache entries from the older format are discarded.
+
+## Group membership and bounded aggregation
+
+```bash
+pm aggregate --group-by tags --limit 20
+pm aggregate --group-by tags,type --sum estimated_minutes --completion
+pm aggregate --group-by tags --set-mode tuple
+```
+
+Set-valued dimensions group by distinct normalized members by default. An item
+with `alpha` and `beta` contributes once to each group, even if a member appears
+more than once or differs only in case or surrounding whitespace. The same
+expansion rule applies to every array-valued grouping dimension; scalar dimensions
+compose with those memberships. Empty sets retain a `null` group displayed as
+`(untagged)` for tags.
+
+`--set-mode tuple` selects the previous behavior: the complete normalized set is
+one comma-joined key. This is useful when comparing exact category combinations.
+It is a distinct operation, and `filters.set_mode` records the interpretation.
+
+Counts, completion rates, sums, and averages are computed independently in each
+membership group. Consequently, summing group counts or numeric sums can count
+one item more than once. `totals.items_grouped` counts distinct input items;
+`totals.group_memberships` counts all group contributions.
+
+Aggregation reads the complete matching item population before paging groups.
+An unreadable input fails the strict read rather than becoming a partial count.
+The default page contains at most 50 groups. `count` is the total group count,
+`returned_count` is the page size, and `truncated` indicates further groups.
+Pass the returned `next_after` value as `--after` to continue. Keep the grouping
+and filters unchanged between pages. A cursor absent from the current result is
+rejected with restart guidance; pages are not an immutable snapshot of a tracker
+that is being concurrently edited.
+
+## Derived deadline constraints
+
+```bash
+pm graph slack --limit 10
+pm graph slack --summary
+```
+
+The existing unit-weighted `rows`, `makespan`, and hop-based `slack` remain intact.
+The additional `deadline_schedule` uses `estimated_minutes` and authored
+`deadline` finish constraints. Its `basis` is `derived_elapsed_minutes`, and
+`as_of` records the clock used. This computation writes no item fields.
+
+A forward pass computes earliest estimated starts from the invocation clock. A
+backward pass transfers each dated finish constraint through the ordering graph,
+retaining the tightest successor constraint. A derived row identifies the
+controlling `deadline_id`, its `latest_start`, and `slack_minutes` relative to the
+earliest possible start. Negative slack indicates a time shortfall; this can
+coexist with positive hop-based slack.
+
+`overcommitted` findings name the authored deadline, the shortfall in minutes,
+and a bounded controlling prerequisite path. `path_truncated` identifies a path
+whose leading steps were omitted; the retained suffix still ends at the dated
+item. Moving the authored deadline later recomputes the finding.
+
+Missing, negative, or nonfinite estimates are explicit `unknown_estimate`
+residuals. Unknown predecessor duration produces `unknown_predecessor_estimate`
+and `null` temporal slack, never zero-cost feasibility. Cycles and work gated by
+cycles report `cycle_or_gated_by_cycle`. Invalid dates and dates outside the
+representable range are also residuals. `complete: false` means feasibility
+cannot be established for the entire input graph; counts remain separate from
+bounded samples.
+
+Estimates represent elapsed duration with independent work allowed in parallel.
+There is no staffing, resource-contention, working-hours, holiday, or progress
+model. The workspace adapter schedules active work and reports `population: active`;
+completed work no longer consumes future duration or contributes overdue deadlines.
+The pure SDK function schedules the supplied graph, so callers can select other
+populations explicitly. ISO
+date-only deadlines denote UTC midnight. Undated components have no latest-start
+constraint. Topology cache hits do not reuse time-sensitive deadline results;
+they are derived from the current metadata on every invocation.
+
+The pure derivation defaults to a work bound of 100,000 input items plus graph
+nodes and edges, checked before graph passes. Larger inputs return
+`work_limit_exceeded: true` and `complete: false` with no manufactured schedule.
+Rows, residual samples, findings, and path identifiers obey the supplied `limit`.
+All retained paths also share a total identifier budget of `maxWork`, so large
+finding limits cannot create quadratic path evidence. Exhaustion preserves exact
+counts and sets both `path_truncated` and the result's `truncated` flag.
+The workspace CLI still pays its existing metadata-read and graph-assembly cost;
+the derivation bound is not a claim that loading a million-item workspace is free.
+Summary mode suppresses the evidence arrays and retains their counts.
+
+## Public SDK
+
+```ts
+import {
+  assembleWorkspaceRelationshipGraph,
+  auditWorkspaceRelationshipGraph,
+  deriveRelationshipDeadlines,
+} from "@unbrained/pm-cli/sdk/graph";
+import { runAggregate } from "@unbrained/pm-cli/sdk/query";
+
+const items = [
+  { id: "work", title: "Prepare", status: "open", estimated_minutes: 60 },
+  {
+    id: "milestone", title: "Deliver", status: "open", blocked_by: "work",
+    estimated_minutes: 30, deadline: "2026-10-01T12:00:00Z",
+  },
+];
+const assembly = assembleWorkspaceRelationshipGraph(items);
+const coverage = auditWorkspaceRelationshipGraph(assembly).profile;
+const schedule = deriveRelationshipDeadlines(assembly.graph, items, {
+  now: "2026-10-01T10:00:00Z",
+  maxWork: 100_000,
+  limit: 20,
+});
+const categories = await runAggregate(
+  { groupBy: "tags", setMode: "element", limit: 20 },
+  { path: "/path/to/project/.agents/pm" },
+);
+```
+
+The derivation accepts an `AbortSignal`. Relationship orientation comes from the
+supplied graph registry, so custom ordering kinds and inverse spellings use the
+same execution semantics. MCP `pm_run` with `action: "aggregate"` accepts
+`options.setMode`, `options.limit`, and `options.after`. MCP `pm_graph` with
+`subcommand: "slack"` returns the same deadline evidence.
+
+## Distribution
+
+Build finalization compacts whitespace in retained runtime JavaScript modules.
+It preserves module paths and identifiers, keeps public declaration documentation,
+and composes source maps back to the original TypeScript for release symbolication.
+Existing bundled outputs remain unchanged by this pass. Source maps remain local
+release artifacts and are excluded from the npm packlist. Artifact size and file
+count ceilings are checked against the actual npm pack projection.

package/docs/README.md

@@ -52,6 +52,7 @@ pm guide release --json
 - [MCP Remote Transport, Authorization, and Migration](MCP_REMOTE_TRANSPORT_SECURITY.md) - Streamable HTTP operation, subscriptions, OAuth and trace boundaries, threat model, and deprecated-feature ratchet.
 - [SDK Artifact Output Contracts](SDK_ARTIFACT_OUTPUT.md) - clean stdout/file exporter channels, bounded receipts, binary-safe delivery, and shared NDJSON terminal framing.
 - [Context Relevance and Packing](CONTEXT_RELEVANCE.md) - shared CLI/SDK signals, derived-store provenance, ranking explanations, and token budgets.
+- [Context Algorithm Portfolio](CONTEXT_ALGORITHM_PORTFOLIO.md) - stable proposal slugs, historical aliases, individual owners, cognitive compositions, and experiment gates.
 - [Output Projection and Omission Contracts](OUTPUT_PROJECTION_CONTRACTS.md) - explicit withheld-field receipts, mode-paired row keys, and completion resolver outcomes.
 - [Output Token Accounting](OUTPUT_TOKEN_ACCOUNTING.md) - opt-in CLI/MCP byte attribution, bounded receipt overhead, and release-level tokens-per-task baselines.
 - [SDK Context Platform](SDK_CONTEXT.md) - task-oriented entry point for authoritative reads, ranking, package workflows, diagnostics, recovery, and verification.
@@ -60,12 +61,15 @@ pm guide release --json
 - [Generated Refusal Closure Census](generated/REFUSAL_CLOSURE_CENSUS.md) - complete error-catalog join to executable refusal evidence and explicit uncovered obligations.
 - [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.
+- [History Maintenance and Recovery](HISTORY_MAINTENANCE.md) - native history commands, permanent aliases, shared SDK transforms, and transactional recovery.
+- [Declarative Workflow Policies](WORKFLOW_POLICIES.md) - portable lifecycle requirements, independent approvals, and completeness reports.
 - [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.
 - [SDK Agent Environments](AGENT_ENVIRONMENTS.md) - calibrated observations, total verdicts, isolated episodes, and an executable public-SDK environment.
 - [Improvement Ledger and History Analytics](IMPROVEMENT_ANALYTICS.md) - audited quantitative observations, live provenance coverage, and bounded observational fleet outcomes.
 - [Project Assurance Primitives](ASSURANCE.md) - SDK-owned measurements, assertions, lifecycle gates, cost receipts, and durable verdict history shared by CLI and MCP.
+- [Planning Measurements](PLANNING_MEASUREMENTS.md) - lifecycle coverage, set-membership aggregation, and derived deadline constraints.
 - [Defect Recurrence and Boundary Evidence](DEFECT_RECURRENCE.md) - captured external samples, structured defect-escape evidence, incremental change-risk indexing, and executable recovery-producer census.
 - [Recurrence and Executable Recovery Contracts](RECURRENCE_RECOVERY_CONTRACTS.md) - terminal-item recurrence, duplicate-intake routing, capability-aware reindex recovery, and target-aware generated test guidance.
 - [Trustworthy Context and Evidence Contracts](TRUSTWORTHY_CONTEXT_EVIDENCE.md) - full-record assurance, graph composition, boolean health rows, lossless linked-test removal, and role-labelled recovery.

package/docs/READ_OUTPUT_CONTRACTS.md

@@ -167,6 +167,11 @@ Cursor recovery carries the opaque value once in `recovery.cursor` and declares
 the accepting `cli`, `sdk`, and `mcp` binding beside it. This avoids
 serializing the same cursor once per transport while retaining an executable,
 machine-readable binding for each surface.
+When `restore_with` is `"recovery"`, consumers must resolve the adjacent
+`recovery` object: pass its `cursor` value through `cli` (`--output-cursor`)
+or the `sdk`/`mcp` field (`outputCursor`) while repeating the original query.
+The string is a reference, not a shell command. Other `restore_with` values
+provide retry guidance when no declared row collection can continue.
 
 Budget-compacted declared row paths are independently resumable. The
 disclosure's `continuations` entries name the row path, retained/remaining/total

package/docs/SCRIPTING.md

@@ -78,6 +78,27 @@ declaring every command's default token ceiling. Use `pm contracts --full
 with TOON- and JSON-specific token ceilings for every active core or package
 command.
 
+Claim receipts ([pm-eqdo85](../.agents/pm/issues/pm-eqdo85.toon)) also keep
+`claimed_by`, `previous_assignee`, and `forced`. Conditional contention adds
+`skipped`; ranked claims add `available` and `attempts`. The change count
+reflects ownership fields actually changed: an unchanged repeat or skipped
+claim reports zero and does not write a duplicate mutation event.
+
+```bash
+pm claim pm-a1b2 --json
+pm claim pm-a1b2 --if-available --json
+pm claim --next --json
+pm claim pm-a1b2 --full-changed-fields --json
+```
+
+Use `--full-changed-fields` to restore the complete item, `changed_fields`,
+and ranked-selection recommendation. `--id-only` returns only identity and
+status; `--quiet` suppresses stdout. Direct typed SDK `claim` and
+`claimNext` calls return the full result. Generic SDK/MCP actions use the
+compact transport contract and accept `fullChangedFields` or `idOnly`.
+Custom SDK claim runners may omit the optional `changed_fields` member;
+receipts without that evidence retain their existing envelope.
+
 JSON object field order is not an API. Consume fields by name. Read envelopes keep the stable pagination vocabulary `items`, `count`, `total`, `has_more`, and, when another page exists, `next_cursor`. The `filters` object echoes the effective query scope. Plain `pm list` and `pm search` are all-status reads and disclose `filters.status: "all"`; lifecycle-specific commands such as `pm list-open` remain explicit shortcuts.
 
 Projection flags intentionally change row shape. Use `--fields` when a script requires an exact subset, `--brief` or `--compact` only when the documented sparse shape is sufficient, and `--full` when linked metadata is required. Check `row_contract` on generic read surfaces that expose one; do not infer omitted fields as empty values.

package/docs/TESTING.md

@@ -50,6 +50,15 @@ children, then cleans the roots up. Instrumentation tests can still exercise
 Sentry initialization through their mocked module boundary; ordinary negative
 fixtures must never create production incidents from a developer host.
 
+Temporary directories must live outside the checkout and outside any ancestor
+workspace with initialized tracker data. The runner rejects a checkout-local
+temporary root, including a symlink alias, before starting build or test
+processes ([pm-bukwmy](../.agents/pm/issues/pm-bukwmy.toon)). If the default
+temporary filesystem is full, set `TMPDIR` (or `TEMP`/`TMP` on Windows) to an
+existing isolated scratch directory; an ignored directory inside the repository
+is not isolated. Filesystem fixtures must honor `node:os`'s `tmpdir()` and remove
+only the temporary directories they created.
+
 Public SDK changes additionally run semantic surface and import-cost contracts:
 
 ```bash
@@ -79,6 +88,16 @@ so PR-local CodeFactor maintainability annotations fail locally before commit or
 push. Existing legacy high-complexity test fixtures are tracked separately and
 must not be used as precedent for new changed production/script code.
 
+`lint:duplicates` runs three zero-clone profiles: the broad repository profile,
+the production cross-format profile, and a supplemental long-table profile at
+28 lines / 80 tokens. The last profile detects the historical GH-508 normalizer
+tables below the other profiles' token floors; it does not replace their shorter
+line thresholds. Its real detector regression rejects the historical table rows
+and accepts a shared declaration. The earlier 12-line / 60-token exploratory
+census informed calibration, but is not the enforced profile. These bounded
+profiles do not claim complete equivalence with hosted analyzers.
+See [pm-xspd](../.agents/pm/chores/pm-xspd.toon) for calibration evidence.
+
 The local parity rules catch analyzer classes before push. The mandatory hosted
 proof runs after the final commit is pushed and both apps have finished:
 
@@ -108,6 +127,20 @@ Use focused runs while iterating, then run coverage before closure when risk or
 
 ## CI Retry and Timeout Diagnostics
 
+Platform regressions from [pm-hrhfgi](../.agents/pm/issues/pm-hrhfgi.toon) and
+[pm-zk67yf](../.agents/pm/issues/pm-zk67yf.toon) have portable negative controls.
+Complete source scans process at most 32 item files per batch; the descriptor
+pressure fixture fails unbounded reads while requiring genuine permission
+failures to remain visible. The 10,000-item aggregation fixture separately
+verifies completeness before pagination. Git fixtures that assert exact bytes
+declare repository-local `core.autocrlf=false` and `core.eol=lf` so host defaults
+cannot change the restoration target. Send generated shell scripts through
+stdin (`bash -s`) so their size cannot exceed Windows command-line limits.
+Runtime compaction is tested through a
+real directory alias as well as its physical path, including original source
+mapping and repeated-compaction byte stability. These tests run in the full
+suite on the Nightly Validation platform matrix.
+
 CI retains the 30-second per-test timeout and retries one failed attempt. A
 test that passes only on retry is reported as flaky rather than silently folded
 into the pass count; a persistent assertion still fails after the bounded

package/docs/WORKFLOW_POLICIES.md

@@ -0,0 +1,129 @@
+# Declarative workflow policies
+
+Tracker: [pm-mj42og](../.agents/pm/features/pm-mj42og.toon) and [pm-htbetn](../.agents/pm/features/pm-htbetn.toon).
+
+Projects can describe their lifecycle requirements as versioned data. The SDK
+uses the same evaluator for item mutations, policy previews, and completeness
+reports. Existing projects have no implicit policies. A declaration can advise,
+warn, or refuse; refusal also requires an explicit workspace opt-in.
+
+## Configure a requirement
+
+```bash
+pm schema policy-put close-evidence --definition '{"id":"close-evidence","effect":"refuse","subject":{"statuses":["closed"]},"rule":{"kind":"require_fields","fields":["resolution","actual_result"]}}'
+pm schema policies
+pm schema policy-check pm-example --definition '{"status":"closed"}'
+pm schema policy-mode refuse
+```
+
+Use canonical status ids and metadata field names. `body` selects the Markdown
+body. Custom fields can use dotted paths with at most eight segments. Empty
+strings, arrays, objects, null, and absent values do not satisfy required fields;
+zero and false are meaningful values.
+
+`policy-put` replaces a declaration with the same id. `policy-remove <id>` removes
+one declaration. `policy-mode advise` disables refusal while retaining diagnostics.
+Registry writes are locked and recorded in workspace history. `--dry-run` previews
+registry changes without writing. Malformed registries fail closed.
+
+## Selectors and rules
+
+All selectors in `subject` must match; values within one selector are alternatives.
+Supported selectors are `types` (case insensitive), `tags`, `statuses`, `operations`,
+`parents`, and `dependency: { "kind": "implements", "id": "pm-example" }` (id optional).
+Parent and dependency selectors inspect direct relationships. Status selectors
+match the destination; other selectors inspect both snapshots so a mutation cannot
+escape a protected scope by removing its tag or changing its type.
+
+| Rule kind | Required properties | Behavior |
+| --- | --- | --- |
+| `require_fields` | `fields` | Checks evidence on lifecycle, scope, or required-field changes |
+| `transition` | `allowed` | Allows listed `[from, to]` status pairs; `$create` and `$delete` represent absent records |
+| `authors` | `authors` | Requires a listed mutation actor |
+| `field_writers` | `fields`, `authors` | Requires a listed actor when protected fields change |
+| `approval` | `fields`, `authors` | Requires independent approval when an existing item changes status or is deleted |
+
+Operation selectors use exact history operation names. Unknown declaration keys
+are errors. Policies contain no executable expressions or regular expressions.
+At most 256 declarations and 64 terms per selector/rule are accepted. Registry
+reads are bounded to 1 MiB, and approval-history reads to 4 MiB.
+
+Actor names are provenance supplied by the caller or local configuration. They
+are not authenticated identities, and these rules are not an access-control
+boundary against a caller who can edit the tracker or choose an author name.
+Authenticated, signed identity ([pm-u14c](../.agents/pm/stories/pm-u14c.toon))
+is a prerequisite for stronger authorization guarantees.
+
+## Approvals
+
+Prepare the declared fields, then have a different workflow actor record approval:
+
+```bash
+pm schema policy-put review --definition '{"id":"review","effect":"refuse","subject":{"statuses":["closed"]},"rule":{"kind":"approval","fields":["body","resolution"],"authors":["reviewer"]}}'
+pm schema policy-approve pm-example --policy review --author reviewer --message 'Reviewed acceptance evidence'
+```
+
+Approval events bind the item id, selected field values, and complete policy
+revision. Changing reviewed content or the declaration invalidates the approval.
+Unrelated metadata changes do not. The actor performing the transition must differ
+from the approval actor. Only sealed approval events from a verified item history
+chain count. `policy-check` previews transitions; `policy-approve` always records
+an event and rejects `--dry-run`.
+
+Approval rules apply to existing items. Creation and initial imports have no
+reviewable history and skip approval requirements; use `transition` rules with
+`["$create", "open"]` to constrain their initial status. Deletion requires approval
+of the current record, using the same content and independent-actor checks.
+
+Refused mutations preserve item state and item history, and append a workspace
+refusal event. Accepted mutations attach bounded policy decisions to their normal
+history event. Diagnostics contain policy ids and missing field paths, without
+copying reviewed content into errors.
+If the mandatory refusal audit cannot be appended, the mutation instead raises
+`workflow_policy_audit_failed` and preserves the original failure in the SDK
+error's `cause`. Item data remains unchanged; resolve the workspace history lock
+or storage failure before retrying. Package imports do not downgrade this error
+to an item-lock warning.
+
+## Completeness reports and SDK
+
+```bash
+pm schema policy-presets
+pm validate --check-completeness --strict-exit
+```
+
+Presets return optional advisory declarations for familiar item types. They do
+not install policies. Author the declarations appropriate to the project's own
+types and lifecycle using `policy-put`. Completeness reports group counts by type,
+return bounded violation examples, and use only `require_fields` declarations
+without `subject.operations`. The report identifies this scope as
+`operation_independent_require_fields`. All item selectors, including status,
+still apply. `policy-check` without a proposed definition uses the same state-only
+scope. Operation-scoped rules remain enforced during matching mutations; a clean
+state report does not imply permission to perform every future operation.
+To check a lifecycle field invariant in both state reports and mutations, select
+its `statuses` without restricting `operations`.
+Default validation includes this check; projects without declarations remain
+unaffected.
+An unreadable or malformed `schema/policies.json` produces an error-level
+`completeness` result with a repair hint. Other requested validation checks still
+run, and `--strict-exit` fails until the policy registry is repaired.
+
+The published `@unbrained/pm-cli/sdk/governance` entrypoint exports
+`runWorkflowPolicyAction`, `evaluateWorkflowPolicies`, policy types, parsers,
+`WORKFLOW_POLICY_SCHEMA`, and `WORKFLOW_POLICY_DOCUMENT_SCHEMA`. `PmClient` exposes
+`workflowPolicy(action, name, options)`. CLI `schema` and MCP `pm_schema` use the
+same action vocabulary and SDK implementation; MCP options accept camelCase
+keys and structured JSON definitions.
+
+For repeated pure evaluation, `createWorkflowPolicyEvaluator(document)` returns
+an evaluator that owns a private normalized policy snapshot and hashes each
+declaration once. Later edits to the supplied document do not change that
+snapshot; create another evaluator to adopt them. Completeness validation uses
+one such snapshot for the whole supplied corpus.
+
+The schema contract version is 4.16. Existing schema operations remain available;
+`SchemaResult` now also includes `WorkflowPolicyActionResult`. Consumers that
+exhaustively narrow schema results should handle the `policy_result: true`
+discriminant. Validation options include `checkCompleteness`, and validation
+results can contain a `completeness` check.

package/docs/generated/FLAG_LEXICON_BUDGETS.md

@@ -6,10 +6,10 @@ This file is generated by `listPmFlagLexicon()`. Compatibility aliases do not co
 | --- | --- | ---: | ---: |
 | `init` | workspace | 30 | 30 |
 | `config` | workspace | 36 | 36 |
-| `extension` | extensions | 53 | 53 |
-| `package` | extensions | 54 | 54 |
-| `packages` | extensions | 54 | 54 |
-| `install` | extensions | 26 | 26 |
+| `extension` | extensions | 54 | 54 |
+| `package` | extensions | 55 | 55 |
+| `packages` | extensions | 55 | 55 |
+| `install` | extensions | 27 | 27 |
 | `upgrade` | extensions | 29 | 29 |
 | `create` | intake | 100 | 100 |
 | `copy` | intake | 24 | 24 |
@@ -22,7 +22,7 @@ This file is generated by `listPmFlagLexicon()`. Compatibility aliases do not co
 | `list-blocked` | context | 84 | 84 |
 | `list-closed` | context | 84 | 84 |
 | `list-canceled` | context | 84 | 84 |
-| `aggregate` | context | 37 | 37 |
+| `aggregate` | context | 40 | 40 |
 | `context` | context | 45 | 45 |
 | `ctx` | context | 45 | 45 |
 | `get` | context | 30 | 30 |
@@ -38,7 +38,7 @@ This file is generated by `listPmFlagLexicon()`. Compatibility aliases do not co
 | `history-compact` | evidence | 30 | 30 |
 | `history-author-acknowledge` | evidence | 28 | 28 |
 | `merge` | workspace | 27 | 27 |
-| `schema` | workspace | 40 | 40 |
+| `schema` | workspace | 43 | 43 |
 | `profile` | workspace | 22 | 22 |
 | `activity` | context | 35 | 35 |
 | `restore` | intake | 23 | 23 |
@@ -60,7 +60,7 @@ This file is generated by `listPmFlagLexicon()`. Compatibility aliases do not co
 | `telemetry` | workspace | 21 | 21 |
 | `stats` | context | 29 | 29 |
 | `health` | workspace | 36 | 36 |
-| `validate` | quality | 45 | 45 |
+| `validate` | quality | 46 | 46 |
 | `assurance` | quality | 30 | 30 |
 | `gc` | workspace | 22 | 22 |
 | `workspace` | workspace | 23 | 23 |

package/docs/generated/REFUSAL_CLOSURE_CENSUS.md

@@ -4,14 +4,14 @@ Tracker: `pm-f05lsg`.
 
 Every catalog code is listed. An `uncovered` row is an explicit closure obligation, never an omission or implied approval.
 
-- Catalog error codes: 365
+- Catalog error codes: 371
 - Executable error codes: 19
 - Executable-code ratchet floor: 18
 - Required executable canonical codes: `bulk_ids_input_empty`, `bulk_ids_input_missing_path`, `bulk_ids_input_unreadable`, `invalid_argument_value`, `manifest_unknown_key`, `missing_lifecycle_target`, `missing_required_argument`, `no_version_bounds_declared`, `projection_options_mutually_exclusive`, `tracker_not_initialized`, `tracker_root_missing`, `tracker_root_not_directory`, `tracker_root_unreadable`, `unknown_context_intent`, `unknown_field_projection`, `unknown_option`, `unknown_subcommand`
-- Uncovered error codes: 346
-- Coverage fraction: 0.052055
+- Uncovered error codes: 352
+- Coverage fraction: 0.051213
 - Closed-domain probes: 19
-- Grammar probes: 94
+- Grammar probes: 97
 
 | Error code | Canonical code | Disposition | Evidence kinds | Probe count |
 | --- | --- | --- | --- | --- |
@@ -211,7 +211,7 @@ Every catalog code is listed. An `uncovered` row is an explicit closure obligati
 | `missing_parameter_alias` | `missing_parameter_alias` | uncovered | none | 0 |
 | `missing_positive_execution_receipt` | `missing_positive_execution_receipt` | uncovered | none | 0 |
 | `missing_probe` | `missing_probe` | uncovered | none | 0 |
-| `missing_required_argument` | `missing_required_argument` | executable | grammar | 57 |
+| `missing_required_argument` | `missing_required_argument` | executable | grammar | 60 |
 | `missing_required_option` | `missing_required_option` | uncovered | none | 0 |
 | `missing_suggested_retry` | `missing_suggested_retry` | uncovered | none | 0 |
 | `missing_suggested_retry_args` | `missing_suggested_retry_args` | uncovered | none | 0 |
@@ -365,6 +365,12 @@ Every catalog code is listed. An `uncovered` row is an explicit closure obligati
 | `vectorization_stale_items_remaining` | `vectorization_stale_items_remaining` | uncovered | none | 0 |
 | `visible_surface_ceiling_exceeded` | `visible_surface_ceiling_exceeded` | uncovered | none | 0 |
 | `workflow_duplicate_type` | `workflow_duplicate_type` | uncovered | none | 0 |
+| `workflow_policy_approval_history_invalid` | `workflow_policy_approval_history_invalid` | uncovered | none | 0 |
+| `workflow_policy_audit_failed` | `workflow_policy_audit_failed` | uncovered | none | 0 |
+| `workflow_policy_input_unreadable` | `workflow_policy_input_unreadable` | uncovered | none | 0 |
+| `workflow_policy_invalid` | `workflow_policy_invalid` | uncovered | none | 0 |
+| `workflow_policy_refused` | `workflow_policy_refused` | uncovered | none | 0 |
+| `workflow_policy_registry_invalid` | `workflow_policy_registry_invalid` | uncovered | none | 0 |
 | `workflow_status_unknown` | `workflow_status_unknown` | uncovered | none | 0 |
 | `workflow_transition_malformed` | `workflow_transition_malformed` | uncovered | none | 0 |
 | `workflow_type_empty` | `workflow_type_empty` | uncovered | none | 0 |

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-cli",
-  "version": "2026.9.7",
+  "version": "2026.9.9",
   "description": "Git-native project management CLI for humans and agents.",
   "type": "module",
   "packageManager": "pnpm@11.10.0",
@@ -119,7 +119,7 @@
     "lint:eslint": "eslint . --max-warnings=0",
     "lint:eslint:prune": "eslint . --prune-suppressions",
     "lint:complexity:baseline": "eslint . --suppress-rule complexity --suppress-rule sonarjs/cognitive-complexity",
-    "lint:duplicates": "jscpd --config .jscpd.json && jscpd --config .jscpd.source.json",
+    "lint:duplicates": "jscpd --config .jscpd.json && jscpd --config .jscpd.source.json && jscpd --config .jscpd.tables.json",
     "lint:codefactor": "pnpm quality:static",
     "quality:static": "pnpm lint:eslint && pnpm lint:duplicates && pnpm build && node scripts/contracts-snapshot.mjs --check && node scripts/generate-agent-capability-surfaces.mjs --check && node scripts/generate-error-code-catalog.mjs --check && node scripts/release/repository-assurance.mjs repository-static-quality --trigger ci --json && node scripts/release/audit-package-boundary.mjs && node scripts/release/package-sdk-contract-parity.mjs && node scripts/release/surface-replication-gate.mjs && node scripts/release/command-grammar-gate.mjs && node scripts/release/flag-invocation-parity.mjs && node scripts/release/flag-lexicon-gate.mjs && node scripts/release/refusal-closure-gate.mjs && node scripts/release/agent-task-token-gate.mjs && pnpm quality:mcp-deprecations && node dist/cli.js assurance run tracker-context-quality --trigger ci --dry-run --json --output-budget unbounded && node scripts/release/gate-registry.mjs && node scripts/sdk-surface-snapshot.mjs --check && node scripts/bench/sdk-entrypoint-costs.mjs --check && node scripts/bench/cli-transport-floor.mjs --check && node dist/cli.js assurance run graph-composition --trigger ci --dry-run --json --output-budget unbounded && node dist/cli.js assurance run record-integrity --trigger ci --dry-run --json --output-budget unbounded",
     "quality:command-grammar": "pnpm build && node scripts/release/command-grammar-gate.mjs && node scripts/release/flag-invocation-parity.mjs && node scripts/release/flag-lexicon-gate.mjs",
@@ -220,7 +220,7 @@
     "@eslint/js": "^10.0.1",
     "@modelcontextprotocol/ext-apps": "1.7.5",
     "@sentry/cli": "^3.7.0",
-    "@types/node": "^26.4.1",
+    "@types/node": "^26.5.0",
     "@types/npm-package-arg": "^6.1.4",
     "@vitest/coverage-v8": "^4.1.11",
     "esbuild": "0.28.2",
@@ -231,11 +231,11 @@
     "github-slugger": "2.0.0",
     "greptile": "^3.5.2",
     "jscpd": "^5.1.2",
-    "marked": "18.0.11",
+    "marked": "18.0.12",
     "parse5": "8.0.1",
     "tsx": "^4.23.13",
     "typescript": "^6.0.3",
-    "typescript-eslint": "^8.69.0",
+    "typescript-eslint": "^8.70.0",
     "vitest": "^4.1.11"
   }
 }

package/packages/pm-beads/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unbrained/pm-beads",
-  "version": "2026.9.7",
+  "version": "2026.9.9",
   "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.9.7",
+  "version": "2026.9.9",
   "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.9.7",
+  "version": "2026.9.9",
   "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.9.7",
+  "version": "2026.9.9",
   "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.9.7",
+  "version": "2026.9.9",
   "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.9.7",
+  "version": "2026.9.9",
   "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.9.7",
+  "version": "2026.9.9",
   "private": true,
   "type": "module",
   "description": "First-party pm archetype package: a complete Kanban continuous-flow profile built on public SDK primitives.",