@unbrained/pm-cli 2026.10.24 → 2026.10.26

package/docs/MERGE_SAFETY.md

@@ -132,6 +132,10 @@ pm merge install --dry-run --json
 
 ## Artifact semantics
 
+History scalar rebasing and ignored settlement artifacts are tracked by
+[pm-gh1553](../.agents/pm/issues/pm-gh1553.toon) and
+[pm-gh1556](../.agents/pm/issues/pm-gh1556.toon).
+
 | Artifact                                                         | Driver                              | Merge behavior                                                                                                                                                                                                                                                                      |
 | ---------------------------------------------------------------- | ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | Item `.toon` / `.md`                                             | `pm-item-toon` / `pm-item-markdown` | Three-way field merge; append-like collections use set union, `updated_at` uses the latest timestamp, scalar conflicts select the value from the later document update with stable value order as an equal-timestamp tie-break, and canonical serialization recomputes TOON counts. |
@@ -139,6 +143,18 @@ pm merge install --dry-run --json
 | tracker `**/*.jsonl` except the later `history/*.jsonl` override | `pm-relationship`                   | Covers default and package-owned custom relationship event paths, unions divergent suffixes by `eventId` (timestamp-ordered, ours-first on ties), and renumbers `sequence` consecutively so the strict-sequence store loader accepts the merged stream.                             |
 | root `settings.json` and nested `**/*.json`                      | `pm-json`                           | Recursively merges objects per key. Arrays compose when both branches preserve the base and add distinct entries, so independent extension installs and evaluation additions merge without weakening edit/removal conflict detection.                                               |
 
+History union validates each event in its original branch before rebasing its
+effects. A whole metadata-field replacement still assigns its exact value when
+another branch removed that field; a repeated whole-field removal keeps its
+event even when absence already satisfies its effect. This covers a branch
+claim following another branch's release without losing closure or comments.
+Nested paths and conditional patches remain strict. An unsafe scalar patch
+refuses with `history_union_rebase_conflict` and SDK `history_merge` coordinates
+(branch, one-based event line, operation, scalar-patch index and JSON pointer).
+CLI diagnostics name those coordinates in the error message. Preserve all three
+inputs and both item snapshots for deliberate recovery;
+verify the resolved history and preview reconciliation before committing.
+
 The `tests` collection has an additional execution-safety rule. Its semantic
 identity excludes provenance so the same command/context does not duplicate
 when branches record different authorship metadata. A test definition newly
@@ -485,6 +501,18 @@ The result's `staged_paths` lists the repository-relative artifacts added.
 Tracker aliases resolve before preview, so proof verification, repair and staging
 use the same physical tracker root.
 
+Both preview and apply check Git's effective ignore rules before any staging or
+audit write. An ignored artifact refuses with `merge_settlement_review_required`,
+`reason: ignored_merge_artifacts`, its relative path, and the owning
+`file:line: pattern`. Remove or narrow that rule, then retry the preview. Older
+workspaces may still ignore `merge-receipts/` from the former clone-local receipt
+policy; current receipt sidecars must travel with the merge commit. `pm health`
+checks a representative receipt path even before a merge exists and reports
+`merge_artifacts_ignored` with the rule coordinates. A file-specific rule is
+also checked against each actual settlement artifact. Git negations and tracked
+files retain their native meaning; pm neither force-adds artifacts nor rewrites
+user ignore rules.
+
 Repositories can explicitly opt into a merge-aware `pre-commit` hook:
 
 ```bash

package/docs/MUTATION_INTEGRITY.md

@@ -2,6 +2,8 @@
 
 Tracker references: [pm-h90s](../.agents/pm/issues/pm-h90s.toon), [pm-pim7](../.agents/pm/features/pm-pim7.toon), [pm-w8q4](../.agents/pm/features/pm-w8q4.toon), [pm-9yfo](../.agents/pm/tasks/pm-9yfo.toon), [pm-wwooxx](../.agents/pm/issues/pm-wwooxx.toon), [pm-3kk6](../.agents/pm/issues/pm-3kk6.toon)
 
+Concrete home-path normalization is tracked by [pm-gh1583](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-gh1583.toon). Tracker records are repository-only and excluded from npm.
+
 `pm` treats mutation provenance and content safety as shared SDK policy. CLI,
 MCP, and package hosts can therefore enforce the same rules without duplicating
 argument parsing or exposing detected values.
@@ -70,6 +72,10 @@ whether a blocking policy was explicitly overridden. `scanMutationSecrets` is
 available separately for package-specific preflight UIs. Cyclic inputs are
 safe; scanner failures fail open with `secret_guard_scan_failed_open`.
 
+Direct SDK persistence does not automatically apply this host preflight.
+Integrations that require the policy must evaluate it before dispatching their
+SDK mutations. CLI and MCP adapters already do this.
+
 The SDK guard and repository scanner consume one inventory in
 `src/core/shared/secret-rules.ts`. It covers GitHub, npm, Slack, AWS access
 keys (including temporary keys), Google, Anthropic, OpenAI, GitLab, Sentry,
@@ -91,6 +97,33 @@ remains advisory; a workspace selecting `block` must replace those literals
 with references or explicitly review a force override. CLI routing paths and
 payload content are distinct: pass only content to package-owned preflight.
 
+Home-path detection recognizes concrete POSIX and macOS account roots, root
+subdirectories, Windows user profiles, UNC profile shares, DOS device namespace
+profiles, and explicit file URLs. Device prefixes follow the
+[documented Windows path families](https://learn.microsoft.com/dotnet/standard/io/file-path-formats).
+It accepts surrounding markup and punctuation. Detection-only views
+decode percent-byte runs, serialized slash/character escapes, and documented
+Unicode disguises. Unicode handling applies NFKC, removes zero-width/bidi
+controls, and folds division/fraction slashes and Cyrillic look-alikes for the
+path vocabulary's letters o and s. These are finite heuristics, not filesystem
+canonicalization or a complete confidentiality guarantee.
+
+Inspection is limited to four normalization passes per original line. Findings
+can include typed `normalizations` identifiers; original and decoded values are
+never returned, and payloads are never rewritten. If encoding remains after the
+limit, `normalization_incomplete: true` conservatively requires review using
+the same advisory/blocking policy. It applies to the entire string leaf, even
+when an earlier line already contained a concrete path. A blocking workspace
+may explicitly force a reviewed value. Repository diagnostics retain original source lines, including
+when an encoded value contains a newline.
+
+Portable references remain literal: current-user and named tilde references,
+home environment variables, and Windows profile variables are not expanded
+using the scanner's host. They do not establish a concrete absolute coordinate.
+Ordinary web URLs and relative paths are also preserved. Package-specific
+policies may classify additional context, but must not treat an empty finding
+list as proof that arbitrary content is safe to publish.
+
 Nested settings reads use own properties. Writes reject empty and prototype
 path segments before changing any object, create local containers for inherited
 values, and define own data properties without invoking inherited setters. Findings expose only the stable rule

package/docs/QUALITY_EVIDENCE.md

@@ -54,6 +54,15 @@ their real emitted-byte counts may differ. Output growth still fails the
 unchanged ceilings; normalization does not waive accounting, payload parity,
 required-field or executable-recovery checks.
 
+The completion-provenance delivery
+([pm-gh1579](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-gh1579.toon),
+a repository-only tracker record excluded from npm) makes the existing close and
+partial-bulk transcripts consume completion timestamp, source and correction
+guidance. Their reviewed ceilings increase by 76 and 80 estimated tokens
+respectively to account for this new required context. Other task and step
+ceilings, orientation selection, output accounting and the seeded growth
+negative control retain their existing enforcement.
+
 ## SDK mutation testing
 
 `pnpm quality:mutation` uses Stryker's Vitest runner to mutate the SDK cursor and

package/docs/READ_OUTPUT_CONTRACTS.md

@@ -4,6 +4,10 @@ Tracker references: [pm-15yuly](../.agents/pm/issues/pm-15yuly.toon), [pm-g8oh0f
 
 ## Agent Quick Context
 
+Complete package-envelope fitting and session-reference recovery are tracked by
+[pm-gh1567](../.agents/pm/issues/pm-gh1567.toon) and
+[pm-session-reference-recovery](../.agents/pm/issues/pm-session-reference-recovery.toon).
+
 Every built-in read surface uses four output dimensions: what to include, how much to return, how much the result may cost, and how to encode it. The same canonical controls work through the CLI, SDK, MCP, generated schemas, runtime contracts, and shell completions.
 
 | Dimension | CLI                              | SDK and MCP     | Meaning                                                                |
@@ -27,6 +31,56 @@ repeated metadata from results by default. Request
 `--output-row-contract` / `outputRowContract: true` when a consumer needs the
 row paths, jq selector, and active TOON encoding contract.
 
+### Package-defined complete envelopes
+
+`fitOutputEnvelope` is available from `@unbrained/pm-cli/sdk/query`, the
+aggregate SDK, and an extension command's `sdk.fitOutputEnvelope`. It fits
+ordered whole rows into a caller-defined envelope without changing domain
+ranking, metadata or transport policy:
+
+```ts
+import { fitOutputEnvelope } from "@unbrained/pm-cli/sdk/query";
+
+const fitted = fitOutputEnvelope([{ id: "one", title: "Context" }], {
+  tokenBudget: 800,
+  buildEnvelope: (items) => ({ source: "my-package", items }),
+  renderers: { json: (value) => JSON.stringify(value) + "\n" },
+});
+process.stdout.write(fitted.renderings[0]!.text);
+```
+
+The SDK reserves `output_fit`, attaches the omission/accounting receipt, and
+stabilizes its `estimated_tokens` and `output_bytes` against complete output,
+including the receipt itself and caller-supplied framing. Multiple required
+renderers may be supplied, such as JSON and TOON; each must fit, and the receipt
+records the greatest token estimate and byte count independently. Emit a cached
+rendering directly: another serializer or extra newline changes its cost.
+`buildEnvelope` can read the receipt for a package-owned self-accounting field.
+
+The default estimator is `ceil(UTF-8 bytes / 4)`. Supply `estimateTokens` for
+another contract, including a stronger one-token-per-byte bound. Estimates are
+not a tokenizer guarantee. Callbacks must be pure, deterministic, promptly
+returning, and include mandatory metadata in every rendering. The SDK does not
+interpret package fields or provider authentication.
+
+The default `prefix` policy stops at the first row that does not fit. `skip`
+tries later rows without changing their order. The receipt retains original
+`included_indices`, `total_candidates` and `omitted_count`; `complete` on the
+result means all candidate rows fit. Neither policy splits rows or assumes
+serialized size is monotone. A smaller budget does not promise nested selected
+sets under `skip`; use `prefix` when prefix continuity matters.
+
+The empty mandatory envelope must fit before any row is attempted.
+`OutputEnvelopeFitError.code` distinguishes `output_envelope_infeasible`
+(with `minimum_tokens`), `output_envelope_work_limit`, and
+`output_envelope_unstable`. No unverified or oversized packet is returned.
+`maxRenderCalls` defaults to 10,000 across every trial and renderer;
+`maxStabilizationPasses` defaults to 16 per trial. Actual renderer calls and
+evaluated candidates are reported in `work`, outside the measured packet.
+These ceilings bound fitting work; they cannot interrupt arbitrary callback
+execution. Existing candidate-projection packing and pre-receipt token
+attribution retain their distinct contracts.
+
 ### Include Modes
 
 `--output-include` accepts two kinds of token. A **field selector** names a row
@@ -195,7 +249,7 @@ The session ceiling and an explicit `--output-budget` both bind; the smaller
 remaining allowance wins. Rows for item facts already present in the caller's
 context become `{ "id": "pm-a1b2", "context_ref":
 "session:orientation:pm-a1b2" }` instead of repeating prose. References retain
-stable item identity and can be restored with `pm get <item-id> --brief` when
+stable item identity and can be restored with `pm get <item-id> --depth brief` when
 the prior context is unavailable. The receipt reports estimated and charged
 tokens separately when the remaining group allowance is smaller than the
 minimum control envelope, plus the accumulated spend, remaining capacity,

package/docs/SDK.md

@@ -312,6 +312,19 @@ explicitly installs the merge-aware pre-commit hook; the default installs no hoo
 verified lossless history and receipt artifacts. It refuses forced acceptance,
 competing values, unrelated drift, dirty reconciliation paths and unresolved Git
 paths. `staged_paths` reports exactly which relative paths were added to the index.
+Git-ignored artifacts refuse before staging or auditing with
+`merge_settlement_review_required`, `reason: ignored_merge_artifacts`, relative
+`paths`, and owning ignore-rule coordinates. The same check applies to
+`{ stage: true, dryRun: true }`; health reports legacy directory rules before a
+merge exists. This recovery is tracked by
+[pm-gh1556](../.agents/pm/issues/pm-gh1556.toon).
+
+`mergeHistoryStreams` preserves validated whole-field assignment/removal intent
+when another branch removed its target. Nested or conditional patches that
+cannot replay refuse with `history_union_rebase_conflict` and typed
+`PmCliError.context.history_merge` coordinates, retaining source inputs for
+deliberate recovery. See [history semantics](MERGE_SAFETY.md#artifact-semantics)
+and [pm-gh1553](../.agents/pm/issues/pm-gh1553.toon).
 
 The single-commit journey pauses Git with `git merge --no-commit --no-ff` before
 reconciliation or an opted-in pre-commit hook runs. `durable_receipt_ids` on the
@@ -586,6 +599,17 @@ sentinel rather than presenting it as a mistyped pm id.
 
 ### Agent output budgets and discovery
 
+Package-defined packets can use `fitOutputEnvelope` from the query entrypoint
+or `CommandHandlerContext.sdk.fitOutputEnvelope` to fit complete JSON/TOON
+renderings, including self-accounting receipts and framing. See
+[complete envelope fitting](READ_OUTPUT_CONTRACTS.md#package-defined-complete-envelopes)
+for policies, work ceilings and refusal contracts, tracked by
+[pm-gh1567](../.agents/pm/issues/pm-gh1567.toon).
+Session receipts now advertise `pm get <item-id> --depth brief`; the
+`restore_reference_with` literal type changes accordingly. Hosts constructing
+`ExtensionCommandSdk` implementations must supply `fitOutputEnvelope` from the
+public SDK; host-created command contexts already provide it.
+
 Tracked by [pm-5t33or](../.agents/pm/features/pm-5t33or.toon),
 [pm-gmdzaa](../.agents/pm/issues/pm-gmdzaa.toon), and
 [pm-dpqa3h](../.agents/pm/chores/pm-dpqa3h.toon).
@@ -643,12 +667,41 @@ explicit full projection. Active package commands receive deterministic
 fallback contracts, so extension authors can discover a bounded surface before
 they invoke it.
 
-`pm activity` applies a compact 20-row default bound; direct SDK calls default
-to five full rows. Results disclose `total_count`, `omitted_count`, `has_more`,
-and `applied_bound`. An explicit `limit` remains authoritative, while
-`unbounded: true` (CLI: `--unbounded`) is an intentional opt-out and cannot be
-combined with a limit. The activity flag and tool schemas publish the same
-option for extension and transport consumers.
+`runActivity` defaults to a 15-item digest over the last 24 hours. `raw: true`
+selects compact events (20 by default); `raw: true, compact: false` selects full
+history entries (five by default). CLI equivalents are `--raw` and `--full`.
+Results disclose `total_count`, `count`, `page_start`, `omitted_count`,
+`has_more`, `next_cursor`, and `applied_bound`. Continue with the same options
+and `after: result.next_cursor` (CLI/MCP: `--after` / `after`). Page size may
+change. `omitted_count` counts rows remaining after the current page.
+
+Activity's `window` publishes the original evaluation `anchor`, inclusive
+`from`, and exclusive `to`. Bounded reads without an explicit upper bound pin
+`to` to that anchor. Relative bounds resolve against the same clock on every
+page. Later writes outside the window do not disturb continuation. Query,
+projection, workspace, or matching-content changes refuse the old cursor with
+`invalid_query_cursor`; start the query again without `after`. This is checked
+continuation over an unchanged matching set, not a persisted snapshot or an
+atomic cross-file read. Backdated writes within the window and current metadata
+changes affecting digest rows can require a restart. `unbounded: true`
+intentionally removes the row bound and cannot be combined with a limit.
+
+Queries collect the matching rows and scan them on each page to detect changes.
+Content fingerprints hash canonical rows incrementally, bounding additional
+serialization storage to the largest row. Digest activity also hashes its full
+source events incrementally so hidden patch changes still invalidate a cursor.
+
+`runCalendar` uses the same `after` contract and frozen clock. `total_count`
+counts matching expanded rows within the selected window and recurrence caps;
+`count`, `page_start`, `omitted_count`, `has_more`, and `next_cursor` describe
+the page. `summary_scope: "returned_rows"` labels `summary` and `days` as
+page-local. Exact-full and empty results have `has_more: false`. A zero limit
+returns counts without rows or a new cursor; repeat with `limit: "1"` or larger
+to fetch rows. Existing recurrence expansion limits remain separate from
+pagination, and calendar mutations affecting matching rows require a restart.
+Repository tracking (PM records are excluded from the npm package):
+[pm-gh1554](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-gh1554.toon)
+and [pm-gh1562](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-gh1562.toon).
 
 The required `quality:token-budget` gate keeps discovery and answer cost
 separate. Help and contract discovery surfaces use ratcheted baselines;
@@ -1011,6 +1064,18 @@ pm contracts --action calendar --runtime-only --schema-only --json
 pm contracts --command templates --runtime-only --flags-only --json
 ```
 
+The SDK owns template persistence independently of the presentation package.
+`runTemplatesSave(name, options: TemplatesSaveOptions, global)` accepts priority
+as an integer `0..4`, a numeric string, or a named priority such as `critical`.
+It validates priority before writing and stores its normalized numeric string;
+`0` therefore survives save, show, and item creation. Invalid priority values
+refuse with exit code 2 and the accepted forms, preserving the template and
+workspace history. Other template keys retain the existing string/string-array
+storage contract, including extension-defined fields. Import the input type
+and function from `@unbrained/pm-cli/sdk/runtime` or the aggregate SDK.
+Tracked by [pm-gh1561](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-gh1561.toon)
+(repository-only tracker record, excluded from npm).
+
 Use static SDK contracts for baseline validation, then use runtime contracts in the target project before invoking package-provided commands or actions. Embedded SDK consumers can avoid subprocesses:
 
 ```ts
@@ -1069,6 +1134,28 @@ recurrence reason, accepts only the workspace open or in-progress target, and
 returns the terminal evidence captured atomically before the update path clears
 it from active metadata.
 
+Create focus policy is tracked by [pm-gh1577](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-gh1577.toon)
+(this tracker record is repository-only and excluded from npm).
+Programmatic `create`, `PmClient.create`, `runCreate`, and MCP `pm_create`
+ignore saved session focus unless `inheritFocus: true` is supplied. An explicit
+parent, a parent from the selected template, or `unset: ["parent"]` takes
+precedence. Create receipts report `parent_source: "focus"`; the effective
+parent remains in the item and immutable create event. Plan results expose the
+effective parent as `plan.parent`. `pm create` and
+`pm plan create` enable this convenience by default; `--no-inherit-focus` or
+`--parent none` suppresses it (`pm create` also accepts `--unset parent`).
+SDK `planCreate` and MCP plan creation follow the same explicit opt-in policy.
+SDK scheduling shortcuts follow the same opt-in policy; package scheduling
+commands retain their focused creation convenience.
+
+Other create defaults still apply: an explicitly selected template supplies
+options before explicit caller values, workspace governance selects the default
+type/create mode, the type workflow selects its initial status, priority defaults
+to 2, tags to an empty array, and author identity comes from invocation/workspace
+policy. There is no implicit saved assignee or tag default outside the selected
+template. Importers should supply explicit type, status, priority, tags, assignee,
+and parent/unset policy when those values are part of their source contract.
+
 Lifecycle handoff and receipt guidance are tracked by
 [pm-gh1465](../.agents/pm/features/pm-gh1465.toon) and
 [pm-gh1464](../.agents/pm/issues/pm-gh1464.toon). Register a project-specific
@@ -1120,10 +1207,31 @@ If a process stops between the domain write and the journal update, rerunning
 the same plan discovers the already-applied step and continues. An ordinary
 error switches the journal to compensation mode and runs applied steps in
 reverse order, limited to steps whose forward attempt was durably recorded.
+Adapters can opt into `compensatePending: true` when `apply()` may fail after
+an internal write while inspection still reports `pending`. Such compensators
+must handle absent and partial effects idempotently. The default preserves
+applied-only compensation; an inspected `compensated` step is skipped.
+If compensation refuses, the journal retains its started steps
+and recovery data in `compensating` state instead of claiming a rollback.
 Compensations are new item-history or relationship events: the
 coordinator never deletes or rewrites immutable history. A crash during
 compensation resumes compensation before a new attempt begins.
 
+Guarded terminal updates are tracked by
+[pm-pllp78](../.agents/pm/issues/pm-pllp78.toon). A bulk update's `match` guard
+is checked under each item lock and advances to the operation's own committed
+key value before its next internal lifecycle write. A stale starting value
+still refuses without item or history writes. Item updates opt into pending
+compensation and attribute every internal write in immutable history. New
+receipts bind the history fingerprint, integer prefix length and exact version, so writes sharing
+one timestamp remain distinguishable. Recovery restores exclusively owned
+effects and preserves peer-only changes. Mixed ownership, rewritten receipts,
+or a peer write before the restore lock refuse with
+`transaction_partial_mutation`; the surfaced `AggregateError` retains both
+failures and the journal keeps recovery data. Repeated compensation recognizes
+its durable marker even when a peer adds context afterward. Legacy timestamp
+receipts remain supported, with ambiguous partial effects refused.
+
 ### Schema evolution and workspace history
 
 Tracked by [pm-dijg](../.agents/pm/features/pm-dijg.toon) and
@@ -1473,8 +1581,9 @@ handlers remain disabled. Package-backed `--template` create input cannot be
 semantically previewed through its package handler; expand it into explicit core
 mutation options before preview.
 
-Actionable previews are tracked by [pm-ekf2gu](../.agents/pm/issues/pm-ekf2gu.toon)
-and [pm-fa9olc](../.agents/pm/tasks/pm-fa9olc.toon).
+Actionable previews are tracked by [pm-ekf2gu](../.agents/pm/issues/pm-ekf2gu.toon),
+[pm-fa9olc](../.agents/pm/tasks/pm-fa9olc.toon), and
+[pm-jhkzk0](../.agents/pm/features/pm-jhkzk0.toon).
 `previewItemMutations` returns `warnings` grouped by zero-based operation
 `index`, canonical `id`, and `op`. These are the original create lifecycle
 warnings, including advisory `likely_duplicates` and duplicate-recovery tokens.
@@ -1490,7 +1599,14 @@ use this same projection. A `replayed_committed_plan` has no newly evaluated
 warnings; an empty warning list in that state does not certify current policy.
 
 Staging excludes derived `search` and `locks` content and unrelated runtime state,
-retaining registered item folders, explicitly configured schema files, and
+plus `extensions/<directory>/node_modules` dependency trees. These trees are
+excluded before entry inspection or traversal, including dependency links;
+configured schema files and registered item folders take precedence and retain
+the regular-file safety checks even inside a dependency tree. Extension source,
+manifests and managed-package metadata remain in the snapshot. The receipt
+declares `derived_extension_dependencies_excluded` among its unresolved commit
+constraints because executable package dependencies are not validated.
+Staging retains registered item folders, explicitly configured schema files, and
 `runtime/session.json` for core focus and inherited-parent semantics. Root-layout
 trackers copy only tracker-owned files and directories, including standard and
 custom item folders and configured schema files; unrelated project content is
@@ -1741,6 +1857,23 @@ the SDK search engine directly. Package authors can import these functions and
 their typed result contracts from `@unbrained/pm-cli/sdk` without importing CLI
 implementation modules.
 
+Read projections also accept metadata names registered by active extensions with
+`registerItemFields`, including `item.<name>` selectors. For example,
+`client.get(id, { fields: "id,probe_score" })` returns the declared numeric value
+without requiring a full item read. `list` and `search` use the same active field
+vocabulary; search retains the requested selector spelling in its row keys.
+Disabling the extension removes its selectors from validation and recovery.
+Unknown names still refuse, and recovery retains valid requested custom fields.
+Tracked by [pm-gh1571](../.agents/pm/issues/pm-gh1571.toon).
+
+Settings reads load optional schema files without creating missing files. Missing
+sections use configured or built-in defaults in memory, and later file creation
+invalidates the settings cache. Explicit `pm init --defaults` scaffolds missing
+sections while preserving existing schema definitions. This applies to shared
+SDK settings reads and CLI read commands; derived query caches and normal
+observability retain their own policies. Tracked by
+[pm-gh1568](../.agents/pm/issues/pm-gh1568.toon).
+
 The shared query cursor contract treats every published list, context, and
 search flag as query-semantic by default: it changes the matched or ordered
 result and therefore invalidates a cursor. Only page-size and rendering flags
@@ -1996,9 +2129,15 @@ signal-set metadata are supported, its item source matches, and its cursor,
 complete item-id set, and substantive recency-evidence fingerprint match.
 Missing, stale, version-incompatible, or corrupt state is rebuilt from the
 authoritative items and atomically replaced. The result reports `cache_status`
-and non-fatal `context_signal_store_stale`,
-`context_signal_store_invalid`, or `context_signal_store_write_failed`
-warnings. A write failure still serves the in-memory rebuilt candidates because
+without a warning for a successful missing/stale refresh
+([pm-gh1581](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-gh1581.toon);
+this tracker record is repository-only and excluded from npm). Rebuilt signals are used in
+the current response; another read is unnecessary. With `explainRanking`,
+`ranking.feature_store.cache_status` exposes the refresh on context receipts.
+Corrupt/unreadable state and failed persistence retain actionable
+`context_signal_store_invalid` and `context_signal_store_write_failed` warnings.
+The exported stale-warning descriptor remains for compatibility with older
+receipts. A write failure still serves the in-memory rebuilt candidates because
 the snapshot is derived, never authoritative. Optional maps for activity density,
 graph proximity, claim/focus, knowledge density, author affinity, usage
 affinity, and semantic similarity let an index or application-specific host
@@ -2510,6 +2649,14 @@ same list/default semantics as core flags:
   `default: "a,b"` or `default: ["a,b", "c"]`) are split into elements. A default
   that would not cleanly coerce under the declared `value_type` (e.g.
   `value_type: "number", default: "abc"`) is rejected at registration.
+  Declared defaults are discoverable without running the command: text help
+  shows `(default: ...)`, JSON help uses `default_value`, and runtime flag
+  contracts and command schemas use `default`, preserving strings, numbers,
+  booleans, empty strings and arrays. These are declaration values; runtime
+  coercion and list flattening still apply during execution. Explicit values
+  replace omitted-flag defaults, including list defaults. Tracked by
+  [pm-gh1560](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-gh1560.toon)
+  (repository-only tracker record, excluded from npm).
 - `value_validation` (`"coerce"` | `"strict"`, tracked by
   [pm-extension-scalar-validation](../.agents/pm/features/pm-extension-scalar-validation.toon))
   decides what happens to a `number`/`boolean` token that does not coerce.
@@ -3431,6 +3578,20 @@ search degrades gracefully and emits warning codes instead of hard-failing.
 
 ## Completion-aware reporting and migration
 
+Close provenance is tracked by [pm-gh1579](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-gh1579.toon)
+(a repository-only tracker record excluded from npm).
+`closeItem`, `PmClient.close`, CLI/MCP close receipts and successful `closeMany`
+rows return `completion` with the persisted `timestamp` and `source`:
+`asserted` means this close supplied `completedAt`, `existing` preserves an
+earlier metadata value, and `close_time` means completion was inferred from the
+tracker close time. Timestamp and source are sealed in the close event's
+`context.completion`; the local correction hint remains in the response.
+Existing records without it have unknown provenance;
+`existing` does not assert how an earlier value was obtained. No prior events are
+rewritten. Inferred receipts include a tracker-bound `update --completed-at`
+correction hint. Pass `completedAt` (CLI `--completed-at`) when closing delivered
+work retroactively; core never extracts a delivery date from reason prose.
+
 `resolveCompletionTimestamp(item)` gives reports one canonical timestamp plus a
 `source` and `fallback` disclosure. It prefers `completed_at` (when the work
 actually finished), then legacy `closed_at`, then `updated_at`.

package/docs/WORKFLOW_POLICIES.md

@@ -80,7 +80,20 @@ reviewable history and skip approval requirements; use `transition` rules with
 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
+refusal event. This append changes the tracked `history/_workspace.jsonl` file
+under the selected tracker. Retain it with the workspace changes. The typed SDK
+error's `context.side_effects` and CLI JSON `side_effects` disclose the
+tracker-relative `path`, `op: "policy_refused"`, and sealed `record_hash`; MCP
+error details retain the same context. Human-readable diagnostics also name the
+write. Every refused attempt records a distinct event and returns its own record
+identity, including repeated identical requests. This preserves attempt history
+instead of silently coalescing it. Dry-run refusals have `side_effects: []` and
+append nothing. An audit failure retains its separate error contract below and
+does not claim a completed append. This disclosure is tracked by
+[pm-gh1585](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/issues/pm-gh1585.toon)
+(a repository-only tracker record excluded from npm).
+
+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

package/docs/agent-task-token-baseline.json

@@ -1 +1 @@
-{"version":5,"transcript_version":2,"transcript_digest":"sha256:6d4041acfaa4075dde1972d6127a74f18916f7661738b4f5d5fd47a61c179a78","estimator":"ceil(utf8_bytes / 4)","comparison_scope":"plan_recovery_tracker_root_canonicalized","measurement_scope":"output_before_token_accounting","published_with_release":true,"orientation":{"canonical_task_id":"orientation-context-intent","required_capabilities":["actionable_work","active_ownership","workspace_state"],"measured_winner_tokens":1087,"protocols":[{"task_id":"orientation-context-intent","command_count":1,"estimated_tokens":1087,"capabilities":["actionable_work","active_ownership","workspace_state"],"capability_evidence":{"actionable_work":[{"step_id":"context","field_path":"hierarchy"}],"active_ownership":[{"step_id":"context","field_path":"activity"}],"workspace_state":[{"step_id":"context","field_path":"summary.active_items"}]}},{"task_id":"orientation-operating-rules","command_count":4,"estimated_tokens":2139,"capabilities":["actionable_work","active_ownership","workspace_state"],"capability_evidence":{"actionable_work":[{"step_id":"open","field_path":"items"}],"active_ownership":[{"step_id":"in-progress","field_path":"items"}],"workspace_state":[{"step_id":"context","field_path":"summary.active_items"}]}},{"task_id":"orientation-contracts-next","command_count":2,"estimated_tokens":5203,"capabilities":["actionable_work","active_ownership","workspace_state"],"capability_evidence":{"actionable_work":[{"step_id":"next","field_path":"recommended.id"}],"active_ownership":[{"step_id":"next","field_path":"held_by_others"}],"workspace_state":[{"step_id":"next","field_path":"summary.in_progress"}]}}]},"tasks":[{"id":"orientation-context-intent","max_estimated_tokens":1087,"steps":[{"id":"context","max_estimated_tokens":1087,"accounting_mode":"self_reported"}]},{"id":"orientation-contracts-next","max_estimated_tokens":5203,"steps":[{"id":"contracts","max_estimated_tokens":4481,"accounting_mode":"self_reported"},{"id":"next","max_estimated_tokens":722,"accounting_mode":"self_reported"}]},{"id":"orientation-operating-rules","max_estimated_tokens":2139,"steps":[{"id":"context","max_estimated_tokens":1087,"accounting_mode":"self_reported"},{"id":"search","max_estimated_tokens":164,"accounting_mode":"self_reported"},{"id":"open","max_estimated_tokens":712,"accounting_mode":"self_reported"},{"id":"in-progress","max_estimated_tokens":176,"accounting_mode":"self_reported"}]},{"id":"context-bootstrap","max_estimated_tokens":2077,"steps":[{"id":"triage","max_estimated_tokens":619,"accounting_mode":"self_reported"},{"id":"orient","max_estimated_tokens":1087,"accounting_mode":"self_reported"},{"id":"inspect","max_estimated_tokens":371,"accounting_mode":"self_reported"}]},{"id":"closed-domain-recovery","max_estimated_tokens":630,"steps":[{"id":"refuse-intent","max_estimated_tokens":259,"accounting_mode":"self_reported"},{"id":"retry-intent","max_estimated_tokens":371,"accounting_mode":"self_reported"}]},{"id":"unknown-option-recovery","max_estimated_tokens":596,"steps":[{"id":"refuse-option","max_estimated_tokens":433,"accounting_mode":"self_reported"},{"id":"retry-option","max_estimated_tokens":163,"accounting_mode":"self_reported"}]},{"id":"lifecycle-mutation","max_estimated_tokens":812,"steps":[{"id":"create","max_estimated_tokens":20,"accounting_mode":"self_reported"},{"id":"inspect-open","max_estimated_tokens":363,"accounting_mode":"self_reported"},{"id":"close","max_estimated_tokens":31,"accounting_mode":"self_reported"},{"id":"inspect-closed","max_estimated_tokens":398,"accounting_mode":"self_reported"}]},{"id":"bulk-effect-outcomes","max_estimated_tokens":326,"steps":[{"id":"create-bulk-target","max_estimated_tokens":20,"accounting_mode":"self_reported"},{"id":"partial-effect","max_estimated_tokens":174,"accounting_mode":"self_reported"},{"id":"no-effect","max_estimated_tokens":132,"accounting_mode":"self_reported"}]},{"id":"plan-execution-mutations","max_estimated_tokens":806,"steps":[{"id":"create-plan","max_estimated_tokens":21,"accounting_mode":"self_reported"},{"id":"add-step","max_estimated_tokens":254,"accounting_mode":"self_reported"},{"id":"complete-step","max_estimated_tokens":253,"accounting_mode":"self_reported"},{"id":"inspect-plan","max_estimated_tokens":278,"accounting_mode":"self_reported"}]}],"composite_max_estimated_tokens":13676}
+{"version":5,"transcript_version":2,"transcript_digest":"sha256:83d4523ca528ad5e8801cf5c7c02dcebbf2b87dc72422d4b8e648755dcdc36c2","estimator":"ceil(utf8_bytes / 4)","comparison_scope":"plan_recovery_tracker_root_canonicalized","measurement_scope":"output_before_token_accounting","published_with_release":true,"orientation":{"canonical_task_id":"orientation-context-intent","required_capabilities":["actionable_work","active_ownership","workspace_state"],"measured_winner_tokens":1087,"protocols":[{"task_id":"orientation-context-intent","command_count":1,"estimated_tokens":1087,"capabilities":["actionable_work","active_ownership","workspace_state"],"capability_evidence":{"actionable_work":[{"step_id":"context","field_path":"hierarchy"}],"active_ownership":[{"step_id":"context","field_path":"activity"}],"workspace_state":[{"step_id":"context","field_path":"summary.active_items"}]}},{"task_id":"orientation-operating-rules","command_count":4,"estimated_tokens":2139,"capabilities":["actionable_work","active_ownership","workspace_state"],"capability_evidence":{"actionable_work":[{"step_id":"open","field_path":"items"}],"active_ownership":[{"step_id":"in-progress","field_path":"items"}],"workspace_state":[{"step_id":"context","field_path":"summary.active_items"}]}},{"task_id":"orientation-contracts-next","command_count":2,"estimated_tokens":5203,"capabilities":["actionable_work","active_ownership","workspace_state"],"capability_evidence":{"actionable_work":[{"step_id":"next","field_path":"recommended.id"}],"active_ownership":[{"step_id":"next","field_path":"held_by_others"}],"workspace_state":[{"step_id":"next","field_path":"summary.in_progress"}]}}]},"tasks":[{"id":"orientation-context-intent","max_estimated_tokens":1087,"steps":[{"id":"context","max_estimated_tokens":1087,"accounting_mode":"self_reported"}]},{"id":"orientation-contracts-next","max_estimated_tokens":5203,"steps":[{"id":"contracts","max_estimated_tokens":4481,"accounting_mode":"self_reported"},{"id":"next","max_estimated_tokens":722,"accounting_mode":"self_reported"}]},{"id":"orientation-operating-rules","max_estimated_tokens":2139,"steps":[{"id":"context","max_estimated_tokens":1087,"accounting_mode":"self_reported"},{"id":"search","max_estimated_tokens":164,"accounting_mode":"self_reported"},{"id":"open","max_estimated_tokens":712,"accounting_mode":"self_reported"},{"id":"in-progress","max_estimated_tokens":176,"accounting_mode":"self_reported"}]},{"id":"context-bootstrap","max_estimated_tokens":2077,"steps":[{"id":"triage","max_estimated_tokens":619,"accounting_mode":"self_reported"},{"id":"orient","max_estimated_tokens":1087,"accounting_mode":"self_reported"},{"id":"inspect","max_estimated_tokens":371,"accounting_mode":"self_reported"}]},{"id":"closed-domain-recovery","max_estimated_tokens":630,"steps":[{"id":"refuse-intent","max_estimated_tokens":259,"accounting_mode":"self_reported"},{"id":"retry-intent","max_estimated_tokens":371,"accounting_mode":"self_reported"}]},{"id":"unknown-option-recovery","max_estimated_tokens":596,"steps":[{"id":"refuse-option","max_estimated_tokens":433,"accounting_mode":"self_reported"},{"id":"retry-option","max_estimated_tokens":163,"accounting_mode":"self_reported"}]},{"id":"lifecycle-mutation","max_estimated_tokens":888,"steps":[{"id":"create","max_estimated_tokens":20,"accounting_mode":"self_reported"},{"id":"inspect-open","max_estimated_tokens":363,"accounting_mode":"self_reported"},{"id":"close","max_estimated_tokens":107,"accounting_mode":"self_reported"},{"id":"inspect-closed","max_estimated_tokens":398,"accounting_mode":"self_reported"}]},{"id":"bulk-effect-outcomes","max_estimated_tokens":406,"steps":[{"id":"create-bulk-target","max_estimated_tokens":20,"accounting_mode":"self_reported"},{"id":"partial-effect","max_estimated_tokens":254,"accounting_mode":"self_reported"},{"id":"no-effect","max_estimated_tokens":132,"accounting_mode":"self_reported"}]},{"id":"plan-execution-mutations","max_estimated_tokens":806,"steps":[{"id":"create-plan","max_estimated_tokens":21,"accounting_mode":"self_reported"},{"id":"add-step","max_estimated_tokens":254,"accounting_mode":"self_reported"},{"id":"complete-step","max_estimated_tokens":253,"accounting_mode":"self_reported"},{"id":"inspect-plan","max_estimated_tokens":278,"accounting_mode":"self_reported"}]}],"composite_max_estimated_tokens":13832}

package/docs/agent-task-transcripts.json

@@ -1 +1 @@
-{"version":2,"orientation":{"canonical_task_id":"orientation-context-intent","required_capabilities":["workspace_state","active_ownership","actionable_work"],"protocols":[{"task_id":"orientation-context-intent","capabilities":["workspace_state","active_ownership","actionable_work"],"capability_evidence":{"workspace_state":[{"step_id":"context","field_path":"summary.active_items"}],"active_ownership":[{"step_id":"context","field_path":"activity"}],"actionable_work":[{"step_id":"context","field_path":"hierarchy"}]}},{"task_id":"orientation-contracts-next","capabilities":["workspace_state","active_ownership","actionable_work"],"capability_evidence":{"workspace_state":[{"step_id":"next","field_path":"summary.in_progress"}],"active_ownership":[{"step_id":"next","field_path":"held_by_others"}],"actionable_work":[{"step_id":"next","field_path":"recommended.id"}]}},{"task_id":"orientation-operating-rules","capabilities":["workspace_state","active_ownership","actionable_work"],"capability_evidence":{"workspace_state":[{"step_id":"context","field_path":"summary.active_items"}],"active_ownership":[{"step_id":"in-progress","field_path":"items"}],"actionable_work":[{"step_id":"open","field_path":"items"}]}}]},"tasks":[{"id":"orientation-context-intent","description":"Build sufficient cold-start workspace, ownership, and actionable-work context with the bounded orientation intent.","steps":[{"id":"context","args":["context","--for","orient","--limit","10"],"expected_exit_code":0,"expected_output_kind":"diagnostic","expected_accounting_mode":"self_reported","required_fields":["summary.active_items","hierarchy","activity"]}]},{"id":"orientation-contracts-next","description":"Compare the proposed contracts-summary plus next cold-start protocol on the same fixed workspace.","steps":[{"id":"contracts","args":["contracts","--summary"],"expected_exit_code":0,"expected_output_kind":"collection","expected_accounting_mode":"self_reported","required_fields":["commands"]},{"id":"next","args":["next","--for","execute","--ready-only","--limit","3"],"expected_exit_code":0,"expected_output_kind":"diagnostic","expected_accounting_mode":"self_reported","required_fields":["summary.in_progress","held_by_others","recommended.id"]}]},{"id":"orientation-operating-rules","description":"Compare the historical context, search, open-list, and in-progress-list orientation sequence.","steps":[{"id":"context","args":["context","--for","orient","--limit","10"],"expected_exit_code":0,"expected_output_kind":"diagnostic","expected_accounting_mode":"self_reported","required_fields":["summary.active_items","hierarchy","activity"]},{"id":"search","args":["search","agent task","--status","all","--limit","10"],"expected_exit_code":0,"expected_output_kind":"collection","expected_accounting_mode":"self_reported","required_fields":["items"]},{"id":"open","args":["list","--status","open","--limit","20"],"expected_exit_code":0,"expected_output_kind":"collection","expected_accounting_mode":"self_reported","required_fields":["items"]},{"id":"in-progress","args":["list","--status","in_progress","--limit","20"],"expected_exit_code":0,"expected_output_kind":"collection","expected_accounting_mode":"self_reported","required_fields":["items"]}]},{"id":"context-bootstrap","description":"Orient in a scaled workspace and inspect the canonical focus item.","steps":[{"id":"triage","args":["list","--for","triage","--limit","2"],"expected_exit_code":0,"expected_output_kind":"collection","expected_accounting_mode":"self_reported","required_fields":["items"]},{"id":"orient","args":["context","--for","orient","--limit","5"],"expected_exit_code":0,"expected_output_kind":"diagnostic","expected_accounting_mode":"self_reported","required_fields":["summary.active_items","hierarchy","activity"]},{"id":"inspect","args":["get","$ANCHOR_ID","--for","inspect"],"expected_exit_code":0,"expected_output_kind":"entity","expected_accounting_mode":"self_reported","required_fields":["item.id"]}]},{"id":"closed-domain-recovery","description":"Reject an invalid context intent and execute the advertised shell-free retry.","steps":[{"id":"refuse-intent","args":["get","$ANCHOR_ID","--for","invalid-agent-intent"],"expected_exit_code":2,"expected_output_kind":"refusal","expected_accounting_mode":"self_reported","required_fields":["code","refusal","recovery"],"expected_error_code":"unknown_context_intent","expected_field_values":{"recovery.recovery_mode":"compact"},"expected_refusal_surface":"--for"},{"id":"retry-intent","args":["get","$ANCHOR_ID","--for","inspect"],"expected_exit_code":0,"expected_output_kind":"entity","expected_accounting_mode":"self_reported","required_fields":["item.id"],"recovery_for":"refuse-intent"}]},{"id":"unknown-option-recovery","description":"Identify an unsupported option after valid flags and continue with the corrected command.","steps":[{"id":"refuse-option","args":["search","agent task","--status","open","--limit","5","--include-body"],"expected_exit_code":2,"expected_output_kind":"refusal","expected_accounting_mode":"self_reported","required_fields":["code","refusal","recovery"],"expected_error_code":"unknown_option","expected_refusal_surface":"--include-body"},{"id":"retry-option","args":["search","agent task","--status","open","--limit","5"],"expected_exit_code":0,"expected_output_kind":"collection","expected_accounting_mode":"self_reported","required_fields":["items"],"recovery_for":"refuse-option"}]},{"id":"lifecycle-mutation","description":"Create, inspect, close, and confirm a project item through public CLI receipts.","steps":[{"id":"create","args":["create","--id","$LIFECYCLE_ID","--title","Transcript lifecycle item","--description","Golden multi-step lifecycle task","--type","Task","--status","open","--create-mode","progressive"],"expected_exit_code":0,"expected_output_kind":"mutation_receipt","expected_accounting_mode":"self_reported","required_fields":["id","changed_field_count"]},{"id":"inspect-open","args":["get","$LIFECYCLE_ID","--for","inspect"],"expected_exit_code":0,"expected_output_kind":"entity","expected_accounting_mode":"self_reported","required_fields":["item.id","item.status"],"expected_field_values":{"item.status":"open"}},{"id":"close","args":["close","$LIFECYCLE_ID","Golden task completed"],"expected_exit_code":0,"expected_output_kind":"mutation_receipt","expected_accounting_mode":"self_reported","required_fields":["id","status","close_reason"]},{"id":"inspect-closed","args":["get","$LIFECYCLE_ID","--for","inspect"],"expected_exit_code":0,"expected_output_kind":"entity","expected_accounting_mode":"self_reported","required_fields":["item.id","item.status"],"expected_field_values":{"item.status":"closed"}}]},{"id":"bulk-effect-outcomes","description":"Preserve successful partial-effect and no-effect outcomes across a bulk lifecycle task.","steps":[{"id":"create-bulk-target","args":["create","--id","$BULK_ID","--title","Transcript bulk effect target","--description","Golden bulk outcome transcript target","--type","Task","--status","open","--create-mode","progressive"],"expected_exit_code":0,"expected_output_kind":"mutation_receipt","expected_accounting_mode":"self_reported","required_fields":["id","status","changed_field_count"]},{"id":"partial-effect","args":["close-many","--ids","$BULK_ID,pm-transcript-missing","--reason","Golden partial-effect transcript","--validate-close","off","--no-checkpoint"],"expected_exit_code":7,"expected_output_kind":"collection","expected_accounting_mode":"self_reported","required_fields":["rows","outcome","exit_code"],"expected_field_values":{"outcome":"partial_effect"}},{"id":"no-effect","args":["close-many","--ids","$BULK_ID","--reason","Golden no-effect transcript","--validate-close","off","--no-checkpoint"],"expected_exit_code":6,"expected_output_kind":"collection","expected_accounting_mode":"self_reported","required_fields":["rows","outcome","exit_code"],"expected_field_values":{"outcome":"no_effect"}}]},{"id":"plan-execution-mutations","description":"Create a Plan, add and complete a step, then inspect its durable evidence without echoing the full Plan on each mutation.","steps":[{"id":"create-plan","args":["create","--id","pm-transcript-plan","--type","Plan","--title","Transcript execution Plan","--create-mode","progressive"],"expected_exit_code":0,"expected_output_kind":"mutation_receipt","expected_accounting_mode":"self_reported","required_fields":["id","status"]},{"id":"add-step","args":["plan","add-step","pm-transcript-plan","--step-title","Verify result","--step-body","Durable execution context retained for later inspection."],"expected_exit_code":0,"expected_output_kind":"diagnostic","expected_accounting_mode":"self_reported","required_fields":["id","step.id","steps_summary.total","inspection_command"],"expected_field_values":{"kind":"plan_mutation","steps_summary.total":1}},{"id":"complete-step","args":["plan","complete-step","pm-transcript-plan","plan-step-001","--step-evidence","Verified result"],"expected_exit_code":0,"expected_output_kind":"diagnostic","expected_accounting_mode":"self_reported","required_fields":["id","step.status","steps_summary.completed","omission_receipt"],"expected_field_values":{"step.status":"completed","steps_summary.completed":1}},{"id":"inspect-plan","args":["plan","show","pm-transcript-plan","--depth","deep"],"expected_exit_code":0,"expected_output_kind":"diagnostic","expected_accounting_mode":"self_reported","required_fields":["plan.steps","plan.steps_summary.completed"],"expected_field_values":{"plan.steps_summary.completed":1}}]}]}
+{"version":2,"orientation":{"canonical_task_id":"orientation-context-intent","required_capabilities":["workspace_state","active_ownership","actionable_work"],"protocols":[{"task_id":"orientation-context-intent","capabilities":["workspace_state","active_ownership","actionable_work"],"capability_evidence":{"workspace_state":[{"step_id":"context","field_path":"summary.active_items"}],"active_ownership":[{"step_id":"context","field_path":"activity"}],"actionable_work":[{"step_id":"context","field_path":"hierarchy"}]}},{"task_id":"orientation-contracts-next","capabilities":["workspace_state","active_ownership","actionable_work"],"capability_evidence":{"workspace_state":[{"step_id":"next","field_path":"summary.in_progress"}],"active_ownership":[{"step_id":"next","field_path":"held_by_others"}],"actionable_work":[{"step_id":"next","field_path":"recommended.id"}]}},{"task_id":"orientation-operating-rules","capabilities":["workspace_state","active_ownership","actionable_work"],"capability_evidence":{"workspace_state":[{"step_id":"context","field_path":"summary.active_items"}],"active_ownership":[{"step_id":"in-progress","field_path":"items"}],"actionable_work":[{"step_id":"open","field_path":"items"}]}}]},"tasks":[{"id":"orientation-context-intent","description":"Build sufficient cold-start workspace, ownership, and actionable-work context with the bounded orientation intent.","steps":[{"id":"context","args":["context","--for","orient","--limit","10"],"expected_exit_code":0,"expected_output_kind":"diagnostic","expected_accounting_mode":"self_reported","required_fields":["summary.active_items","hierarchy","activity"]}]},{"id":"orientation-contracts-next","description":"Compare the proposed contracts-summary plus next cold-start protocol on the same fixed workspace.","steps":[{"id":"contracts","args":["contracts","--summary"],"expected_exit_code":0,"expected_output_kind":"collection","expected_accounting_mode":"self_reported","required_fields":["commands"]},{"id":"next","args":["next","--for","execute","--ready-only","--limit","3"],"expected_exit_code":0,"expected_output_kind":"diagnostic","expected_accounting_mode":"self_reported","required_fields":["summary.in_progress","held_by_others","recommended.id"]}]},{"id":"orientation-operating-rules","description":"Compare the historical context, search, open-list, and in-progress-list orientation sequence.","steps":[{"id":"context","args":["context","--for","orient","--limit","10"],"expected_exit_code":0,"expected_output_kind":"diagnostic","expected_accounting_mode":"self_reported","required_fields":["summary.active_items","hierarchy","activity"]},{"id":"search","args":["search","agent task","--status","all","--limit","10"],"expected_exit_code":0,"expected_output_kind":"collection","expected_accounting_mode":"self_reported","required_fields":["items"]},{"id":"open","args":["list","--status","open","--limit","20"],"expected_exit_code":0,"expected_output_kind":"collection","expected_accounting_mode":"self_reported","required_fields":["items"]},{"id":"in-progress","args":["list","--status","in_progress","--limit","20"],"expected_exit_code":0,"expected_output_kind":"collection","expected_accounting_mode":"self_reported","required_fields":["items"]}]},{"id":"context-bootstrap","description":"Orient in a scaled workspace and inspect the canonical focus item.","steps":[{"id":"triage","args":["list","--for","triage","--limit","2"],"expected_exit_code":0,"expected_output_kind":"collection","expected_accounting_mode":"self_reported","required_fields":["items"]},{"id":"orient","args":["context","--for","orient","--limit","5"],"expected_exit_code":0,"expected_output_kind":"diagnostic","expected_accounting_mode":"self_reported","required_fields":["summary.active_items","hierarchy","activity"]},{"id":"inspect","args":["get","$ANCHOR_ID","--for","inspect"],"expected_exit_code":0,"expected_output_kind":"entity","expected_accounting_mode":"self_reported","required_fields":["item.id"]}]},{"id":"closed-domain-recovery","description":"Reject an invalid context intent and execute the advertised shell-free retry.","steps":[{"id":"refuse-intent","args":["get","$ANCHOR_ID","--for","invalid-agent-intent"],"expected_exit_code":2,"expected_output_kind":"refusal","expected_accounting_mode":"self_reported","required_fields":["code","refusal","recovery"],"expected_error_code":"unknown_context_intent","expected_field_values":{"recovery.recovery_mode":"compact"},"expected_refusal_surface":"--for"},{"id":"retry-intent","args":["get","$ANCHOR_ID","--for","inspect"],"expected_exit_code":0,"expected_output_kind":"entity","expected_accounting_mode":"self_reported","required_fields":["item.id"],"recovery_for":"refuse-intent"}]},{"id":"unknown-option-recovery","description":"Identify an unsupported option after valid flags and continue with the corrected command.","steps":[{"id":"refuse-option","args":["search","agent task","--status","open","--limit","5","--include-body"],"expected_exit_code":2,"expected_output_kind":"refusal","expected_accounting_mode":"self_reported","required_fields":["code","refusal","recovery"],"expected_error_code":"unknown_option","expected_refusal_surface":"--include-body"},{"id":"retry-option","args":["search","agent task","--status","open","--limit","5"],"expected_exit_code":0,"expected_output_kind":"collection","expected_accounting_mode":"self_reported","required_fields":["items"],"recovery_for":"refuse-option"}]},{"id":"lifecycle-mutation","description":"Create, inspect, close, and confirm a project item through public CLI receipts.","steps":[{"id":"create","args":["create","--id","$LIFECYCLE_ID","--title","Transcript lifecycle item","--description","Golden multi-step lifecycle task","--type","Task","--status","open","--create-mode","progressive"],"expected_exit_code":0,"expected_output_kind":"mutation_receipt","expected_accounting_mode":"self_reported","required_fields":["id","changed_field_count"]},{"id":"inspect-open","args":["get","$LIFECYCLE_ID","--for","inspect"],"expected_exit_code":0,"expected_output_kind":"entity","expected_accounting_mode":"self_reported","required_fields":["item.id","item.status"],"expected_field_values":{"item.status":"open"}},{"id":"close","args":["close","$LIFECYCLE_ID","Golden task completed"],"expected_exit_code":0,"expected_output_kind":"mutation_receipt","expected_accounting_mode":"self_reported","required_fields":["id","status","close_reason","completion.timestamp","completion.source","completion.hint"],"expected_field_values":{"completion.source":"close_time"}},{"id":"inspect-closed","args":["get","$LIFECYCLE_ID","--for","inspect"],"expected_exit_code":0,"expected_output_kind":"entity","expected_accounting_mode":"self_reported","required_fields":["item.id","item.status"],"expected_field_values":{"item.status":"closed"}}]},{"id":"bulk-effect-outcomes","description":"Preserve successful partial-effect and no-effect outcomes across a bulk lifecycle task.","steps":[{"id":"create-bulk-target","args":["create","--id","$BULK_ID","--title","Transcript bulk effect target","--description","Golden bulk outcome transcript target","--type","Task","--status","open","--create-mode","progressive"],"expected_exit_code":0,"expected_output_kind":"mutation_receipt","expected_accounting_mode":"self_reported","required_fields":["id","status","changed_field_count"]},{"id":"partial-effect","args":["close-many","--ids","$BULK_ID,pm-transcript-missing","--reason","Golden partial-effect transcript","--validate-close","off","--no-checkpoint"],"expected_exit_code":7,"expected_output_kind":"collection","expected_accounting_mode":"self_reported","required_fields":["rows","outcome","exit_code","rows.0.completion.timestamp","rows.0.completion.source","rows.0.completion.hint"],"expected_field_values":{"outcome":"partial_effect","rows.0.completion.source":"close_time"}},{"id":"no-effect","args":["close-many","--ids","$BULK_ID","--reason","Golden no-effect transcript","--validate-close","off","--no-checkpoint"],"expected_exit_code":6,"expected_output_kind":"collection","expected_accounting_mode":"self_reported","required_fields":["rows","outcome","exit_code"],"expected_field_values":{"outcome":"no_effect"}}]},{"id":"plan-execution-mutations","description":"Create a Plan, add and complete a step, then inspect its durable evidence without echoing the full Plan on each mutation.","steps":[{"id":"create-plan","args":["create","--id","pm-transcript-plan","--type","Plan","--title","Transcript execution Plan","--create-mode","progressive"],"expected_exit_code":0,"expected_output_kind":"mutation_receipt","expected_accounting_mode":"self_reported","required_fields":["id","status"]},{"id":"add-step","args":["plan","add-step","pm-transcript-plan","--step-title","Verify result","--step-body","Durable execution context retained for later inspection."],"expected_exit_code":0,"expected_output_kind":"diagnostic","expected_accounting_mode":"self_reported","required_fields":["id","step.id","steps_summary.total","inspection_command"],"expected_field_values":{"kind":"plan_mutation","steps_summary.total":1}},{"id":"complete-step","args":["plan","complete-step","pm-transcript-plan","plan-step-001","--step-evidence","Verified result"],"expected_exit_code":0,"expected_output_kind":"diagnostic","expected_accounting_mode":"self_reported","required_fields":["id","step.status","steps_summary.completed","omission_receipt"],"expected_field_values":{"step.status":"completed","steps_summary.completed":1}},{"id":"inspect-plan","args":["plan","show","pm-transcript-plan","--depth","deep"],"expected_exit_code":0,"expected_output_kind":"diagnostic","expected_accounting_mode":"self_reported","required_fields":["plan.steps","plan.steps_summary.completed"],"expected_field_values":{"plan.steps_summary.completed":1}}]}]}