pm-brief 2026.10.21 → 2026.10.23

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## 2026.10.23 - 2026-10-23
+
+### Changed
+
+- Enable the gated GitHub issue sync ([pm-brief-gp5o](https://github.com/unbraind/pm-brief/blob/main/.agents/pm/chores/pm-brief-gp5o.toon))
+- Adopt pm-github 2026.10.16: default-branch-safe gated sync and daily gated closeout PRs ([pm-brief-b7dy](https://github.com/unbraind/pm-brief/blob/main/.agents/pm/chores/pm-brief-b7dy.toon))
+
+### Fixed
+
+- The publish-attestation gate misses a publish routed through an unquoted shell variable ([pm-brief-tai3](https://github.com/unbraind/pm-brief/blob/main/.agents/pm/issues/pm-brief-tai3.toon))
+- The release job authenticated with a stored npm token that expired, so publishing stopped while every other gate stayed green ([pm-brief-s83v](https://github.com/unbraind/pm-brief/blob/main/.agents/pm/issues/pm-brief-s83v.toon))
+- A release run bumped and committed a new version every night while publishing was impossible, because the only externally-failable step runs last ([pm-brief-4ohy](https://github.com/unbraind/pm-brief/blob/main/.agents/pm/issues/pm-brief-4ohy.toon))
+
+### Other
+
+- Enable GitHub CodeQL code scanning ([pm-brief-1p5o](https://github.com/unbraind/pm-brief/blob/main/.agents/pm/chores/pm-brief-1p5o.toon))
+
 ## 2026.10.21 - 2026-10-21
 
 ### Fixed

package/README.md

@@ -47,6 +47,7 @@ pm brief since 2026-07-20T00:00:00Z --until 2026-07-22 --author alice
 - `pm brief since <checkpoint>` renders a delta brief of what changed since a checkpoint.
 - `pm brief diverge [base]` previews pm item collisions between two branches **before** merging.
 - `pm brief duplicates` sweeps the merged tracker for near-duplicate items the create-time advisory cannot see across branches.
+- `pm brief alternatives <id> <id> [more ids]` compares recorded proposals, outcomes and evidence with exact citations and no recommendation.
 
 ### Ranking and Budget Flags
 
@@ -410,3 +411,161 @@ compaction. Command-local selection limits and document budgets still apply.
    trackers: projection, budget omission, every-row cursor recovery, and writer
    rejection. Remove only the declarations, rebuild, and prove the tests fail.
 5. Run unchanged npm and Bun release gates and document their exact results.
+
+## Acknowledged handoff contracts
+
+`pm brief handoff` records what each receiving agent understood against exact
+item content revisions. A packet includes explicit questions, unresolved
+assumptions, required evidence and the transitive declared blocker closure.
+A changed blocker, source item or evidence item invalidates its old receipts.
+Two receivers append independent receipts to the same tracker; identical retries
+by the same author add nothing. Claims continue to own work ownership.
+
+```sh
+# Set an explicit identity for each sender or receiver.
+export PM_AUTHOR=sender
+# Replace the focus/evidence item ids in docs/examples/handoff.json.
+pm brief handoff preview --input docs/examples/handoff.json --json
+pm brief handoff create --input docs/examples/handoff.json --json
+# Save the returned id and digest. Then write response.json, as shown below.
+PM_AUTHOR=receiver-a pm brief handoff ack <packet-id> --input response.json --json
+pm brief handoff show <packet-id> --receiver receiver-a
+```
+
+A receiver supplies every obligation id, including evidence that is still missing:
+
+```json
+{
+  "digest": "<64-character digest from the packet>",
+  "questions": { "fixture": "I will use the public tracker fixture." },
+  "assumptions": { "review": "Unresolved; I will verify the blocker before proceeding." },
+  "evidence": { "report": "The report link is missing; validation remains outstanding." }
+}
+```
+
+Every collection is explicit; use `[]` in contracts and `{}` in responses when
+there are no obligations. Each input collection has at most 32 entries; the
+blocker/evidence closure has at most 64 items. Keys use ASCII letters, digits,
+dots, underscores or hyphens and start with a letter or digit. Obligation and actor
+keys have at most 128 characters; native item identifiers retain their full length. Obligation text and evidence references have at most 2,000 code units.
+Native source titles and blocker references retain their full text under the aggregate budget.
+Native TOON is the default; `--json` uses the host's
+structured JSON output. The default conservative output ceiling is 4,000 tokens,
+measured from UTF-8 bytes with twice pretty-JSON size plus framing headroom.
+`--token-budget` accepts up to 64,000. Oversized output refuses with a remedy;
+it never silently drops questions, assumptions, evidence or receiver receipts.
+A receiver filter reduces the selected receipt set without changing storage.
+Universal host output controls can intentionally project or paginate read commands;
+retain their omission receipts and use normal output for a complete contract.
+
+Evidence requirements select exact native `docs`, `files` or `tests` links by
+`item`, `kind` and `ref` (path, or test command). `missingEvidence` remains visible
+in the packet and each receipt. Linkage proves a reference was recorded; it does
+not prove that a file exists, its contents are correct, or a test passed. Receiver
+statements are self-reported understanding, including disagreement or uncertainty.
+`valid` means the source revisions still match; `ready` additionally means all
+required links are present. Neither field grants approval or claims the work.
+
+Packets are native Decision items tagged `pm-brief-handoff`; their JSON bodies are
+immutable protocol artifacts. Receipts are append-only native comments protected
+by the host's comment lock and author/text idempotency. Native lock contention
+is retried up to three times for reads and idempotent appends; creates are never
+automatically retried. Persistent contention refuses with a retry remedy. Do not edit contract bodies
+or receipt comments. Create a fresh packet after a revision changes. A receipt
+racing a source edit is reassessed on return and every subsequent read. All source
+metadata, bodies and linked evidence contribute to content revisions, so even an
+unrelated source comment conservatively invalidates old understanding. Reads are
+certified full-corpus snapshots, not a transaction spanning arbitrary source writers.
+
+The SDK exports `previewHandoff`, `createHandoff`, `acknowledgeHandoff`,
+`inspectHandoff`, their typed contracts, and `HandoffError` (`code`, `remedy`).
+Pass `{ pmRoot, author, tokenBudget? }`, optionally with the active native `PmClient`.
+CLI expected refusals exit 2 (3 for a stale packet), with a stable `handoff_<code>`
+JSON category and a `required` remedy.
+Categories cover invalid input, identity, missing packets/items, response coverage,
+integrity, budget and tracker reads. Validation and budget checks precede writes.
+The commands never change source items or claims; `preview` and `show` are read-only.
+
+This complements [pm-context](https://github.com/unbraind/pm-context)'s
+context delivery/usage receipts and the [since-delta candidate](https://github.com/unbraind/pm-context/pull/164)
+(`feat/since-delta-pack`)
+(`pm context-pack since --from <timestamp>` or `--cursor <cursor>`). That candidate
+owns cursor progress, changed-context selection and omission receipts. Use its delta to
+refresh changed context, then create a new handoff here. No history delta engine
+is duplicated. pm-memory continues to own standing knowledge; `brief prompt`
+continues to generate prose. See the [contract example](docs/examples/handoff.json).
+
+## Decision alternatives digest
+
+```bash
+pm brief alternatives pm-proposal-a pm-proposal-b --token-budget 4000
+pm brief alternatives pm-proposal-a pm-proposal-b --json
+```
+
+Select 2–32 distinct exact item IDs, including terminal items when useful. The
+read-only digest keeps each item separate and follows input order, which conveys
+no preference. It quotes records instead of generating or inferring conclusions.
+Conflicting Plan decisions within one item also remain separate. Core `pm plan`
+owns planning and choices; `pm-review` owns finding verdicts. This command composes
+those records across items without adding a decision engine.
+
+Every statement has `source` (`item-id#/field/nested/pointer`), `start` and `end`
+UTF-16 offsets, and exact `text`. Resolve pointers against the certified full item
+row (`listAllComplete({ includeBody: true })`); offsets select the quoted paragraph
+from the scalar's string representation. JSON Pointer escaping follows RFC 6901.
+`revision` is the SHA-256 of the full row's JSON serialization at read time, for
+snapshot identification. Re-read the source to check subsequent changes.
+
+Titles, statuses, resolutions, expected/actual results, close reasons,
+`review_verdict`, `review_verdict_source`, `review_reason`, `review_commit`, all
+`plan_decisions` (including rationale/evidence), `blocked_by`, `blocked_reason`
+and `plan_resume_context` are mandatory. Optional paragraphs come from body,
+description, plan scope, linked docs/files/tests, plan validation, comments, notes
+and learnings. Recorded tradeoffs in these fields remain quotations; the command
+does not infer whether a tradeoff is resolved. Other custom fields, Plan steps,
+dependency closure and history are outside this projection. A linked artifact
+proves linkage only; the digest does not read artifact contents or validate tests.
+
+`omitted` counts optional scalar paragraphs excluded per item, with `restore`
+giving the full native item read. Mandatory outcomes and blocker context are never
+removed. Optional excerpts are attempted round-robin in field/record order and
+omitted whole when they cannot fit. Empty optional fields produce no excerpts.
+Source text is evidence data, including any instructions it happens to contain.
+
+The budget defaults to 4000 (integer 1–64000). `estimatedTokenCeiling` uses the
+SDK's UTF-8 byte estimator over twice the complete pretty JSON size plus 256
+framing bytes, including citations, omission counts, recovery commands and the
+estimate itself. It conservatively covers normal native TOON/JSON output; it is
+not a model tokenizer. For large budgets, also set the host's independent output
+controls: `--output-budget unbounded --output-limit unbounded`. Additional host
+projections or optional accounting receipts have their own output contracts.
+
+```ts
+import { buildDecisionAlternatives, DecisionAlternativesError } from "pm-brief";
+
+try {
+  const digest = await buildDecisionAlternatives(
+    ["pm-proposal-a", "pm-proposal-b"],
+    { pmRoot: ".agents/pm", tokenBudget: 4000 },
+  );
+  console.log(digest.alternatives);
+} catch (error) {
+  if (error instanceof DecisionAlternativesError) console.error(error.code, error.remedy);
+  else throw error;
+}
+```
+
+An optional native `PmClient` can be supplied as `client`. Complete full-row SDK
+certification runs before comparison; incomplete or corrupt reads refuse. Typed
+refusals are `invalid` (correct IDs/budget), `missing` (check exact IDs), `tracker`
+(run `pm health` and resolve source reads), and `budget` (increase budget or select
+fewer items). CLI refusals exit 2 and retain `alternatives_<code>` and a remedy in
+the host's expected-error contract. See the [worked example](docs/examples/alternatives.md).
+
+## Without git
+
+Briefs, prompts, ranking, history deltas, governance, duplicate checks and all
+handoff and decision alternatives commands work in plain initialized trackers without a git executable.
+Handoff storage uses the native SDK dispatcher and can reuse a host client.
+`brief diverge` needs a git repository and git refs. Handoff receipts have no
+branch, commit or repository dependency.

package/dist/alternatives.d.ts

@@ -0,0 +1,45 @@
+import { PmClient } from "@unbrained/pm-cli/sdk";
+import type { ExtensionApi } from "@unbrained/pm-cli/sdk/authoring";
+/** Exact recorded text with an item-relative JSON Pointer and UTF-16 range. */
+export interface DecisionExcerpt {
+    source: string;
+    start: number;
+    end: number;
+    text: string;
+}
+/** One proposal remains independent, including all recorded outcomes and blockers. */
+export interface DecisionAlternative {
+    id: string;
+    revision: string;
+    statements: DecisionExcerpt[];
+    omitted: number;
+    restore: string;
+}
+/** Extractive comparison; ordering follows the caller and never implies preference. */
+export interface DecisionAlternativesDigest {
+    protocol: "pm-brief.alternatives/v1";
+    alternatives: DecisionAlternative[];
+    estimatedTokenCeiling: number;
+}
+/** Backend-neutral read context; injected native clients retain the active host dispatcher. */
+export interface DecisionAlternativesOptions {
+    pmRoot: string;
+    client?: PmClient;
+    tokenBudget?: number;
+}
+/** Stable expected failure categories for SDK consumers. */
+export type DecisionAlternativesRefusalCode = "invalid" | "missing" | "tracker" | "budget";
+/** Typed refusal with a recovery action, never an empty successful comparison. */
+export declare class DecisionAlternativesError extends Error {
+    /** Machine-readable failure category. */
+    readonly code: DecisionAlternativesRefusalCode;
+    /** Concrete correction to perform before retrying. */
+    readonly remedy: string;
+    /** Retain machine and human recovery information independently. */
+    constructor(code: DecisionAlternativesRefusalCode, message: string, remedy: string);
+}
+/** Compare explicitly selected native records read-only; never recommend, merge outcomes or invoke git. */
+export declare function buildDecisionAlternatives(ids: string[], options: DecisionAlternativesOptions): Promise<DecisionAlternativesDigest>;
+/** Register a native structured command so host TOON/JSON and error contracts remain authoritative. */
+export declare function registerDecisionAlternativesCommand(api: ExtensionApi): void;
+//# sourceMappingURL=alternatives.d.ts.map

package/dist/alternatives.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"alternatives.d.ts","sourceRoot":"","sources":["../alternatives.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,QAAQ,EAA+E,MAAM,uBAAuB,CAAC;AAE9H,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iCAAiC,CAAC;AAEpE,+EAA+E;AAC/E,MAAM,WAAW,eAAe;IAAG,MAAM,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE;AAC7F,sFAAsF;AACtF,MAAM,WAAW,mBAAmB;IAClC,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,eAAe,EAAE,CAAC;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;CACjB;AACD,uFAAuF;AACvF,MAAM,WAAW,0BAA0B;IACzC,QAAQ,EAAE,0BAA0B,CAAC;IACrC,YAAY,EAAE,mBAAmB,EAAE,CAAC;IACpC,qBAAqB,EAAE,MAAM,CAAC;CAC/B;AACD,+FAA+F;AAC/F,MAAM,WAAW,2BAA2B;IAAG,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,QAAQ,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAA;CAAE;AACxG,4DAA4D;AAC5D,MAAM,MAAM,+BAA+B,GAAG,SAAS,GAAG,SAAS,GAAG,SAAS,GAAG,QAAQ,CAAC;AAC3F,kFAAkF;AAClF,qBAAa,yBAA0B,SAAQ,KAAK;IAClD,yCAAyC;IACzC,QAAQ,CAAC,IAAI,EAAE,+BAA+B,CAAC;IAC/C,sDAAsD;IACtD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,mEAAmE;IACnE,YAAY,IAAI,EAAE,+BAA+B,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAEjF;CACF;AA0BD,2GAA2G;AAC3G,wBAAsB,yBAAyB,CAAC,GAAG,EAAE,MAAM,EAAE,EAAE,OAAO,EAAE,2BAA2B,GAAG,OAAO,CAAC,0BAA0B,CAAC,CA4BxI;AAED,uGAAuG;AACvG,wBAAgB,mCAAmC,CAAC,GAAG,EAAE,YAAY,GAAG,IAAI,CAc3E"}

package/dist/alternatives.js

@@ -0,0 +1,103 @@
+import { createHash } from "node:crypto";
+import { PmClient, certifyCompleteListResult, createPmCliExpectedError, estimatePmOutputTokens } from "@unbrained/pm-cli/sdk";
+/** Typed refusal with a recovery action, never an empty successful comparison. */
+export class DecisionAlternativesError extends Error {
+    /** Machine-readable failure category. */
+    code;
+    /** Concrete correction to perform before retrying. */
+    remedy;
+    /** Retain machine and human recovery information independently. */
+    constructor(code, message, remedy) {
+        super(message);
+        this.name = "DecisionAlternativesError";
+        this.code = code;
+        this.remedy = remedy;
+    }
+}
+const REQUIRED = ["title", "status", "resolution", "expected_result", "actual_result", "close_reason", "review_verdict", "review_verdict_source", "review_reason", "review_commit", "plan_decisions", "blocked_by", "blocked_reason", "plan_resume_context"];
+const OPTIONAL = ["body", "description", "plan_scope", "docs", "files", "tests", "plan_validation", "comments", "notes", "learnings"];
+/** Reject malformed agent selection before reading a tracker. */
+function validate(ids, budget) {
+    if (!Array.isArray(ids) || ids.length < 2 || ids.length > 32 || new Set(ids).size !== ids.length || ids.some(id => typeof id !== "string" || !/^[a-zA-Z0-9][a-zA-Z0-9._-]*$/.test(id)) || !Number.isSafeInteger(budget) || budget < 1 || budget > 64000) {
+        throw new DecisionAlternativesError("invalid", "Invalid alternative selection or token budget", "Supply 2-32 distinct exact item ids and an integer --token-budget from 1 to 64000 (default 4000)");
+    }
+}
+/** Walk recorded JSON values without inventing summaries or dropping conflicting entries. */
+function excerpts(value, source) {
+    if (value === null || value === undefined || value === "")
+        return [];
+    if (Array.isArray(value))
+        return value.flatMap((entry, i) => excerpts(entry, `${source}/${i}`));
+    if (typeof value === "object")
+        return Object.entries(value).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0).flatMap(([key, entry]) => excerpts(entry, `${source}/${key.replace(/~/g, "~0").replace(/\//g, "~1")}`));
+    const text = String(value);
+    // Whole paragraphs preserve complete recorded sentences, including punctuation.
+    return [...text.matchAll(/[^\r\n]+(?:\r?\n(?!\s*\r?\n)[^\r\n]+)*/g)].map(match => ({ source, start: match.index, end: match.index + match[0].length, text: match[0] }));
+}
+/** Measure citations, omission counts, recovery commands and framing with the native estimator. */
+function measure(digest) {
+    digest.estimatedTokenCeiling = 64000;
+    digest.estimatedTokenCeiling = estimatePmOutputTokens(Buffer.byteLength(JSON.stringify(digest, null, 2)) * 2 + 256);
+    return digest.estimatedTokenCeiling;
+}
+/** Compare explicitly selected native records read-only; never recommend, merge outcomes or invoke git. */
+export async function buildDecisionAlternatives(ids, options) {
+    const budget = options.tokenBudget ?? 4000;
+    validate(ids, budget);
+    let items;
+    try {
+        const client = options.client ?? new PmClient({ pmRoot: options.pmRoot, noExtensions: true });
+        items = certifyCompleteListResult(await client.listAllComplete({ includeBody: true })).items;
+    }
+    catch {
+        throw new DecisionAlternativesError("tracker", "Cannot certify the tracker snapshot", "Run pm health and resolve unreadable or incomplete records before retrying");
+    }
+    const rows = new Map(items.map(item => [item.id, item]));
+    if (ids.some(id => !rows.has(id)))
+        throw new DecisionAlternativesError("missing", "A selected alternative does not exist", "Check the exact ids with pm list --all --full; no alternative is silently removed");
+    const optional = [];
+    const alternatives = ids.map(id => {
+        const item = rows.get(id);
+        const extra = OPTIONAL.flatMap(field => excerpts(item[field], `${id}#/${field}`));
+        optional.push(extra);
+        return { id, revision: createHash("sha256").update(JSON.stringify(item)).digest("hex"), statements: REQUIRED.flatMap(field => excerpts(item[field], `${id}#/${field}`)), omitted: extra.length, restore: `pm get ${id} --json --output-budget unbounded --output-limit unbounded` };
+    });
+    const digest = { protocol: "pm-brief.alternatives/v1", alternatives, estimatedTokenCeiling: 0 };
+    if (measure(digest) > budget)
+        throw new DecisionAlternativesError("budget", "Mandatory alternative context exceeds the token budget", "Increase --token-budget (maximum 64000) or compare fewer items; titles, statuses, outcomes and blocker context are never dropped");
+    // Round-robin optional excerpts give each proposal context without ranking it.
+    const longest = Math.max(...optional.map(rows => rows.length));
+    for (let i = 0; i < longest; i++)
+        for (let j = 0; j < alternatives.length; j++) {
+            const excerpt = optional[j][i];
+            if (!excerpt)
+                continue;
+            const alternative = alternatives[j];
+            alternative.statements.push(excerpt);
+            alternative.omitted--;
+            if (measure(digest) > budget) {
+                alternative.statements.pop();
+                alternative.omitted++;
+            }
+        }
+    measure(digest);
+    return digest;
+}
+/** Register a native structured command so host TOON/JSON and error contracts remain authoritative. */
+export function registerDecisionAlternativesCommand(api) {
+    api.registerCommand({
+        name: "brief alternatives",
+        description: "Compare recorded proposals and evidence with citations, without picking a winner",
+        flags: [{ long: "--token-budget", type: "string", value_name: "n", description: "Conservative TOON/JSON token ceiling including citations and omissions (default 4000, maximum 64000)" }],
+        async run(ctx) {
+            try {
+                return await buildDecisionAlternatives(ctx.args, { pmRoot: ctx.pm_root, client: ctx.sdk?.client, tokenBudget: ctx.options.tokenBudget === undefined ? undefined : Number(ctx.options.tokenBudget) });
+            }
+            catch (error) {
+                const refusal = error instanceof DecisionAlternativesError ? error : new DecisionAlternativesError("tracker", "Alternative comparison could not complete", "Run pm health and check tracker permissions before retrying");
+                throw createPmCliExpectedError(`alternatives ${refusal.code}: ${refusal.message}. Remedy: ${refusal.remedy}`, { exitCode: 2, context: { code: `alternatives_${refusal.code}`, required: refusal.remedy } });
+            }
+        },
+    });
+}
+//# sourceMappingURL=alternatives.js.map

package/dist/alternatives.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"alternatives.js","sourceRoot":"","sources":["../alternatives.ts"],"names":[],"mappings":"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"}

package/dist/handoff.d.ts

@@ -0,0 +1,102 @@
+import { PmClient } from "@unbrained/pm-cli/sdk";
+import type { ExtensionApi } from "@unbrained/pm-cli/sdk/authoring";
+/** An explicit question or unresolved assumption with a stable response key. */
+export interface HandoffPrompt {
+    id: string;
+    text: string;
+}
+/** Required native tracker linkage; presence proves linkage, never artifact contents or test success. */
+export interface HandoffEvidence {
+    id: string;
+    item: string;
+    kind: "docs" | "files" | "tests";
+    ref: string;
+}
+/** Sender-authored obligations; every collection must be supplied, even when intentionally empty. */
+export interface HandoffContract {
+    focus: string[];
+    questions: HandoffPrompt[];
+    assumptions: HandoffPrompt[];
+    requiredEvidence: HandoffEvidence[];
+}
+/** Content-addressed full item revision, including transitive declared blockers and missing targets. */
+export interface HandoffRevision {
+    id: string;
+    revision: string | null;
+    title: string;
+    status: string;
+    blockers: string[];
+}
+/** Immutable stored contract; protocol and digest prevent accidental cross-packet acknowledgment. */
+export interface HandoffDocument extends HandoffContract {
+    protocol: "pm-brief.handoff/v1";
+    sender: string;
+    createdAt: string;
+    items: HandoffRevision[];
+}
+/** Transport packet with live missing-evidence disclosure and a conservative byte-based token ceiling. */
+export interface HandoffPacket {
+    id: string;
+    digest: string;
+    contract: HandoffDocument;
+    missingEvidence: string[];
+    estimatedTokenCeiling: number;
+}
+/** Receiver statements keyed by every question, assumption and evidence obligation. */
+export interface HandoffResponse {
+    digest: string;
+    questions: Record<string, string>;
+    assumptions: Record<string, string>;
+    evidence: Record<string, string>;
+}
+/** Read-only or native mutation context; no filesystem or git backend assumptions. */
+export interface HandoffOptions {
+    pmRoot: string;
+    author?: string;
+    client?: PmClient;
+    tokenBudget?: number;
+}
+/** Receipt validity is recomputed on each read; missing evidence cannot become a ready acknowledgment. */
+export interface HandoffReceipt {
+    id: string;
+    receiver: string;
+    response: HandoffResponse;
+    acknowledgedAt: string;
+    valid: boolean;
+    ready: boolean;
+    staleItems: string[];
+    missingEvidence: string[];
+}
+/** Complete contract and selected receiver receipts, with no silent row omission. */
+export interface HandoffStatus {
+    packet: HandoffPacket;
+    staleItems: string[];
+    receipts: HandoffReceipt[];
+    estimatedTokenCeiling: number;
+}
+/** Stable refusal categories callers can branch on without parsing prose. */
+export type HandoffRefusalCode = "invalid" | "missing" | "identity" | "stale" | "responses" | "integrity" | "budget" | "tracker";
+/** Expected failure with a concrete recovery action; tracker writes never precede validation. */
+export declare class HandoffError extends Error {
+    /** Machine-readable reason for refusing an operation. */
+    readonly code: HandoffRefusalCode;
+    /** Action the caller can take before retrying. */
+    readonly remedy: string;
+    /** Preserve the typed category separately from human-readable context. */
+    constructor(code: HandoffRefusalCode, message: string, remedy: string);
+}
+/** Validate and normalize the SDK and CLI contract through the same runtime boundary. */
+export declare function parseHandoffContract(value: unknown): HandoffContract;
+/** Parse explicit receiver statements; digest binds them to exactly one packet. */
+export declare function parseHandoffResponse(value: unknown): HandoffResponse;
+/** Generate a bounded packet from a certified tracker read without creating records or invoking git. */
+export declare function previewHandoff(input: HandoffContract, options: HandoffOptions): Promise<HandoffPacket>;
+/** Create one native Decision artifact; no source item or claim is modified. */
+export declare function createHandoff(input: HandoffContract, options: HandoffOptions): Promise<HandoffPacket>;
+/** Read all receipts and recompute validity; receiver filters affect output only, never stored data. */
+export declare function inspectHandoff(id: string, options: HandoffOptions, receiver?: string): Promise<HandoffStatus>;
+/** Append an idempotent receiver receipt under the native comment lock; concurrent receivers never overwrite. */
+export declare function acknowledgeHandoff(id: string, input: HandoffResponse, options: HandoffOptions): Promise<HandoffStatus>;
+/** Register native structured TOON/JSON commands; expected refusals carry code and remedy at nonzero exit. */
+export declare function registerHandoffCommands(api: ExtensionApi): void;
+//# sourceMappingURL=handoff.d.ts.map

package/dist/handoff.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handoff.d.ts","sourceRoot":"","sources":["../handoff.ts"],"names":[],"mappings":"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"}