@unbrained/pm-cli 2026.10.10 → 2026.10.12

package/dist/sdk/test/update.d.ts

@@ -0,0 +1,55 @@
+import type { GlobalOptions } from "../../core/shared/command-types.js";
+import type { LinkedTest } from "../../types/index.js";
+import type { TestCommandOptions } from "./execution.js";
+/** Unambiguous selector evaluated against the current locked collection. */
+export type LinkedTestUpdateSelector = {
+    index: number;
+} | {
+    command: string;
+} | {
+    path: string;
+};
+/** Explicit metadata values; null removes an optional value without replacing other fields. */
+export type LinkedTestMetadataPatch = {
+    [K in keyof Omit<LinkedTest, "command" | "provenance" | "provenance_invalid" | "updated_by" | "updated_at">]?: K extends "scope" ? LinkedTest[K] : LinkedTest[K] | null;
+};
+/** One metadata revision with ordinary mutation ownership and history controls. */
+export interface UpdateLinkedTestOptions {
+    /** Current entry identity or one-based list position. */
+    selector: LinkedTestUpdateSelector;
+    /** Fields to change; command and provenance cannot be replaced. */
+    patch: LinkedTestMetadataPatch;
+    /** Explicit author override, otherwise the configured or detected identity. */
+    author?: string;
+    /** Explanation retained on the single history event. */
+    message?: string;
+    /** Explicit ownership override. */
+    force?: boolean;
+}
+/** Receipt identifying the edited entry and semantically changed metadata. */
+export interface UpdateLinkedTestResult {
+    /** Successful mutation or unchanged retry. */
+    ok: true;
+    /** Owning item ID. */
+    id: string;
+    /** Current ordered linked-test collection. */
+    tests: LinkedTest[];
+    /** Whether authoritative state changed. */
+    changed: boolean;
+    /** Current collection size. */
+    count: number;
+    /** One-based position of the selected entry. */
+    updated_index: number;
+    /** Explicit metadata keys whose normalized values changed. */
+    updated_fields: string[];
+}
+/** Resolve transport edit flags without accepting ambiguous selectors or implicit replacement. */
+export declare function parseLinkedTestUpdateOptions(options: {
+    update?: string;
+    updateIndex?: string | number;
+    setJson?: string;
+}): Pick<UpdateLinkedTestOptions, "selector" | "patch"> | undefined;
+/** Keep metadata editing a separate atomic operation from execution or other collection changes. */
+export declare function assertLinkedTestEditUsage(options: TestCommandOptions): void;
+/** Patch one linked-test entry atomically, keeping ordering and original command provenance. */
+export declare function updateLinkedTest(id: string, options: UpdateLinkedTestOptions, global?: GlobalOptions): Promise<UpdateLinkedTestResult>;

package/dist/sdk/test/update.js

@@ -0,0 +1,2 @@
+(function(){try{var e=typeof window<"u"?window:typeof global<"u"?global:typeof globalThis<"u"?globalThis:typeof self<"u"?self:{},n=new e.Error().stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="cfcc5f4f-caf0-5a2e-8a9d-219c3afb5d2d")}catch{}})();import{getActiveExtensionRegistrations}from"../../core/extensions/index.js";import{resolveItemTypeRegistry}from"../../core/item/type-registry.js";import{normalizeLinkedTest}from"../../core/item/item-format.js";import{parseOnlyIndexValue}from"../../core/test/run-selectors.js";import{resolveAuthor}from"../../core/shared/author.js";import{EXIT_CODE}from"../../core/shared/constants.js";import{PmCliError}from"../../core/shared/errors.js";import{stableValueEquals}from"../../core/shared/serialization.js";import{nowIso}from"../../core/shared/time.js";import{mutateItemWithHistoryContextResolver}from"../../core/store/item-store.js";import{resolvePmRoot}from"../../core/store/paths.js";import{readSettings}from"../../core/store/settings.js";import{assertInitializedTracker}from"../environment/tracker-preflight.js";import{assertLinkedTestContext,STRUCTURED_LINKED_TEST_KEYS}from"./entry.js";import{parseLinkedTestJsonEntries}from"./parsers.js";function parseLinkedTestUpdateOptions(options){if(options.update===void 0&&options.updateIndex===void 0&&options.setJson===void 0)return;if(options.update===void 0==(options.updateIndex===void 0)||options.setJson===void 0)throw new PmCliError("Use exactly one --update or --update-index with --set-json",EXIT_CODE.USAGE);let patch;try{patch=JSON.parse(options.setJson)}catch{throw new PmCliError("--set-json must contain a JSON object with explicit linked-test metadata fields",EXIT_CODE.USAGE)}if(options.updateIndex!==void 0)return{selector:{index:parseOnlyIndexValue(options.updateIndex,"--update-index")},patch};const value=options.update,prefix=/^(command|path)=/u.exec(value);return{selector:prefix?.[1]==="path"?{path:value.slice(prefix[0].length)}:{command:prefix?value.slice(prefix[0].length):value},patch}}function assertLinkedTestEditUsage(options){if([options.list,options.run,options.progress,options.timeout!==void 0,options.acknowledgeLinkedTests,options.metricBelow!==void 0,options.metricDiff!==void 0,(options.add?.length??0)>0,(options.addJson?.length??0)>0,(options.remove?.length??0)>0,(options.removeIndex?.length??0)>0].some(Boolean))throw new PmCliError("Edit linked-test metadata separately from listing, additions, removals, execution options, metric filters and trust acknowledgement",EXIT_CODE.USAGE)}function selectIndex(tests,selector){if(typeof selector!="object"||selector===null||Array.isArray(selector))throw new PmCliError("Select one linked test by index, command, or path",EXIT_CODE.USAGE);const keys=Object.keys(selector);if(keys.length!==1||!["index","command","path"].includes(keys[0]))throw new PmCliError("Select one linked test by index, command, or path",EXIT_CODE.USAGE);if("index"in selector){const index=parseOnlyIndexValue(selector.index,"--update-index");if(index<=tests.length)return index-1}else{const key="command"in selector?"command":"path",value="command"in selector?selector.command:selector.path;if(typeof value!="string"||value.trim().length===0)throw new PmCliError("Linked-test selector must be a non-empty command or path",EXIT_CODE.USAGE);const matches=tests.flatMap((test,index)=>test[key]===value?[index]:[]);if(matches.length===1)return matches[0];if(matches.length>1)throw new PmCliError(`Linked-test selector is ambiguous; matching indexes: ${matches.map(index=>index+1).join(", ")}`,EXIT_CODE.USAGE,{code:"linked_test_update_ambiguous",required:"List linked tests and select one current --update-index."})}throw new PmCliError("No linked test matched the update selector",EXIT_CODE.NOT_FOUND,{code:"linked_test_update_no_match",required:"List linked tests and select a current command, path, or --update-index."})}function applyPatch(test,patch){if(typeof patch!="object"||patch===null||Array.isArray(patch))throw new PmCliError("Linked-test metadata patch must be a JSON object",EXIT_CODE.USAGE);const keys=Object.keys(patch);if(keys.length===0||keys.some(key=>!STRUCTURED_LINKED_TEST_KEYS.includes(key)||["command","cmd","timeout"].includes(key)))throw new PmCliError("Patch explicit linked-test metadata fields; command, aliases and provenance cannot be edited",EXIT_CODE.USAGE);if(patch.scope===null)throw new PmCliError("scope is required and cannot be cleared",EXIT_CODE.USAGE);const metadata=Object.fromEntries(Object.entries(test).filter(([key])=>STRUCTURED_LINKED_TEST_KEYS.includes(key))),parsed=normalizeLinkedTest(parseLinkedTestJsonEntries(JSON.stringify({...metadata,command:test.command??"legacy-path-only",...Object.fromEntries(Object.entries(patch).map(([key,value])=>[key,value===null?void 0:value]))}),"--set-json")[0]);assertLinkedTestContext(parsed);const fields=keys.filter(key=>!stableValueEquals(test[key],parsed[key])),next={...test};for(const key of fields){const value=parsed[key];Object.assign(next,{[key]:value}),value===void 0&&delete next[key]}if(!next.command?.trim()&&!next.path?.trim())throw new PmCliError("Linked-test entry must retain a command or path",EXIT_CODE.USAGE);return{test:next,fields}}async function updateLinkedTest(id,options,global2={}){const pmRoot=resolvePmRoot(process.cwd(),global2.path);await assertInitializedTracker(pmRoot);const settings=await readSettings(pmRoot),author=resolveAuthor(options.author,settings.author_default),typeRegistry=resolveItemTypeRegistry(settings,getActiveExtensionRegistrations());let updatedIndex=0,updatedFields=[];const result=await mutateItemWithHistoryContextResolver({pmRoot,settings,id,author,op:"tests_update",message:options.message,force:options.force,skipNoop:!0,typeToFolder:typeRegistry.type_to_folder,resolveHistoryContext:()=>({linked_test_update:{index:updatedIndex,fields:updatedFields}}),mutate(document){const tests2=document.metadata.tests??[],index=selectIndex(tests2,options.selector),patch=applyPatch(tests2[index],options.patch);return updatedIndex=index+1,updatedFields=patch.fields,patch.fields.length===0?{changedFields:[]}:(document.metadata.tests=tests2.map((test,position)=>position===index?{...patch.test,updated_by:author,updated_at:nowIso()}:test),{changedFields:["tests"]})}}),tests=result.item.tests;return{ok:!0,id:result.item.id,tests,count:tests.length,changed:result.changedFields.length>0,updated_index:updatedIndex,updated_fields:updatedFields}}export{assertLinkedTestEditUsage,parseLinkedTestUpdateOptions,updateLinkedTest};
+//# sourceMappingURL=update.js.map

package/dist/types.d.ts

@@ -195,6 +195,10 @@ export interface LinkedTest {
     provenance?: LinkedTestProvenance;
     /** Explicit fail-closed marker retained when stored provenance is malformed. */
     provenance_invalid?: true;
+    /** Author of the most recent explicit metadata edit; creation provenance is retained. */
+    updated_by?: string;
+    /** ISO timestamp of the most recent explicit metadata edit. */
+    updated_at?: string;
     /** Value that configures or reports env set for this contract. */
     env_set?: Record<string, string>;
     /** Value that configures or reports env clear for this contract. */

package/dist/types.js

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

package/docs/LINKED_TEST_EDITS.md

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

package/docs/RELEASE_LEDGER_RECONCILIATION.md

@@ -0,0 +1,148 @@
+# Full-history release reconciliation
+
+Owner: [pm-q91qyd](../.agents/pm/issues/pm-q91qyd.toon).
+Upstream trigger evidence: [pm-prrlce](../.agents/pm/issues/pm-prrlce.toon).
+
+The Release Reliability workflow compares every dated section in the
+package-generated changelog, every release tag advertised by `origin`, and
+every version in anonymous public npm metadata. It runs on the existing daily
+schedule and completion triggers, even when a rolling reliability report fails.
+Its separate `release-ledgers-<run>-<attempt>` artifact contains the complete
+input inventories, counts, findings and exception dispositions for offline replay.
+
+Missing public registry versions are declared-but-undelivered releases. Missing
+changelog sections are delivered-but-undocumented releases. A tag missing its
+section is tagged-but-unsectioned; an identity can belong to several classes.
+Every missing ledger appears explicitly in the report, without counting one
+identity several times or dropping overlapping classes.
+The `classes` object names these three populations separately; `findings`
+retains one row per discrepant identity.
+
+The first complete census on 2026-10-10 found 14 discrepant identities among
+143 sections, 151 tags and 143 public versions. The exact historical signatures
+and their individual dispositions are recorded in
+[the reviewed exception policy](../config/release-ledger-exceptions.json).
+Unpublished historical preparations are retained as abandoned publications;
+historical documentation gaps remain visible without inventing shipped content.
+These are explicit exceptions, not claims that the three historical sets agree.
+No tag is deleted and no old artifact is published by this reporting path.
+
+An exception matches one identity and one exact missing-ledger signature.
+Additional missing evidence invalidates it. Correcting a historical gap makes
+its exception stale and requires removing or revising that policy entry in a
+reviewed change. A new discrepancy or stale exception fails the report.
+Empty total inventories, incomplete populations, duplicate identities, malformed
+remote output, registry failures and missing exception evidence refuse evaluation.
+
+The registry request uses the same public npm metadata surface as release
+acceptance, with explicit public registry selection, empty user/global
+configuration and a fresh temporary cache. It runs outside the checkout and
+removes inherited npm authentication/configuration. The report never archives
+credentials, command output or environment values.
+On Windows the collector invokes `cmd.exe` explicitly for npm's `.cmd` launcher.
+The package name must satisfy the restricted registry identity grammar before
+any child starts; the remaining arguments are fixed. Required Windows acceptance
+executes real Git and public npm requests from paths containing spaces and `&`,
+first proves that direct `npm.cmd` execution fails, then verifies the complete
+inventory and temporary-directory cleanup through the repaired launcher.
+No `shell: true` argument-array fallback or resource ceiling increase is used.
+The parser supports npm 11's object and npm 12's single-result array, with
+[captured public npm 12 metadata](../tests/fixtures/release-ledgers/npm-view-12.json)
+as its format regression. Multiple package results refuse evaluation.
+
+To run the actual collector after building:
+
+```bash
+RELEASE_LEDGERS_OUTPUT=/absolute/report.json node --input-type=module -e '
+  import { main } from "./scripts/release/collect-release-ledgers.mjs";
+  const report = main();
+  console.log(JSON.stringify({ok:report.ok,counts:report.counts,findings:report.findings}));
+  process.exitCode = report.ok ? 0 : 1;
+'
+```
+
+Packages and non-release projects can use the same pure SDK primitive with
+their own named artifact inventories and decision references:
+
+```ts
+import { reconcileArtifactLedgers } from "@unbrained/pm-cli/sdk/governance";
+
+const report = reconcileArtifactLedgers([
+  { name: "declared", complete: true, identities: ["artifact-1"] },
+  { name: "delivered", complete: true, identities: ["artifact-1"] },
+]);
+```
+
+`ArtifactLedgerSnapshot`, `ArtifactLedgerException`, `ArtifactLedgerFinding`
+and `ArtifactLedgerReport` describe this harness-independent contract.
+The evaluator performs no filesystem, clock or network operations and preserves
+caller inputs. For offline replay, feed the saved `snapshots` and `exceptions`
+back into `reconcileArtifactLedgers`.
+
+## Tag-carried trigger declarations
+
+New preparations create annotated tags whose bounded JSON message binds the
+declared upstream event/origin, repository, run/attempt, reviewed source commit
+and prepared target commit. Before publication, the Release workflow checks
+the tag's peeled commit and source ancestry and compares the source declaration
+with the exact GitHub run attempt, including repository, event, source SHA,
+the producer workflow path and declared Auto Release run name. It independently
+fetches the repository's default branch and requires the source run's branch to
+match it. Auto Release uploads an immutable producer binding before pushing;
+publication independently downloads that run attempt's artifact and compares
+the exact tag name, target commit, tag object and canonical declaration. Missing,
+expired, ambiguous or mismatched evidence stops publication; the artifact is
+retained for 90 days. The verifier never assumes the default branch is named
+`main`.
+
+The separate `release-publication-origin-<run>-<attempt>` artifact retains the
+tag-object SHA, upstream declaration, independent verification result and the
+current publication/recovery trigger. An operator recovering a dispatcher
+release therefore retains both origins. A rejected atomic push after sealing
+refuses to rebase into a different target; a new preparation must establish a
+new independent binding. Local preparation remains supported without pushing;
+local `--push` refuses before Git inspection or release-asset mutation.
+
+Historical lightweight tags and unrelated legacy annotations stay explicitly
+unattributed only when publication matches the repository, tag name and exact
+content-addressed object in the
+[frozen pre-rollout inventory](../config/release-tag-legacy.json). That reviewed
+inventory identifies all 152 origin tag objects observed before this rollout;
+it is not extended automatically. Unknown lightweight tags, unrelated new
+annotations and rewritten historical objects stop before publication, including
+operator recovery. A missing or unreadable inventory fails closed. No origin is
+inferred from a tag-push event or actor. Local preparation records an operator
+declaration but hosted publication refuses it without a hosted producer.
+Tag objects are content-addressed evidence; this does not assert that GitHub
+release/tag immutability policy has been enabled.
+
+The downstream tag-push workflow's run name still names `tag_push`; its verified
+upstream origin lives in the summary and artifact. The remaining run-name and
+operator-only manual follow-up contracts retain their existing owners
+[pm-prrlce](../.agents/pm/issues/pm-prrlce.toon) and
+[pm-uenmu9](../.agents/pm/issues/pm-uenmu9.toon). The one-automatic-release-per-UTC-day
+guard and exact-tag recovery semantics are unchanged.
+
+## Installed acceptance path cost
+
+Owner: [pm-release-acceptance-path-cost](../.agents/pm/issues/pm-release-acceptance-path-cost.toon).
+
+The disposable installed-consumer layout uses concise directory names because
+`init` repeats its workspace path throughout its complete JSON guidance. Long
+macOS temporary ancestry previously made an otherwise valid public artifact
+exceed the raw 12,000-character init ceiling. Shorter private paths retain every
+output field, lifecycle assertion, deadline and ceiling. The
+[captured public output regression](../tests/fixtures/release-acceptance/README.md)
+checks the raw cost for independent control/candidate local npm, global npm and
+Bun layouts; actual installed sessions remain separate acceptance evidence.
+
+## Publication metadata weight
+
+Owner: [pm-998juj](../.agents/pm/tasks/pm-998juj.toon).
+
+The publication stage compacts first-party JSON while leaving checkout files
+readable and third-party runtime files unchanged. Every parsed value must survive
+serialization exactly; invalid JSON and lossy representations, including negative
+zero or overflowing numbers, stop packing. Real tarball regressions verify nested
+extension data, Unicode, escaped text and the runtime ledger. Both committed size
+profiles, required files and source-map exclusions remain enforced.

package/docs/RELEASE_RELIABILITY.md

@@ -34,6 +34,10 @@ by release preparation, not the inferred cron occurrence. A delayed run cannot
 backdate a tag. Reporting never creates, retargets, retries, or publishes a tag.
 The unchanged [release recovery rules](RELEASING.md#failure-handling) apply.
 
+The independent [full-history ledger report](RELEASE_LEDGER_RECONCILIATION.md)
+also reconciles public registry versions, release tags and generated sections.
+It preserves every historical exception and fails on new or changed drift.
+
 ## Evidence and denominator
 
 The collector paginates Auto Release runs over an explicit half-open UTC window

package/docs/RELEASING.md

@@ -148,8 +148,13 @@ configuration belong in private operator documentation.
 - protected-branch pushes require `RELEASE_PAT`; Auto Release fails fast before the expensive release gates when `push=true`, `dry_run=false`, and that secret is not configured
 - release reliability gating requires `SENTRY_PERSONAL_ADMIN_TOKEN` for issue-threshold checks; Auto Release fails before creating the version commit/tag when the token is missing and `push=true`, while sourcemap upload remains optional through `SENTRY_AUTH_TOKEN`
 - after creating and pushing a new tag, auto-release waits for the tag-push `.github/workflows/release.yml` run to finish instead of dispatching a second publish workflow
-- scheduled failure issues include the preflight state (`push`, `dry_run`, `release_pat_configured`, and `sentry_personal_admin_token_configured`) plus a detected cause so agents can distinguish missing release secrets from Sentry gate failures without scanning the full workflow log first
-- when scheduled failures continue across multiple UTC days, auto-release supersedes a stale open blocker with a fresh current-day blocker so same-day retry detection follows the latest scheduled failure
+- native scheduled and declared morning-dispatcher failures open or update the
+  same daily blocker with trigger origin, preflight state (`push`, `dry_run`,
+  `release_pat_configured`, and `sentry_personal_admin_token_configured`) and
+  detected cause. Successful automatic recovery closes it only after exact
+  publication verification; operator dispatch does not manage this lifecycle.
+  This behavior is tracked by [pm-automatic-release-alerts](../.agents/pm/tasks/pm-automatic-release-alerts.toon).
+- when either automatic origin fails across multiple UTC days, auto-release supersedes a stale open blocker with a fresh current-day blocker so same-day retry detection follows the latest automatic failure
 - closing the exact bot-created `Auto Release blocked: scheduled run failed`
   issue as a maintainer or agent records a same-day retry marker, then either
   retries preparation when no tag exists or watches an active exact-tag Release
@@ -172,6 +177,17 @@ Pipeline entrypoint:
 node scripts/release/run-release-pipeline.mjs
 ```
 
+Tracked by [pm-prrlce](../.agents/pm/issues/pm-prrlce.toon): hosted preparation
+uses `--push --defer-push` to write an exact producer binding. Auto Release uploads
+`release-producer-binding-<attempt>` before verifying and atomically pushing its
+prepared refs. Publication independently fetches the verified run's artifact and
+compares the tag name, target commit, tag object and declaration. Missing, expired,
+ambiguous or mismatched evidence fails closed; artifact retention is 90 days.
+A branch advance after sealing refuses publication rather than rebasing into a
+different target. Local `--push` refuses before Git inspection or asset mutation;
+local preparation without pushing remains supported. Historical admission remains
+limited to the reviewed exact-object inventory.
+
 The pipeline performs:
 
 1. change detection + one-release-per-day guard
@@ -421,14 +437,28 @@ maintainer supplies
 pair that acknowledgement with migration guidance, compatible extension
 version bounds where applicable, and the next eligible date-based release.
 
-5. Push branch and tag after local green.
+5. Land the implementation through a reviewed pull request, then use hosted
+   preparation for publication.
+
+Local preparation without `--push` is a diagnostic preview. Its local producer
+declaration cannot authorize publication. Once the reviewed implementation is on
+`main`, dispatch the existing Auto Release workflow from that default branch:
 
 ```bash
-git push origin main
-git tag v<version>
-git push origin v<version>
+gh workflow run auto-release.yml --ref main \
+  -f push=true -f dry_run=false -f telemetry_mode=off -f trigger_origin=operator
 ```
 
+Hosted preparation runs the mandatory gates, creates the version commit and
+annotated tag, and seals their exact producer binding in an immutable artifact
+before verifying and atomically pushing either ref. It waits for the single
+tag-driven Release workflow to publish and accept that exact package. Do not push
+locally prepared tags or invoke `npm publish` separately.
+
+If today's immutable tag already exists, use the exact-tag recovery procedure
+below. A local diagnostic tag does not prove hosted preparation or publication;
+never move a published tag or mint a second automatic version for the same UTC day.
+
 ## GitHub Workflow
 
 `.github/workflows/release.yml` runs on `v*.*.*` tags and handles:
@@ -454,7 +484,11 @@ git push origin v<version>
 - a base npm pack dry run, optional Sentry debug-ID injection, a second
   `sentry-injected` packlist budget over the exact publishable bytes, and only
   then optional Sentry release metadata/upload/finalization and the npx tarball
-  smoke test
+  smoke test. Sentry release metadata and sourcemaps are uploaded only from
+  tag sources. Recovery of an already-published version from reviewed `main`
+  preserves that version's existing Sentry commits and sourcemaps; local debug-ID
+  injection still validates the candidate artifact budget without changing the
+  published release's symbolication data.
 - generated release notes from changelog plus sanitized tracker metadata. The
   tracker read projects only release-relevant fields and explicitly removes row
   and token limits. The generator validates the completeness receipt before
@@ -563,12 +597,18 @@ Use the npm registry package for maintainer global updates. Do not use `npm inst
   ordinal recovery version. Rerun `.github/workflows/release.yml` with
   `workflow_dispatch` and `tag=v<version>` (or close the current bot-created
   blocker once to trigger the guarded exact-run recovery). The workflow skips
-  duplicate npm publication for an anonymously visible version. Before
-  installing or running gates, dispatch performs an isolated anonymous
-  exact-version probe. An
-  existing version keeps the reviewed dispatch-time `main` source and cannot
-  be republished. A definitive missing-version response pins the checkout to
-  the existing immutable tag, reapplies the version guard, installs the managed
+  npm publication for a version visible to its isolated anonymous probe, keeping
+  reviewed dispatch-time `main`. A definitive missing-version response can pin
+  source to the immutable tag only after admission reads complete workflow and
+  job inventories, validates totals and unique identities, and checks matching
+  attempts. Prior successful `Publish to npm` evidence refuses
+  publication while metadata is unavailable: acceptance can precede visibility.
+  Unavailable, malformed, incomplete or inconsistent evidence also refuses it.
+  Only the executing attempt is excluded; its earlier attempts remain checked.
+  This admission check also runs before first publication, using reviewed
+  controls retained outside recovery checkout. Push and dispatch publishers
+  share exact-tag concurrency. See [pm-publication-acceptance-fence](../.agents/pm/issues/pm-publication-acceptance-fence.toon).
+  A never-published tag then reapplies the version guard, installs the managed
   changelog extension, regenerates the package changelog with the tagged
   checkout's canonical policy under a tracked-path mutation guard, and permits
   first publication only from that tagged source. Ordinary tag-push releases