pm-github 2026.10.16 → 2026.10.19

package/dist/index.js

@@ -14,13 +14,14 @@
 // Issues use the REST API; Projects v2 is GraphQL-only (see the Projects v2
 // section below and the pure plan/mapping logic in ./projects.ts).
 import { CloseoutUsageError, compactCloseoutReport, runCloseout } from "./closeout.js";
+import { buildImportFidelity, fetchImportTimeline, matchImportedIssue, persistImportFidelity, readImportReleases, selectImportContextIndex, } from "./import-fidelity.js";
 import http from "node:http";
 import https from "node:https";
 import crypto from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
 import { spawnSync } from "node:child_process";
-import { comments as pmCommentsFn, commitItemMutations as sdkCommitItemMutations, isExternalDependencyReference, listAllComplete, certifyCompleteListResult, listAllItemMetadata as sdkListAllItemMetadata, normalizeItemId as sdkNormalizeItemId, readSettings as sdkReadSettings, } from "@unbrained/pm-cli/sdk";
+import { comments as pmCommentsFn, commitItemMutations as sdkCommitItemMutations, isExternalDependencyReference, listAllComplete, certifyCompleteListResult, listAllItemMetadata as sdkListAllItemMetadata, normalizeItemId as sdkNormalizeItemId, readSettings as sdkReadSettings, resolvePmRoot as sdkResolvePmRoot, getHistoryPath as sdkGetHistoryPath, readHistorySnapshot as sdkReadHistorySnapshot, } from "@unbrained/pm-cli/sdk";
 import { collectNewOrderingCycleWarnings as sdkCollectNewOrderingCycleWarnings } from "@unbrained/pm-cli/sdk/graph";
 import { GateInputError, formatGateReport, runTrackerGate, resolvePmDataDir, } from "./gate.js";
 export { resolvePmDataDir } from "./gate.js";
@@ -356,7 +357,7 @@ export function parseNextLink(linkHeader) {
 // Map a GitHub issue/PR state (+ optional stateReason) onto a pm status,
 // preserving `not_planned` closures as `canceled` rather than `closed`.
 export function mapState(state, stateReason) {
-    if (state === "closed" && stateReason === "not_planned")
+    if (state === "closed" && (stateReason === "not_planned" || stateReason === "duplicate"))
         return "canceled";
     return state === "closed" ? "closed" : "open";
 }
@@ -718,6 +719,7 @@ export function decodeCompletePmItems(parsed) {
         }
         ids.add(item.id);
         items.push({
+            ...item,
             id: item.id,
             title,
             status,
@@ -924,8 +926,9 @@ async function resolveAtomicSdkFunctions(opts) {
  * Derive an order-independent transaction id from the desired import state and
  * exact ordered mutation plan. Content or target changes produce a fresh
  * transaction; a reordered retry of the same plan resumes the durable journal.
+ * External history revisions distinguish a local edit from a retry of import-owned writes.
  */
-export function deriveAtomicTransactionId(repo, entries, mutations) {
+export function deriveAtomicTransactionId(repo, entries, mutations, contextVersions = []) {
     const canonical = [...entries]
         .sort((a, b) => a.issueNumber - b.issueNumber)
         .map((entry) => ({
@@ -938,8 +941,10 @@ export function deriveAtomicTransactionId(repo, entries, mutations) {
         tags: [...entry.tags].sort(),
         assignee: entry.assignee ?? null,
         milestone: entry.milestone ?? null,
+        fidelity: entry.fidelity ?? null,
+        linkOnly: entry.linkOnly ?? false,
     }));
-    const digest = crypto
+    const payload = crypto
         .createHash("sha256")
         .update(repo.toLowerCase())
         .update("\x1f")
@@ -948,10 +953,10 @@ export function deriveAtomicTransactionId(repo, entries, mutations) {
         // Recovery requires the exact ordered step plan. Include targets and
         // options so a changed id_prefix or provenance match gets a fresh journal
         // instead of colliding with an incompatible prior attempt.
-        .update(JSON.stringify(mutations))
-        .digest("hex")
-        .slice(0, 16);
-    return `${ATOMIC_IMPORT_PREFIX}${digest}`;
+        .update(JSON.stringify(mutations));
+    if (contextVersions.length > 0)
+        payload.update("\x1f").update(JSON.stringify([...contextVersions].sort()));
+    return `${ATOMIC_IMPORT_PREFIX}${payload.digest("hex").slice(0, 16)}`;
 }
 /** Stable create id keyed by the external GitHub issue, never by fetch order. */
 export function deriveAtomicItemId(repo, issueNumber, idPrefix, normalizeItemId) {
@@ -964,6 +969,9 @@ export function deriveAtomicItemId(repo, issueNumber, idPrefix, normalizeItemId)
 }
 /** Map one rendered import entry to its reversible SDK mutation sequence. */
 export function buildAtomicImportMutations(repo, entry, idPrefix, normalizeItemId) {
+    if (entry.linkOnly && entry.match?.id) {
+        return { itemId: entry.match.id, mutations: [{ op: "update", id: entry.match.id, options: { addTags: entry.tags } }] };
+    }
     const sharedOptions = {
         title: entry.title,
         type: entry.itemType,
@@ -972,7 +980,14 @@ export function buildAtomicImportMutations(repo, entry, idPrefix, normalizeItemI
         tags: entry.tags.join(","),
         ...(entry.assignee ? { assignee: entry.assignee } : {}),
         ...(entry.milestone ? { sprint: entry.milestone } : {}),
+        ...(entry.status === "canceled" ? { closeReason: entry.fidelity?.github_close_reason ?? `GitHub issue #${entry.issueNumber} closed` } : {}),
     };
+    // Explicit terminal reconciliation also handles canceled -> completed. The
+    // supported force option permits that source-authoritative repeat closure;
+    // finalization restores the real dates before the transaction commits.
+    const statusOptions = entry.status === "closed"
+        ? entry.fidelity ? { status: "closed", closeReason: entry.fidelity.github_close_reason, force: true } : {}
+        : { status: entry.status };
     const managedItemId = deriveAtomicItemId(repo, entry.issueNumber, idPrefix, normalizeItemId);
     // A missing match and a match at our deterministic external-key id use the
     // SAME create+update upsert plan. This is essential for crash recovery: if a
@@ -985,21 +1000,21 @@ export function buildAtomicImportMutations(repo, entry, idPrefix, normalizeItemI
         const mutations = [{
                 op: "create",
                 id: managedItemId,
-                options: { ...sharedOptions, status: createStatus },
+                options: { ...sharedOptions, status: createStatus, message: `pm-github import create ${repo.toLowerCase()}#${entry.issueNumber}` },
             }, {
                 op: "update",
                 id: managedItemId,
                 options: {
                     ...sharedOptions,
-                    ...(entry.status !== "closed" ? { status: entry.status } : {}),
+                    ...statusOptions,
                 },
             }];
-        if (entry.status === "closed") {
+        if (entry.status === "closed" && !entry.fidelity) {
             mutations.push({
                 op: "close",
                 id: managedItemId,
                 reason: `GitHub issue #${entry.issueNumber} closed`,
-                // Preserve the source's real completion time instead of the import time.
+                // Legacy callers can supply completion directly; full plans finalize both lifecycle dates.
                 ...(entry.closedAt ? { options: { completedAt: entry.closedAt } } : {}),
             });
         }
@@ -1009,30 +1024,43 @@ export function buildAtomicImportMutations(repo, entry, idPrefix, normalizeItemI
         };
     }
     const itemId = entry.match.id;
-    const updateOptions = { ...sharedOptions };
-    // close has a dedicated mutation so its reason is preserved. Every other
-    // transition (open/reopen/canceled) is safely reversible as part of update.
-    if (entry.status !== "closed") {
-        updateOptions.status = entry.status;
-    }
+    const updateOptions = { ...sharedOptions, ...statusOptions };
     const mutations = [{
             op: "update",
             id: itemId,
             options: updateOptions,
         }];
-    if (entry.status === "closed") {
+    if (entry.status === "closed" && !entry.fidelity) {
         mutations.push({
             op: "close",
             id: itemId,
             reason: `GitHub issue #${entry.issueNumber} closed`,
-            // Preserve the source's real completion time instead of the import time.
+            // Legacy callers can supply completion directly; full plans finalize both lifecycle dates.
             ...(entry.closedAt ? { options: { completedAt: entry.closedAt } } : {}),
         });
     }
     return { itemId, mutations };
 }
+/**
+ * Bind atomic plans to the latest external edit or different lifecycle generation.
+ * The importer's desired-state and compensation writes leave retries stable;
+ * local edits and later state cycles invalidate completed journals.
+ */
+async function importContextVersions(pmRoot, entries) {
+    const versions = [];
+    for (const entry of entries) {
+        if (!entry.fidelity || !entry.match?.id)
+            continue;
+        const snapshot = await sdkReadHistorySnapshot(sdkGetHistoryPath(pmRoot, entry.match.id), entry.match.id);
+        const context = snapshot.entries[selectImportContextIndex(snapshot.entries, entry.status)];
+        if (context)
+            versions.push(`${entry.match.id}:${crypto.createHash("sha256").update(JSON.stringify(context)).digest("hex")}`);
+    }
+    return versions;
+}
 /** Commit a complete issue-import batch under one crash-resumable transaction. */
 export async function importGithubAtomic(pmRoot, repo, entries, opts = {}) {
+    pmRoot = sdkResolvePmRoot(process.cwd(), pmRoot);
     const { commitItemMutations: commit, normalizeItemId, readSettings, } = await resolveAtomicSdkFunctions(opts);
     let idPrefix = "pm-";
     try {
@@ -1054,7 +1082,15 @@ export async function importGithubAtomic(pmRoot, repo, entries, opts = {}) {
         itemIds.set(entry.issueNumber, planned.itemId);
         mutations.push(...planned.mutations);
     }
-    const transactionId = deriveAtomicTransactionId(repo, entries, mutations);
+    const transactionId = deriveAtomicTransactionId(repo, entries, mutations, await importContextVersions(pmRoot, entries));
+    /** Finalize before the SDK commits, and repair source metadata on recovered journals. */
+    const finalize = async () => {
+        for (const entry of entries) {
+            if (entry.fidelity)
+                await persistImportFidelity(pmRoot, itemIds.get(entry.issueNumber), entry.fidelity, Boolean(entry.linkOnly));
+        }
+    };
+    let committed = false;
     try {
         const result = await commit({
             pmRoot,
@@ -1066,7 +1102,14 @@ export async function importGithubAtomic(pmRoot, repo, entries, opts = {}) {
             // restores every UPDATE and CLOSE step (covered by the mixed rollback
             // integration test below this implementation).
             createCompensation: "delete",
+            onTransition: async (context) => {
+                if (context.transition === "committing")
+                    await finalize();
+                await opts.onTransition?.(context);
+            },
         });
+        committed = true;
+        await finalize();
         // A recovered journal may include work applied by the interrupted process
         // as well as steps resumed now. The SDK intentionally returns the durable
         // final results, not a per-invocation delta, so create/update counts cannot
@@ -1083,6 +1126,8 @@ export async function importGithubAtomic(pmRoot, repo, entries, opts = {}) {
     }
     catch (err) {
         const msg = errorMessage(err);
+        if (committed)
+            throw new CommandError(`Atomic GitHub import has a committed journal but source metadata could not be finalized. Retry transaction ${transactionId}; nothing may be pushed. Underlying error: ${msg}`);
         if (err instanceof AggregateError || /compensation failed/i.test(msg)) {
             throw new CommandError(`Atomic GitHub import failed and compensation was incomplete. The tracker may contain partially applied state; retry the same import to resume transaction ${transactionId}, then inspect its durable journal if recovery still fails. Underlying error: ${msg}`, EXIT_CODE.GENERIC_FAILURE);
         }
@@ -2177,10 +2222,17 @@ export async function linkImportedDependencies(repo, issues, pmRoot, deps = {})
  * @param fetchIssueComments - Injectable comment fetcher (defaults to {@link fetchComments}).
  * @returns The prepared import entry, or `undefined` when the issue has no title.
  */
-async function prepareGithubImport(issue, repo, opts, token, match, fetchIssueComments = fetchComments) {
+async function prepareGithubImport(issue, repo, opts, token, match, fetchIssueComments = fetchComments, fidelityContext) {
     const title = issue.title.trim();
     if (!title)
         return undefined;
+    const identity = matchImportedIssue(fidelityContext.items, issue, match);
+    match = identity.item;
+    const timeline = await fidelityContext.timeline(issue, repo, token);
+    const fidelity = buildImportFidelity(issue, fidelityContext.releases, timeline);
+    const targetStatus = mapState(issue.state, issue.state_reason);
+    const conflict = match?.status && match.status !== targetStatus && (["closed", "canceled"].includes(match.status) || issue.state === "closed")
+        ? { local: match.status, github: issue.state, rule: identity.linkOnly ? "preserve-provider-owner" : "github-source-wins" } : undefined;
     const kind = issue.pull_request ? "PR" : "issue";
     const labels = issue.labels.map((label) => label.name).filter(Boolean);
     const tag = provenanceTag(repo, issue.number);
@@ -2206,19 +2258,21 @@ async function prepareGithubImport(issue, repo, opts, token, match, fetchIssueCo
         issueNumber: issue.number,
         title,
         itemType: opts.itemType,
-        status: mapState(issue.state, issue.state_reason),
+        status: identity.linkOnly ? match.status : targetStatus,
         description: `GH ${kind} #${issue.number}: ${issue.html_url}` +
             (author ? ` · author @${author}` : "") +
             (issue.state_reason ? ` · state reason ${issue.state_reason}` : "") +
-            (issue.created_at ? ` · created ${issue.created_at}` : "") +
-            (issue.updated_at ? ` · updated ${issue.updated_at}` : ""),
+            ` · created ${issue.created_at} · updated ${issue.updated_at}`,
         body: writeCommentsToBody ? composeBody(issue, comments) : (issue.body || ""),
-        tags: [...labels, tag, ...(ghAuthorTag ? [ghAuthorTag] : [])],
+        tags: [...new Set([...(identity.linkOnly ? match.tags : []), ...labels, tag, ...(ghAuthorTag ? [ghAuthorTag] : [])])],
         assignee: issue.assignee?.login,
         milestone: issue.milestone?.title,
         comments,
         syncAnnotations,
         closedAt: issue.closed_at ?? undefined,
+        fidelity,
+        linkOnly: identity.linkOnly,
+        identity: { via: identity.via, ...(conflict ? { conflict } : {}) },
         match,
     };
 }
@@ -2455,8 +2509,17 @@ export async function runImport(repoArg, pmRoot, opts, dependencies = {}) {
     // reported "would import N, skip 0" where the real run performs updates for
     // already-linked issues. A preview that overstates creates reads as "this will
     // duplicate my whole tracker" and is the one thing --dry-run exists to rule out.
-    const existingItems = (dependencies.readItems ?? readPmItems)(pmRoot);
+    /** Read the complete raw corpus in-process, retaining all provider metadata and bodies. */
+    const readImportItems = async () => {
+        if (dependencies.readItems)
+            return dependencies.readItems(pmRoot);
+        const corpus = certifyCompleteListResult(await listAllComplete({ includeBody: true }, { pmRoot, cwd: pmRoot, noExtensions: true }));
+        return decodeCompletePmItems(corpus);
+    };
+    const existingItems = await readImportItems();
     const existing = indexByProvenance(existingItems);
+    const fidelityContext = { items: existingItems, releases: readImportReleases(pmRoot),
+        timeline: dependencies.fetchIssueTimeline ?? (dependencies.fetchIssues ? async () => [] : fetchImportTimeline) };
     let imported = 0;
     let updated = 0;
     let skipped = 0;
@@ -2477,7 +2540,7 @@ export async function runImport(repoArg, pmRoot, opts, dependencies = {}) {
         const planned = [];
         const skippedNumbers = [];
         for (const issue of filtered) {
-            const entry = await prepareGithubImport(issue, repo, opts, token, existing.get(`${repo.toLowerCase()}#${issue.number}`), dependencies.fetchIssueComments);
+            const entry = await prepareGithubImport(issue, repo, opts, token, existing.get(`${repo.toLowerCase()}#${issue.number}`), dependencies.fetchIssueComments, fidelityContext);
             if (!entry) {
                 skippedNumbers.push(issue.number);
                 continue;
@@ -2494,7 +2557,7 @@ export async function runImport(repoArg, pmRoot, opts, dependencies = {}) {
         if (opts.gate && !opts.dryRun) {
             const preview = runCommandTrackerGate({ pmRoot, plannedItems: planned.map(entry => ({
                     itemId: entry.match?.id ?? `github-issue-${entry.issueNumber}`,
-                    fields: { title: entry.title, description: entry.description, body: entry.body, tags: entry.tags,
+                    fields: { ...entry.fidelity, title: entry.title, description: entry.description, body: entry.body, tags: entry.tags,
                         assignee: entry.assignee, sprint: entry.milestone,
                         comments: entry.syncAnnotations ? entry.comments.map(comment => ({
                             author: comment.user?.login, text: comment.body, created_at: comment.created_at,
@@ -2507,7 +2570,21 @@ export async function runImport(repoArg, pmRoot, opts, dependencies = {}) {
             console.error(`pm github gate: plan verified — ${gateCompleteness.planned} planned, ${gateCompleteness.skipped} skipped, ` +
                 `${gateIdempotency.matched_by_provenance} matched by provenance, ${gateIdempotency.new_entries} new.`);
     }
-    const gatePlanFields = opts.gate ? { gate: { completeness: gateCompleteness, idempotency: gateIdempotency, scan: "post-write" } } : {};
+    // Preview output omits unscanned PR-title quotes and private provider close text.
+    const fidelityPlan = () => gatePlan.map(entry => {
+        const source = entry.fidelity;
+        const reason = source.github_close_reason.split(" (", 1)[0];
+        return { issue: entry.issueNumber, item: entry.match?.id,
+            action: entry.linkOnly ? "link" : entry.match?.id ? "update" : "create", status: entry.status,
+            ...source, github_close_reason: reason,
+            created_at: entry.linkOnly ? entry.match.created_at : source.github_created_at,
+            updated_at_policy: "sdk-mutation-clock; source in github_updated_at",
+            closed_at: entry.linkOnly ? entry.match.closed_at : source.github_closed_at,
+            close_reason: entry.linkOnly ? "preserved-provider-owner" : reason,
+            release: entry.linkOnly ? "preserved-provider-owner" : source.github_release,
+            identity: entry.identity };
+    });
+    const gatePlanFields = opts.gate ? { plan: fidelityPlan(), gate: { completeness: gateCompleteness, idempotency: gateIdempotency, scan: "post-write" } } : {};
     if (opts.atomic) {
         // The gated pipeline already prepared every entry (and counted its skips)
         // during the pre-mutation plan phase; reuse that plan verbatim so the write
@@ -2552,7 +2629,7 @@ export async function runImport(repoArg, pmRoot, opts, dependencies = {}) {
         }
         const result = await (dependencies.commitAtomic ?? importGithubAtomic)(pmRoot, repo, prepared);
         if (opts.gate)
-            verifyImportedProvenance((dependencies.readItems ?? readPmItems)(pmRoot), prepared, repo);
+            verifyImportedProvenance(await readImportItems(), prepared, repo);
         // Planned native comments are part of the verified plan: a contended lock,
         // a refused add, or a committed entry whose created id is missing from the
         // post-commit routing map all leave planned comments unwritten, so they are
@@ -2595,6 +2672,7 @@ export async function runImport(repoArg, pmRoot, opts, dependencies = {}) {
             atomic: true,
             ...depLinkResultFields(atomicDepLink),
             ...fetchFields,
+            ...(opts.gate ? { plan: fidelityPlan() } : {}),
             ...(gateReceipt ? { gate: gateReceipt } : {}),
         };
     }
@@ -2604,7 +2682,7 @@ export async function runImport(repoArg, pmRoot, opts, dependencies = {}) {
         // the write phase cannot diverge from it.
         const prepared = gatePlanByNumber
             ? gatePlanByNumber.get(issue.number)
-            : await prepareGithubImport(issue, repo, opts, token, existing.get(`${repo.toLowerCase()}#${issue.number}`), dependencies.fetchIssueComments);
+            : await prepareGithubImport(issue, repo, opts, token, existing.get(`${repo.toLowerCase()}#${issue.number}`), dependencies.fetchIssueComments, fidelityContext);
         if (!prepared) {
             // A gated run counted its skips during the verified plan phase; only the
             // ungated path counts them here.
@@ -2613,22 +2691,19 @@ export async function runImport(repoArg, pmRoot, opts, dependencies = {}) {
             continue;
         }
         const labels = issue.labels.map((l) => l.name).filter(Boolean);
-        const { title, status, assignee, milestone, match, description, body, tags, comments, syncAnnotations, closedAt, } = prepared;
+        const { title, status, assignee, milestone, match, description, body, tags, comments, syncAnnotations, } = prepared;
         /**
          * Build the `pm close` argv for this issue's pm item.
          *
          * Two paths below close an item for the same reason — reconciling an
          * already-matched item whose upstream issue is now closed, and closing an
          * item that was just created `open` because pm-cli 2026.8.3 refuses a
-         * terminal `create --status closed`. Both must carry identical provenance
-         * (the reason) and identical completion evidence (GitHub's own `closed_at`,
-         * when it recorded one), so the argv is built once here rather than
-         * duplicated at each site where the two could silently drift apart.
+         * terminal `create --status closed`. Both carry the same source reason.
+         * Source completion is applied with source creation during finalization,
+         * avoiding an intermediate completion date before the SDK creation date.
          */
         const githubCloseArgs = (id) => {
-            const args = ["--path", pmRoot, "close", id, "--reason", `GitHub issue #${issue.number} closed`];
-            if (closedAt)
-                args.push("--completed-at", closedAt);
+            const args = ["--path", pmRoot, "close", id, "--reason", prepared.fidelity.github_close_reason];
             return args;
         };
         if (opts.dryRun) {
@@ -2641,6 +2716,15 @@ export async function runImport(repoArg, pmRoot, opts, dependencies = {}) {
                 imported++;
             continue;
         }
+        if (prepared.linkOnly) {
+            const ownerId = match.id;
+            const linked = pmRun(["--path", pmRoot, "update", ownerId, "--add-tags", tags.join(",")]);
+            if (!linked.ok)
+                throw new CommandError(`Could not link GitHub issue #${issue.number} to its existing owner.`);
+            await persistImportFidelity(pmRoot, ownerId, prepared.fidelity, true);
+            updated++;
+            continue;
+        }
         if (match?.id) {
             // Idempotent update — never duplicate. Status transitions go through the
             // proper command (close requires a reason; reopen via update --status).
@@ -2663,17 +2747,22 @@ export async function runImport(repoArg, pmRoot, opts, dependencies = {}) {
                 continue;
             }
             // Reconcile status separately.
+            if (status === "canceled" && match.status !== "canceled") {
+                const cancel = pmRun(["--path", pmRoot, "update", match.id, "--status", "canceled", "--close-reason", prepared.fidelity.github_close_reason]);
+                if (!cancel.ok)
+                    throw new CommandError(`Could not cancel GitHub issue #${issue.number}.`);
+            }
             if (status === "closed" && match.status !== "closed") {
                 // Close through `pm close` so the reason is real provenance; pass the
                 // source completion time as --completed-at when GitHub recorded one.
-                const close = pmRun(githubCloseArgs(match.id));
+                const close = pmRun([...githubCloseArgs(match.id), ...(match.status === "canceled" ? ["--force"] : [])]);
                 if (!close.ok) {
                     console.error(`#${issue.number}: close reconciliation failed — ${close.stderr}`);
                     skipped++;
                     continue;
                 }
             }
-            else if (status === "open" && match.status === "closed") {
+            else if (status === "open" && (match.status === "closed" || match.status === "canceled")) {
                 const reopen = pmRun(["--path", pmRoot, "update", match.id, "--status", "open", "--message", `GitHub issue #${issue.number} reopened`]);
                 if (!reopen.ok) {
                     console.error(`#${issue.number}: reopen reconciliation failed — ${reopen.stderr}`);
@@ -2684,6 +2773,7 @@ export async function runImport(repoArg, pmRoot, opts, dependencies = {}) {
             if (syncAnnotations) {
                 commentWriteFailures += (await syncGithubCommentsToAnnotations(match.id, comments, pmRoot, issue.number)).failed;
             }
+            await persistImportFidelity(pmRoot, match.id, prepared.fidelity, false);
             updated++;
             continue;
         }
@@ -2703,21 +2793,22 @@ export async function runImport(repoArg, pmRoot, opts, dependencies = {}) {
             "--tags", tags.join(","),
             "--message", `Imported from GitHub #${issue.number}`,
         ];
+        if (status === "canceled")
+            createArgs.push("--close-reason", prepared.fidelity.github_close_reason);
         if (assignee)
             createArgs.push("--assignee", assignee);
         if (milestone)
             createArgs.push("--sprint", milestone);
         // --json lets a following close (or annotations sync) address the freshly
         // created item by id without re-scanning the workspace.
-        if (mustClose || syncAnnotations)
-            createArgs.push("--json");
+        createArgs.push("--json");
         const created = pmRun(createArgs);
         if (!created.ok) {
             console.error(`#${issue.number}: create failed — ${created.stderr}`);
             skipped++;
             continue;
         }
-        const createdId = (mustClose || syncAnnotations) ? parseCreatedItemId(created.stdout) : undefined;
+        const createdId = parseCreatedItemId(created.stdout);
         if (mustClose) {
             if (createdId) {
                 const close = pmRun(githubCloseArgs(createdId));
@@ -2749,6 +2840,9 @@ export async function runImport(repoArg, pmRoot, opts, dependencies = {}) {
                 commentWriteFailures += comments.length;
             }
         }
+        if (!createdId)
+            throw new CommandError(`Could not finalize GitHub issue #${issue.number}: created id missing.`);
+        await persistImportFidelity(pmRoot, createdId, prepared.fidelity, false);
         imported++;
     }
     if (opts.dryRun) {
@@ -2784,9 +2878,9 @@ export async function runImport(repoArg, pmRoot, opts, dependencies = {}) {
     // Gated pipeline, phase 2 — the writes are on disk but nothing is committed or
     // pushed; scan the proposed tracker change now and fail closed.
     if (opts.gate)
-        verifyImportedProvenance((dependencies.readItems ?? readPmItems)(pmRoot), gatePlan, repo);
+        verifyImportedProvenance(await readImportItems(), gatePlan, repo);
     const gateReceipt = opts.gate ? gateImportWrites(pmRoot) : undefined;
-    return { imported, updated, skipped, ...fetchFields, ...depLinkResultFields(depLink), ...(gateReceipt ? { gate: gateReceipt } : {}) };
+    return { imported, updated, skipped, ...fetchFields, ...depLinkResultFields(depLink), ...(opts.gate ? { plan: fidelityPlan() } : {}), ...(gateReceipt ? { gate: gateReceipt } : {}) };
 }
 /**
  * Emit the human-readable `--link-deps` summary to stderr.
@@ -4102,7 +4196,8 @@ function graphqlUrl() {
 // `errors` array, so we surface those explicitly. The combined user+org queries
 // below intentionally return a partial error for the wrong owner type while the
 // right one still resolves; we only throw when there is NO usable data.
-async function githubGraphQL(token, query, variables) {
+/** Execute a typed GraphQL request for internal import closure evidence. @internal */
+export async function githubGraphQL(token, query, variables) {
     return (await githubGraphQLResponse(token, query, variables)).data;
 }
 /** Shared GraphQL client retaining partial errors for reference-level classification. */
@@ -4977,7 +5072,7 @@ const PROJECT_SYNC_FLAGS = [
 const defineExtension = (module) => module;
 export default defineExtension({
     name: "pm-github",
-    version: "2026.10.16",
+    version: "2026.10.19",
     activate(api) {
         // -----------------------------------------------------------------------
         // schema — declare the GitHub provenance fields so the workspace knows them
@@ -4989,6 +5084,8 @@ export default defineExtension({
             { name: "github_author", type: "string", optional: true },
             { name: "github_created_at", type: "string", optional: true },
             { name: "github_updated_at", type: "string", optional: true },
+            { name: "github_link_only", type: "boolean", optional: true },
+            ...["github_closed_at", "github_state_reason", "github_close_reason", "github_release"].map(name => ({ name, type: "string", optional: true })),
         ]);
         // -----------------------------------------------------------------------
         // preflight — safe, local guard for mutating github commands. Scoped to
@@ -5311,6 +5408,7 @@ export default defineExtension({
                 { long: "--repo", value_name: "owner/repo", description: "Repository (or PM_GITHUB_REPO)" },
                 { long: "--pr", value_name: "n", repeatable: true, description: "Select a PR number (repeatable; conflicts with --since)" },
                 { long: "--since", value_name: "ISO date", description: "Select PRs merged at or after this ISO date/time" },
+                { long: "--required-checks", value_name: "contexts", description: "One required context per line when protection metadata is unavailable (spaces preserved; blank lines ignored)" },
                 { long: "--skip", value_name: "id", repeatable: true, description: "Never close this item (repeatable)" },
                 { long: "--apply", description: "Close eligible items (default: dry-run)" },
                 { long: "--dry-run", description: "Preview only; overrides --apply" },