pm-github 2026.10.24 → 2026.10.26

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 2026.10.25 - 2026-10-25
+
+### Fixed
+
+- Hold ambiguous merged-PR delivery until attribution is verified ([pm-github-closeout-attribution](https://github.com/unbraind/pm-github/blob/main/.agents/pm/issues/pm-github-closeout-attribution.toon))
+
 ## 2026.10.24 - 2026-10-24
 
 ### Fixed

package/README.md

@@ -48,17 +48,41 @@ PR body, including links in follow-up lists (`PM:`), can produce `not_delivery`
 rows for otherwise eligible items with the reason "Mentioned, not delivered".
 Tracker PR URL metadata with no body reference or declaration produces no row.
 
-When several merged PRs declare delivery, closeout selects the latest merge with
-complete merge facts and passing head checks. Equal merge times use the higher
-PR number. Other qualifying claims receive `duplicate_selection`; mention-only
-PRs retain `not_delivery`. All completion fields and the appended close event use
-the selected PR's merge time, merge SHA, head SHA and check evidence.
+A merged PR is a delivery candidate only when it claims the item through an explicit
+`delivery-pr:` tag, a closing declaration, or a commit claim naming the item.
+A fully inspected mention-only or link-only PR is context: it remains listed as
+`skip` / `not_delivery`, never enters the candidate set, and its merge/check gaps
+cannot hold another delivery. Unreadable PR or commit evidence remains unresolved
+because it may hide a claim; a known candidate's incomplete evidence still holds.
+
+Closeout never breaks a delivery tie by PR number or merge order. Prefer one explicit
+item tag linking the delivery PR, for example:
+
+```sh
+pm update pm-x --add-tags delivery-pr:https://github.com/example/project/pull/19
+```
+
+The tagged PR must be in the selected PR set and pass the merge and head-check gates.
+Ordinary `pr_url` metadata remains contextual. Without an explicit tag, exactly one
+linked merged PR must declare the item in its description or commit messages and
+merge strictly after the last acceptance-criteria edit in the item's SDK history.
+Creation is the cutoff when no later criteria edit exists; comments and unrelated
+updates do not move it. Missing or unverifiable history cannot establish chronology.
+Unreadable commits on an otherwise qualifying mention also hold selection: they may hide another claim. A failed check on the unique PR never permits fallback to an earlier delivery.
+
+Unresolved attribution produces `needs_review` rows listing every linked candidate
+PR number, leaving the item and its history unchanged. Multiple or unmatched explicit
+tags also require review. The reusable workflow includes these rows and candidates
+in the closeout PR body. An all-held run proposes only the privacy-gated
+`closeout-review.json` report in the tracker, so it can still open a review PR.
+All completion fields and the appended close event use the selected PR's merge
+time, merge SHA, head SHA and check evidence.
 
 **A mention is not delivery.** PR bodies routinely link follow-ups, epics and
 related work for context, so a link alone never closes an item. An item is
 closed only when:
 
-- its delivery is explicitly declared; a canonical link may be preceded on the same
+- its delivery is selected by an explicit item tag or a unique claim after the last criteria edit; a canonical link may be preceded on the same
   line by a GitHub-style closing keyword: `Closes`, `Fixes`, `Resolves` or
   `Delivers` (and their tense forms), for example `- Closes [pm-x](…/pm-x.toon)`;
 - it is not an `Epic`; epics close when their children are done;
@@ -163,10 +187,96 @@ for missed deliveries or unavailable webhooks. Back up the ignored durable
 [CLI and typed SDK example](docs/webhook-inbox.md) for deployment, crash recovery,
 retention and supported-event details.
 
+## Issue-form completion contracts
+
+`pm github form` reads one explicitly selected repository issue form through the
+GitHub Contents API. It compiles requirements before export; it never writes to
+GitHub or changes an item. Select a revision explicitly (prefer a commit SHA for
+reproducibility). Requirements follow [GitHub's form schema](https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/syntax-for-githubs-form-schema).
+
+```sh
+pm github form --repo unbraind/pm-cli \
+  --form .github/ISSUE_TEMPLATE/feature-request.yml --form-ref main \
+  --form-bindings docs/issue-form-bindings.json --compile --json
+
+pm github form --repo unbraind/pm-cli \
+  --form .github/ISSUE_TEMPLATE/feature-request.yml --form-ref main \
+  --item pm-123 --form-bindings docs/issue-form-bindings.json \
+  --form-answers docs/issue-form-answers.json --json
+
+pm github export --repo unbraind/pm-cli --ids pm-123 \
+  --form .github/ISSUE_TEMPLATE/feature-request.yml --form-ref main \
+  --form-bindings docs/issue-form-bindings.json \
+  --form-answers docs/issue-form-answers.json --dry-run --json
+```
+
+The [bindings example](docs/issue-form-bindings.json) maps form IDs to current
+native item fields; the [answers example](docs/issue-form-answers.json) supplies
+the dropdown selection. Explicit answers override bindings. Native text fields
+(including custom fields) and string arrays are read through the SDK, without
+coercion. Numbers, objects and nested arrays refuse as answers. Status bindings
+are literal text; this feature does not infer lifecycle meaning. Required text
+must contain non-whitespace content. Text supports `required` and `min_length`
+(Unicode code points, after CRLF/CR normalization); dropdowns support `required`,
+exact option membership, uniqueness and single/multiple selection. Defaults and
+placeholders do not count as confirmed answers. Markdown elements are display
+context and are omitted from the issue body. Fields without IDs use `field-N`,
+where N is their one-based position in the form body.
+
+IDs accept Unicode letters/numbers, `_` and `-` (1..100 characters). Names such as
+`toString`, `constructor`, `__proto__`, `hasOwnProperty` and `valueOf` are ordinary
+IDs, choices and binding names. Answer and binding maps preserve every own key;
+inherited properties never supply answers or defaults. Invalid answer objects
+refuse by value shape, without rejecting these names or changing prototypes.
+
+Unknown keys, validators or element types refuse explicitly as `unsupported_form`.
+This includes checkboxes, uploads, rendered/code textareas, dropdown defaults,
+assignees, project routing and issue types. Duplicate IDs, labels or options
+also refuse. The supported top-level keys are `name`, `description`, `title`,
+`labels`, and `body`; `title` is a UI preset and the native pm title remains the
+exported title. Form labels augment exported labels. Missing/invalid answers
+produce `incomplete_answers`, exit 2, and **one** checklist of at most 20 repairs
+plus an omitted count. A batch validates all selected items before any POST or
+PATCH, so one incomplete item yields zero remote writes. Pass the same form
+flags to `export --apply` only after reviewing the preview. Without `--form`,
+export retains its existing behavior. This does not repair export identity,
+retry or idempotency defects, and a form check is not an approval for later use.
+
+Normal form output is compact host-rendered TOON (`--json` selects JSON): contract,
+binding names, counts and repair evidence, without item contents or answer values.
+`--compile` returns the contract even before answers are supplied. Limits are
+128 KiB YAML/JSON files; 100 elements, map entries or choices; 200 characters per
+label/choice; 32,768 characters per answer; `min_length` 0..32,768; 64 KiB UTF-8
+rendered issue body. Arrays must be dense and numeric validators finite integers.
+Input and output size refusals use `invalid_form_input`; inaccessible forms and
+items use `form_unavailable` and `item_unavailable`. Remedies use the host SDK's
+structured error context (`nextSteps` and `why`).
+
+The typed SDK exports `IssueFormInput`, `IssueFormContract`, `IssueFormReport`,
+`IssueFormRefusalCode`, `compileIssueForm(input)`,
+`completeIssueForm(pmRoot, input)` and `readRepositoryIssueForm(selection, reader, apiBase)`:
+
+```ts
+import { completeIssueForm, type IssueFormInput } from "pm-github";
+
+const input: IssueFormInput = {
+  repo: "owner/repo", ref: "commit-sha", path: ".github/ISSUE_TEMPLATE/bug.yml",
+  yaml: selectedRepositoryFormYaml,
+  item: "pm-123", bindings: { problem: "description" },
+  answers: { version: "stable" },
+};
+const { report, body } = await completeIssueForm(pmRoot, input);
+// report.ok is completion evidence for this read; body is the validated export text.
+```
+
+There are no saved plans, leases, idempotency keys, or retries in the completion
+adapter. Every call re-reads native state, and the semantic form digest is only
+a source identifier. Imports and sync do not use this opt-in export adapter.
+
 ## Without git
 
 With an explicit repository, GitHub import, export, refresh, sync, project commands,
-blocker checks, closeout and webhook receive/reconcile work in a plain pm tracker
+blocker checks, issue-form compilation/completion, closeout and webhook receive/reconcile work in a plain pm tracker
 without a git executable.
 `pm github identity` also works there, entirely offline and without credentials.
 The provider commands still require their normal GitHub access and credentials. Privacy scanning
@@ -176,6 +286,14 @@ Gated imports (`github import --gate`, including the scheduled sync workflow)
 also require a git repository so the proposed publication can be checked. They
 refuse before writing when the tracker is outside one; plain imports still work.
 
+Import lifecycle finalization uses the pm SDK's item mutation boundary, retaining
+GitHub source dates and both import write hooks. Tracker ownership, workflow,
+history-stream and transactional extension guards now apply to these writes too;
+a refusal leaves the item and history unchanged. The SDK supplies missing-item
+diagnostics (not-found exit code 3), maintains its derived index, and uses its
+native TOON storage format when updating legacy documents.
+See [SDK adoption evidence](docs/sdk-adoption-1025.md).
+
 ## Revalidate GitHub blockers
 
 **Compatibility:** pm-github now requires PM CLI 2026.10.5 or newer for complete

package/dist/closeout.d.ts

@@ -11,12 +11,18 @@ export interface CloseoutApi {
 export interface CloseoutRow {
     item: string;
     pr: number;
-    action: "close" | "skip";
+    action: "close" | "skip" | "needs_review";
+    candidates?: number[];
+    missing_evidence?: {
+        pr: number;
+        code: CloseoutCode;
+        reason: string;
+    }[];
     reason: string;
     code: CloseoutCode;
 }
 /** Stable decisions used by automation and compact skip counts. */
-export type CloseoutCode = "already_terminal" | "other_repository" | "duplicate_selection" | "explicit_skip" | "unknown_item" | "epic" | "active_children" | "not_delivery" | "close_failed" | "head_checks_passed" | "head_checks_failed" | "head_evidence_unavailable" | "required_checks_unverified" | "incomplete_merge";
+export type CloseoutCode = "already_terminal" | "other_repository" | "duplicate_selection" | "explicit_skip" | "needs_review" | "unknown_item" | "epic" | "active_children" | "not_delivery" | "close_failed" | "head_checks_passed" | "head_checks_failed" | "head_evidence_unavailable" | "required_checks_unverified" | "not_merged" | "incomplete_merge";
 /** Which head-check policy was evaluated for one selected pull request. */
 interface CheckGate {
     pr: number;
@@ -30,9 +36,10 @@ interface CheckGate {
 interface PullRequest {
     number: number;
     body: string | null;
-    merged: boolean;
+    merged: boolean | null;
     merged_at: string | null;
     merge_commit_sha: string | null;
+    commits?: number | null;
     html_url: string;
     head: {
         sha: string;
@@ -76,8 +83,10 @@ export declare class CloseoutUsageError extends Error {
  * may pass on neutral or skipped runs alone, so it states that policy and lists successful checks only when any exist.
  */
 export declare function checkEvidence(gate: CheckGate): string;
-/** Plan all selected PRs before closing eligible items through the real SDK. */
-export declare function runCloseout(pmRoot: string, repo: string | undefined, options: Record<string, unknown>, api: CloseoutApi): Promise<{
+/** Deterministic scheduling observer; it never replaces SDK reads or writes. */
+export type CloseoutObserver = (boundary: "listed" | "snapshot" | "history" | "selection" | "before_close" | "locked") => Promise<void>;
+/** Plan selected PRs and apply only decisions whose exact item snapshot still matches. */
+export declare function runCloseout(pmRoot: string, repo: string | undefined, options: Record<string, unknown>, api: CloseoutApi, observer?: CloseoutObserver): Promise<{
     command: string;
     repo: string;
     dry_run: boolean;
@@ -96,6 +105,12 @@ export declare function compactCloseoutReport(report: Awaited<ReturnType<typeof
     plan: {
         item: string;
         pr: number;
+        candidates?: number[];
+        missing_evidence?: {
+            pr: number;
+            code: CloseoutCode;
+            reason: string;
+        }[];
         reason: string;
         code: CloseoutCode;
         action: string;

package/dist/closeout.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"closeout.d.ts","sourceRoot":"","sources":["../closeout.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"closeout.d.ts","sourceRoot":"","sources":["../closeout.ts"],"names":[],"mappings":"AAIA,6EAA6E;AAC7E,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACjE,IAAI,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;CACzC;AAED,gFAAgF;AAChF,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,OAAO,GAAG,MAAM,GAAG,cAAc,CAAC;IAC1C,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,gBAAgB,CAAC,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,YAAY,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IACxE,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,YAAY,CAAC;CACpB;AAED,mEAAmE;AACnE,MAAM,MAAM,YAAY,GAAG,kBAAkB,GAAG,kBAAkB,GAAG,qBAAqB,GAAG,eAAe,GACxG,cAAc,GAAG,cAAc,GAAG,MAAM,GAAG,iBAAiB,GAAG,cAAc,GAAG,cAAc,GAC9F,oBAAoB,GAAG,oBAAoB,GAAG,2BAA2B,GAAG,4BAA4B,GAAG,YAAY,GAAG,kBAAkB,CAAC;AAEjJ,2EAA2E;AAC3E,UAAU,SAAS;IACjB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,YAAY,CAAC;IACnB,IAAI,EAAE,UAAU,GAAG,UAAU,GAAG,UAAU,GAAG,aAAa,CAAC;IAC3D,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,EAAE,EAAE,OAAO,CAAC;CACb;AAED,iFAAiF;AACjF,UAAU,WAAW;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,MAAM,EAAE,OAAO,GAAG,IAAI,CAAC;IACvB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE;QAAE,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC;IACtB,IAAI,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE;YAAE,SAAS,EAAE,MAAM,CAAA;SAAE,CAAA;KAAE,CAAC;CACpD;AAuKD,oGAAoG;AACpG,wBAAsB,iBAAiB,CAAC,GAAG,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,WAAW,EAAE,QAAQ,GAAE,MAAM,EAAO,GAAG,OAAO,CAAC,SAAS,CAAC,CA0DpI;AAoBD;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,SAAK,GAAG,OAAO,CAwBrE;AAED,+FAA+F;AAC/F,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,OAAO,CAAA;CAAE,EAAE,CAyBtG;AAkDD,4FAA4F;AAC5F,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAO5D;AAED,sHAAsH;AACtH,qBAAa,kBAAmB,SAAQ,KAAK;CAAG;AAOhD;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,SAAS,GAAG,MAAM,CAMrD;AAqBD,gFAAgF;AAChF,MAAM,MAAM,gBAAgB,GAAG,CAAC,QAAQ,EAAE,QAAQ,GAAG,UAAU,GAAG,SAAS,GAAG,WAAW,GAAG,cAAc,GAAG,QAAQ,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;AAExI,0FAA0F;AAC1F,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,SAAS,EAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,WAAW,EAAE,QAAQ,CAAC,EAAE,gBAAgB;aAM1I,MAAM;UAAQ,MAAM;aAAW,OAAO;UAAQ,WAAW,EAAE;YAAU,SAAS,EAAE;YAAU,MAAM;YAAU,MAAM;GAJ1H;AAuPD,8FAA8F;AAC9F,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,OAAO,CAAC,UAAU,CAAC,OAAO,WAAW,CAAC,CAAC;aApP1E,MAAM;UAAQ,MAAM;aAAW,OAAO;YAAoD,MAAM;YAAU,MAAM;;cAvcnH,MAAM;YACR,MAAM;qBAEG,MAAM,EAAE;2BACF;YAAE,EAAE,EAAE,MAAM,CAAC;YAAC,IAAI,EAAE,YAAY,CAAC;YAAC,MAAM,EAAE,MAAM,CAAA;SAAE,EAAE;gBAC/D,MAAM;cACR,YAAY;;;;;EAisBnB"}