pm-github 2026.10.9 → 2026.10.14

package/dist/index.js

@@ -19,7 +19,7 @@ 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, 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, } 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";
@@ -480,6 +480,10 @@ export const EXIT_CODE = {
     GENERIC_FAILURE: 1,
     USAGE: 2,
     NOT_FOUND: 3,
+    // `pm github blockers`: at least one revalidated item is cleared (every
+    // blocker closed or merged) or partially cleared. Distinct from a failure so
+    // a scheduled sync can alert on a lifted blocker without reading the report.
+    BLOCKERS_CLEARED: 4,
 };
 /**
  * Error that carries a semantic process exit code.
@@ -1094,7 +1098,10 @@ export async function importGithubAtomic(pmRoot, repo, entries, opts = {}) {
 // are honored server-side; `milestone` is filtered client-side (the REST API
 // keys milestones by number, not title).
 export function buildIssuesUrl(repo, opts) {
-    let url = `${githubApiBase()}/repos/${repo}/issues?state=${opts.state}&per_page=100`;
+    const pageSize = opts.limit === undefined ? 100 : Math.min(100, opts.limit + 1);
+    let url = `${githubApiBase()}/repos/${repo}/issues?state=${opts.state}&per_page=${pageSize}`;
+    if (opts.limit !== undefined)
+        url += "&sort=updated&direction=desc";
     if (opts.labels)
         url += `&labels=${encodeURIComponent(opts.labels)}`;
     if (opts.since)
@@ -1105,7 +1112,8 @@ export function buildIssuesUrl(repo, opts) {
 }
 /**
  * Page through GitHub's issues REST endpoint, following the Link header, applying
- * the import filters, and returning the full issue list.
+ * the import filters, and returning the issue list. Limited runs stop after
+ * retaining the cap plus one matching issue so callers can report truncation.
  *
  * @internal Exported only so the HTTP-boundary tests can drive the real client.
  * `stripInternal` keeps it out of the published `.d.ts`, so this is NOT a public API
@@ -1126,11 +1134,58 @@ export async function fetchAllIssues(repo, opts, token) {
         if (!Array.isArray(page)) {
             throw new Error("Unexpected GitHub API response (expected an array of issues).");
         }
-        issues.push(...page);
+        const fetched = page;
+        issues.push(...(opts.limit === undefined ? fetched : applyClientFilters(fetched, opts)));
+        // One extra eligible issue proves truncation without draining the repo.
+        if (opts.limit !== undefined && issues.length > opts.limit)
+            return issues.slice(0, opts.limit + 1);
         nextUrl = parseNextLink(linkHeader);
     }
     return issues;
 }
+/** Parse, deduplicate, and validate selected issue references before any fetch. */
+export function parseIssueNumbers(repo, input) {
+    const numbers = new Set();
+    for (const reference of input.split(",")) {
+        const match = /^(?:([^/#\s]+\/[^/#\s]+)#|#)?([1-9]\d*)$/.exec(reference.trim());
+        if (!match || !Number.isSafeInteger(Number(match[2]))) {
+            throw new CommandError("--issue must contain positive issue numbers, #N, or owner/repo#N references.", EXIT_CODE.USAGE);
+        }
+        if (match[1] && match[1].toLowerCase() !== repo.toLowerCase()) {
+            throw new CommandError(`--issue reference ${reference.trim()} conflicts with repository ${repo}.`, EXIT_CODE.USAGE);
+        }
+        numbers.add(Number(match[2]));
+    }
+    return [...numbers];
+}
+/** Fetch only selected REST issue endpoints, refusing PRs and missing numbers before writes. */
+async function fetchSelectedIssues(repo, numbers, opts, token) {
+    const issues = [];
+    const missingIssues = [];
+    for (const number of numbers) {
+        let body;
+        try {
+            ({ body } = await fetchJSON(`${githubApiBase()}/repos/${repo}/issues/${number}`, token));
+        }
+        catch (err) {
+            if (!/HTTP 404/.test(errorMessage(err)))
+                throw err;
+            if (!opts.dryRun)
+                throw new Error(`GitHub issue ${repo}#${number} was not found (HTTP 404); no issues were imported.`);
+            missingIssues.push(number);
+            console.error(`[dry-run] Missing issue: ${repo}#${number} (HTTP 404).`);
+            continue;
+        }
+        const issue = JSON.parse(body);
+        if (issue.number !== number)
+            throw new Error(`Unexpected GitHub issue response for ${repo}#${number}.`);
+        if (issue.pull_request && !opts.includePrs) {
+            throw new Error(`${repo}#${number} is a pull request; use --include-prs to import it. No issues were imported.`);
+        }
+        issues.push(issue);
+    }
+    return { issues, missingIssues };
+}
 /**
  * Fetch all review comments for a single issue or PR, paging through the Link header.
  *
@@ -1775,6 +1830,23 @@ export function applyClientFilters(issues, opts) {
  * @returns The normalized import options.
  */
 export function parseImportOptions(options) {
+    const issue = optionString(options, "issue");
+    if (optionProvided(options, "issue")) {
+        if (!issue)
+            throw new CommandError("--issue requires a non-empty issue list.", EXIT_CODE.USAGE);
+        for (const flag of ["state", "all", "labels", "since", "assignee", "milestone", "limit"]) {
+            if (optionProvided(options, flag))
+                throw new CommandError(`--issue conflicts with --${flag}.`, EXIT_CODE.USAGE);
+        }
+    }
+    let limit;
+    if (optionProvided(options, "limit")) {
+        const input = optionString(options, "limit");
+        if (!input || !/^[1-9]\d*$/.test(input) || !Number.isSafeInteger(Number(input))) {
+            throw new CommandError("--limit must be a positive integer.", EXIT_CODE.USAGE);
+        }
+        limit = Number(input);
+    }
     // --state takes precedence; --all is the legacy shorthand for "all".
     const stateOpt = optionString(options, "state");
     const includeAll = optionEnabled(options, "all");
@@ -1806,6 +1878,8 @@ export function parseImportOptions(options) {
         commentsMode = "both";
     }
     return {
+        issue,
+        limit,
         state,
         labels: optionString(options, "labels"),
         since,
@@ -2324,14 +2398,22 @@ export async function runImport(repoArg, pmRoot, opts, dependencies = {}) {
         throw new CommandError("Usage: pm github import <owner/repo> [--all|--state open|closed|all] " +
             "[--labels bug,enhancement] [--since <iso>] [--assignee <login>] " +
             "[--milestone <name>] [--include-prs] [--skip-drafts] [--with-comments] " +
-            "[--comments-mode body|annotations|both] [--atomic]", EXIT_CODE.USAGE);
+            "[--comments-mode body|annotations|both] [--atomic] [--issue <N[,N...]> | --limit <n>] " +
+            "[--link-deps] [--gate] [--dry-run] [--type <type>]", EXIT_CODE.USAGE);
     }
     const repo = repoArg;
+    const selectedNumbers = opts.issue === undefined ? undefined : parseIssueNumbers(repo, opts.issue);
     const token = (dependencies.resolveToken ?? resolveGitHubToken)();
     console.error(`Fetching issues from ${repo}…${token ? "" : " (unauthenticated — 60 req/hr)"}`);
     let fetched;
+    let missingIssues = [];
     try {
-        fetched = await (dependencies.fetchIssues ?? fetchAllIssues)(repo, opts, token);
+        if (selectedNumbers) {
+            ({ issues: fetched, missingIssues } = await fetchSelectedIssues(repo, selectedNumbers, opts, token));
+        }
+        else {
+            fetched = await (dependencies.fetchIssues ?? fetchAllIssues)(repo, opts, token);
+        }
     }
     catch (err) {
         const msg = errorMessage(err);
@@ -2341,22 +2423,30 @@ export async function runImport(repoArg, pmRoot, opts, dependencies = {}) {
         const exitCode = /HTTP 404/.test(msg) ? EXIT_CODE.NOT_FOUND : EXIT_CODE.GENERIC_FAILURE;
         throw new CommandError(`Failed to fetch issues from ${repo}: ${msg}${hint}`, exitCode);
     }
-    const filtered = applyClientFilters(fetched, opts);
+    const eligible = applyClientFilters(fetched, opts);
+    const filtered = opts.limit === undefined ? eligible : eligible.slice(0, opts.limit);
+    const fetchFields = {
+        ...(opts.limit === undefined ? {} : { limit: opts.limit, truncated: eligible.length > opts.limit }),
+        ...(missingIssues.length === 0 ? {} : { missingIssues }),
+    };
+    if (opts.limit !== undefined && eligible.length > opts.limit)
+        console.error(`Issue list truncated at --limit ${opts.limit}.`);
     if (filtered.length === 0) {
         console.error("No issues found.");
         // Even a no-op gated import must prove the workspace is gateable (a Git work
         // tree the scanner can read), so the empty-change gate scan runs here too.
         const emptyGateReceipt = opts.gate && !opts.dryRun ? gateImportWrites(pmRoot) : undefined;
-        if (opts.atomic && opts.dryRun) {
+        if (opts.dryRun && (opts.atomic || missingIssues.length > 0)) {
             return {
                 dryRun: true,
                 wouldImport: 0,
                 wouldUpdate: 0,
                 wouldSkip: 0,
-                atomic: true,
+                ...(opts.atomic ? { atomic: true } : {}),
+                ...fetchFields,
             };
         }
-        return { imported: 0, updated: 0, skipped: 0, ...(emptyGateReceipt ? { gate: emptyGateReceipt } : {}) };
+        return { imported: 0, updated: 0, skipped: 0, ...fetchFields, ...(emptyGateReceipt ? { gate: emptyGateReceipt } : {}) };
     }
     console.error(`Found ${filtered.length} issue(s).`);
     // Build the idempotency index once up-front — including for a dry run. Skipping
@@ -2431,6 +2521,7 @@ export async function runImport(repoArg, pmRoot, opts, dependencies = {}) {
                     wouldUpdate: 0,
                     wouldSkip: skipped,
                     atomic: true,
+                    ...fetchFields,
                 };
             }
             throw new CommandError(`Imported 0 issue(s); ${skipped} failed.`, EXIT_CODE.GENERIC_FAILURE);
@@ -2455,6 +2546,7 @@ export async function runImport(repoArg, pmRoot, opts, dependencies = {}) {
                 atomic: true,
                 ...(opts.linkDeps ? { wouldLinkDependencyCandidates: countDependencyRefCandidates(repo, filtered) } : {}),
                 ...gatePlanFields,
+                ...fetchFields,
             };
         }
         const result = await (dependencies.commitAtomic ?? importGithubAtomic)(pmRoot, repo, prepared);
@@ -2501,6 +2593,7 @@ export async function runImport(repoArg, pmRoot, opts, dependencies = {}) {
             skipped,
             atomic: true,
             ...depLinkResultFields(atomicDepLink),
+            ...fetchFields,
             ...(gateReceipt ? { gate: gateReceipt } : {}),
         };
     }
@@ -2670,6 +2763,7 @@ export async function runImport(repoArg, pmRoot, opts, dependencies = {}) {
             wouldSkip: skipped,
             ...(opts.linkDeps ? { wouldLinkDependencyCandidates: countDependencyRefCandidates(repo, filtered) } : {}),
             ...gatePlanFields,
+            ...fetchFields,
         };
     }
     console.error(`Imported ${imported} new, updated ${updated} existing, skipped ${skipped}.`);
@@ -2691,7 +2785,7 @@ export async function runImport(repoArg, pmRoot, opts, dependencies = {}) {
     if (opts.gate)
         verifyImportedProvenance((dependencies.readItems ?? readPmItems)(pmRoot), gatePlan, repo);
     const gateReceipt = opts.gate ? gateImportWrites(pmRoot) : undefined;
-    return { imported, updated, skipped, ...depLinkResultFields(depLink), ...(gateReceipt ? { gate: gateReceipt } : {}) };
+    return { imported, updated, skipped, ...fetchFields, ...depLinkResultFields(depLink), ...(gateReceipt ? { gate: gateReceipt } : {}) };
 }
 /**
  * Emit the human-readable `--link-deps` summary to stderr.
@@ -3135,6 +3229,700 @@ async function runExport(ctx) {
     };
 }
 // ---------------------------------------------------------------------------
+// Blocker revalidation — `pm github blockers`
+// ---------------------------------------------------------------------------
+//
+// A `blocked_reason` is a static string: nothing re-reads it, so an item whose
+// named GitHub blocker has since closed stays blocked indefinitely (the
+// motivating incident: two items sat blocked for 27 days after their blocker
+// issue closed). This section revalidates blocked items against the LIVE state
+// of the GitHub issues and pull requests their blocker text names. It is
+// REPORT-ONLY by construction: it never unblocks, reopens, or edits any item;
+// the optional `--comment` appends one idempotent comment per cleared item
+// so a human — not the tool — decides what the cleared blocker means.
+/** Terminal pm lifecycle statuses: an item in one of these can no longer be blocked. */
+export const BLOCKER_TERMINAL_STATUSES = new Set(["closed", "canceled"]);
+/** How many blocker references are resolved per GraphQL request. */
+export const BLOCKER_STATES_BATCH_SIZE = 25;
+/** Shape an `owner/repo` (or `--repo`) hint must have before it resolves bare references. */
+const BLOCKER_REPO_SHAPE = /^[A-Za-z0-9][A-Za-z0-9_.-]*\/[A-Za-z0-9_.-]+$/;
+// GitHub reference forms, anchored so prose around a match cannot leak into it.
+// The prefix class excludes word characters, path separators, dots, and colons,
+// so `https://github.com/o/r/issues/N` (slash before owner) and
+// `github.com/o/r#N` never produce a second, shorter match inside a URL.
+const BLOCKER_URL_RE = /https?:\/\/(?:www\.)?github\.com\/([A-Za-z0-9][A-Za-z0-9_.-]*)\/([A-Za-z0-9_.-]+)\/(?:issues|pull)\/([1-9]\d{0,8})(?!\w)/gi;
+const BLOCKER_OWNER_REPO_RE = /(^|[^\w./:-])([A-Za-z0-9][A-Za-z0-9_.-]*\/[A-Za-z0-9_.-]+)#([1-9]\d{0,8})(?!\w)/g;
+const BLOCKER_GH_DASH_RE = /\bGH-([1-9]\d{0,8})\b/gi;
+const BLOCKER_SHORT_REPO_RE = /(^|[^\w./:-])([A-Za-z0-9_.-]+)#([1-9]\d{0,8})(?!\w)/g;
+const BLOCKER_BARE_HASH_RE = /(^|[^\w./:#-])#([1-9]\d{0,8})(?!\w)/g;
+/**
+ * Mask foreign tracker locators and the `github:` scheme prefix in blocker text.
+ *
+ * `gitlab:`/`jira:`/`linear:` locators name blockers pm-github cannot query, so
+ * the whole token is blanked to keep its `owner/repo#N` interior from parsing as
+ * a GitHub reference. The `github:` scheme — the tracker's canonical external
+ * dependency locator (`github:owner/repo#N`) — is replaced by a space so the
+ * locator's payload parses through the ordinary `owner/repo#N` form.
+ *
+ * @param text - One blocker text source (blocked_reason, description, comment, …).
+ * @returns The text with foreign locators blanked and the `github:` prefix removed.
+ */
+function maskNonGithubLocators(text) {
+    return text.replace(/\b(?:gitlab|jira|linear):[^\s]+/gi, " ").replace(/\bgithub:/gi, " ");
+}
+/**
+ * Parse every GitHub reference in one text source.
+ *
+ * Recognized forms: full issue/PR URLs, `owner/repo#N`, `GH-N`, bare `#N`, and
+ * `name#N` (a repo short name). URL and `owner/repo#N` references carry their
+ * repo; `GH-N`, bare `#N`, and `name#N` do not and are resolved later against
+ * the item's provenance repo or `--repo` (see {@link resolveBlockerReferences}).
+ * Duplicate mentions within one text are not deduplicated here — the resolver
+ * owns the stable identity — but each form's scan is independent, so one text
+ * never yields the same (form, raw, number) twice.
+ *
+ * @param text - One blocker text source (blocked_reason, description, comment, …).
+ * @returns Every recognized reference, in form order (URL, owner/repo, GH-N, short, bare).
+ */
+export function parseBlockerReferences(text) {
+    const masked = maskNonGithubLocators(text);
+    const out = [];
+    for (const m of masked.matchAll(BLOCKER_URL_RE)) {
+        out.push({ repo: `${m[1].toLowerCase()}/${m[2].toLowerCase()}`, number: Number(m[3]), form: "url", raw: m[0] });
+    }
+    for (const m of masked.matchAll(BLOCKER_OWNER_REPO_RE)) {
+        out.push({ repo: m[2].toLowerCase(), number: Number(m[3]), form: "repo_hash", raw: `${m[2]}#${m[3]}` });
+    }
+    for (const m of masked.matchAll(BLOCKER_GH_DASH_RE)) {
+        out.push({ number: Number(m[1]), form: "gh_dash", raw: m[0].toUpperCase() });
+    }
+    for (const m of masked.matchAll(BLOCKER_SHORT_REPO_RE)) {
+        out.push({ number: Number(m[3]), form: "short_repo_hash", raw: `${m[2]}#${m[3]}` });
+    }
+    for (const m of masked.matchAll(BLOCKER_BARE_HASH_RE)) {
+        out.push({ number: Number(m[2]), form: "bare_hash", raw: `#${m[2]}` });
+    }
+    return out;
+}
+/**
+ * Resolve hint-dependent references and deduplicate the result.
+ *
+ * `GH-N`, bare `#N`, and `name#N` references resolve against the first
+ * applicable hint — the item's own `gh:owner/repo#N` provenance repo, then
+ * `--repo`. A `name#N` short form resolves only when the name matches the
+ * hint's repo segment (so `pm-cli#854` resolves against `unbraind/pm-cli`, but
+ * `other#854` stays unresolved instead of guessing an owner). References that
+ * resolve to the same `owner/repo#N` collapse to the first-seen form.
+ *
+ * @param parsed - References from {@link parseBlockerReferences}.
+ * @param itemRepo - The item's provenance repo hint (`owner/repo`), when it has one.
+ * @param fallbackRepo - The `--repo` hint, when given.
+ * @returns Deduplicated references, sorted by repo then number for a deterministic report.
+ */
+export function resolveBlockerReferences(parsed, itemRepo, fallbackRepo) {
+    const out = [];
+    const seen = new Set();
+    for (const ref of parsed) {
+        let repo = ref.repo;
+        if (repo === undefined) {
+            for (const hint of [itemRepo, fallbackRepo]) {
+                if (hint === undefined || !BLOCKER_REPO_SHAPE.test(hint))
+                    continue;
+                if (ref.form === "short_repo_hash" && hint.split("/")[1].toLowerCase() !== ref.raw.split("#")[0].toLowerCase())
+                    continue;
+                repo = hint.toLowerCase();
+                break;
+            }
+        }
+        const key = repo === undefined
+            ? (ref.form === "short_repo_hash" ? `unresolved:${ref.raw.toLowerCase()}` : `unresolved:#${ref.number}`)
+            : `${repo}#${ref.number}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        out.push({ key, ...(repo === undefined ? {} : { repo }), number: ref.number, form: ref.form, raw: ref.raw });
+    }
+    return out.sort((a, b) => `${a.repo ?? ""}#${a.number}`.localeCompare(`${b.repo ?? ""}#${b.number}`));
+}
+/**
+ * Collect and resolve every GitHub reference named by one item's blocker text.
+ *
+ * Sources scanned, in order: external `blocked_by` dependency targets, the
+ * item-level `blocked_by` field, `blocked_reason`, `description`, and every
+ * stored comment. A `blocked_reason` is a static string that nothing re-reads —
+ * that is exactly the staleness this command exists to surface — so comments
+ * (including the latest ones) are scanned too. References matching any of the
+ * item's own GitHub provenance tags are excluded: an issue cannot block itself.
+ *
+ * @param item - One complete item from {@link decodeBlockerPmItems}.
+ * @param fallbackRepo - The `--repo` hint, when given.
+ * @returns Deduplicated resolved references for the item.
+ */
+export function collectBlockerReferences(item, fallbackRepo) {
+    const texts = [];
+    for (const dep of item.dependencies) {
+        if (dep.kind === "blocked_by" && isGithubBlockerDependency(dep.id))
+            texts.push(dep.id);
+    }
+    if (item.blockedBy !== undefined)
+        texts.push(item.blockedBy);
+    if (item.blockedReason !== undefined)
+        texts.push(item.blockedReason);
+    texts.push(item.description);
+    for (const comment of item.comments)
+        texts.push(comment.text);
+    const itemRepo = (() => {
+        for (const tag of item.tags ?? []) {
+            const provenance = parseProvenanceTag(tag);
+            if (provenance && BLOCKER_REPO_SHAPE.test(provenance.repo))
+                return provenance.repo;
+        }
+        return undefined;
+    })();
+    const parsed = texts.flatMap((text) => parseBlockerReferences(text));
+    const ownKeys = new Set((item.tags ?? []).flatMap((tag) => {
+        const provenance = parseProvenanceTag(tag);
+        return provenance ? [`${provenance.repo}#${provenance.number}`] : [];
+    }));
+    return resolveBlockerReferences(parsed, itemRepo, fallbackRepo).filter((ref) => !ownKeys.has(ref.key));
+}
+/** Classify external dependency targets that explicitly name GitHub issues or PRs. */
+function isGithubBlockerDependency(target) {
+    return isExternalDependencyReference(target) && /^(?:github:|https?:\/\/(?:www\.)?github\.com\/)/i.test(target)
+        && parseBlockerReferences(target).length > 0;
+}
+/**
+ * Select the items `pm github blockers` revalidates.
+ *
+ * Every item whose status is `blocked`, plus every non-terminal item carrying a
+ * `blocked_by` dependency (or `blocked_by` field) whose target is an explicit
+ * external reference — the tracker's own cross-system locator classification
+ * plus an explicit GitHub locator or URL decides what counts as
+ * a GitHub target, so a foreign tracker or local `blocked_by` edge to another pm item never selects the
+ * item here. Terminal items are excluded: a closed item cannot be blocked.
+ *
+ * @param items - The complete runtime-validated item corpus.
+ * @returns The candidate items, in corpus order.
+ */
+export function selectBlockerCandidates(items) {
+    return items.filter((item) => {
+        if (item.status === "blocked")
+            return true;
+        if (BLOCKER_TERMINAL_STATUSES.has(item.status))
+            return false;
+        return (item.dependencies.some((dep) => dep.kind === "blocked_by" && isGithubBlockerDependency(dep.id))
+            || (item.blockedBy !== undefined && isGithubBlockerDependency(item.blockedBy)));
+    });
+}
+/**
+ * Read an optional string field from one decoded `pm list --all` row.
+ *
+ * Fail closed on a present-but-wrong-type value: a number or object where a
+ * string belongs means the row cannot be trusted, and an unverifiable read is
+ * not a whole-workspace read.
+ *
+ * @param value - The raw row field.
+ * @param field - Field description for the refusal message.
+ * @returns The string, or `undefined` when the field is absent.
+ * @throws {@link CommandError} When the field is present but not a string.
+ */
+function optionalCompletePmString(value, field) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== "string") {
+        throw new CommandError(`Refusing unverifiable pm list --all output: ${field} must be a string when present.`);
+    }
+    return value;
+}
+/**
+ * Decode the complete `pm list --all` envelope into blocker-revalidation items.
+ *
+ * The envelope and every base field are validated by {@link decodeCompletePmItems}
+ * first (the same complete-read contract import uses), then the extra rows this
+ * command consumes — `blocked_reason`, `blocked_by`, dependency rows, and
+ * comment texts — are validated on top. A wrong-type extra fails closed with
+ * the same refusal wording, because blocker revalidation reading a partial or
+ * untrustworthy corpus would silently miss items.
+ *
+ * @param parsed - JSON decoded from the installed pm CLI.
+ * @returns Fresh runtime-validated blocker items.
+ * @throws {@link CommandError} When a receipt, count, identity, or consumed row
+ * field is absent, incomplete, or contradictory.
+ */
+export function decodeBlockerPmItems(parsed) {
+    const base = decodeCompletePmItems(parsed);
+    // No re-validation branch here: decodeCompletePmItems has already thrown unless
+    // `parsed` is a record whose `items` is an array exactly as long as `base`.
+    const rows = parsed.items;
+    return base.map((item, index) => {
+        // Downcast, not a runtime claim: the complete reader has already proven
+        // id/title/status/description are strings on every row it emitted, so the
+        // required-field view of BlockerPmItem holds for this object.
+        const validated = item;
+        const row = rows[index];
+        const blockedReason = optionalCompletePmString(row.blocked_reason, `item ${item.id} blocked_reason`);
+        const blockedBy = optionalCompletePmString(row.blocked_by, `item ${item.id} blocked_by`);
+        const dependencies = [];
+        if (row.dependencies !== undefined) {
+            if (!Array.isArray(row.dependencies)) {
+                throw new CommandError(`Refusing unverifiable pm list --all output: item ${item.id} dependencies must be an array.`);
+            }
+            for (const dep of row.dependencies) {
+                if (!isJsonRecord(dep) || typeof dep.id !== "string" || typeof dep.kind !== "string") {
+                    throw new CommandError(`Refusing unverifiable pm list --all output: item ${item.id} dependency rows must carry string id and kind.`);
+                }
+                dependencies.push({ id: dep.id, kind: dep.kind });
+            }
+        }
+        const comments = [];
+        if (row.comments !== undefined) {
+            if (!Array.isArray(row.comments)) {
+                throw new CommandError(`Refusing unverifiable pm list --all output: item ${item.id} comments must be an array.`);
+            }
+            for (const comment of row.comments) {
+                if (!isJsonRecord(comment) || typeof comment.text !== "string") {
+                    throw new CommandError(`Refusing unverifiable pm list --all output: item ${item.id} comment rows must carry string text.`);
+                }
+                comments.push({ text: comment.text });
+            }
+        }
+        return {
+            ...validated,
+            dependencies,
+            comments,
+            ...(blockedReason === undefined ? {} : { blockedReason }),
+            ...(blockedBy === undefined ? {} : { blockedBy }),
+        };
+    });
+}
+/**
+ * Read every item through the complete SDK path and check its completeness certificate.
+ *
+ * The SDK disables extensions for the observational read. The shared item
+ * decoder also validates every blocker field consumed by this command.
+ *
+ * @param pmRoot - Workspace or tracker root accepted by the SDK.
+ * @returns The complete runtime-validated blocker item corpus.
+ * @throws On unreadable, incomplete, omitted, or invalid tracker data.
+ */
+export async function readBlockerPmItems(pmRoot) {
+    const result = certifyCompleteListResult(await listAllComplete({ includeBody: true }, { pmRoot, cwd: pmRoot, noExtensions: true }));
+    return decodeBlockerPmItems(result);
+}
+/**
+ * Build the batched GraphQL document resolving many references' live state.
+ *
+ * One query aliases each distinct repo (`r0: repository(owner:…, name:…)`), and
+ * within it each reference twice (`iN: issue(number:…)` plus `pN:
+ * pullRequest(number:…)`) — a number is either an issue or a PR and GraphQL
+ * resolves the wrong one to null, so one round-trip classifies every reference
+ * without guessing its kind. Repos are deduplicated and sorted, and each repo's
+ * references are sorted by number, so the document is a pure function of the
+ * reference SET, keeping recorded fixtures stable. The returned entries carry
+ * every reference's aliases so the response can be read back without
+ * re-deriving that ordering.
+ *
+ * @param refs - One batch's resolved references.
+ * @returns The query, its repo alias order, and the per-reference alias entries.
+ */
+export function buildBlockerStatesQueryPlan(refs) {
+    const byRepo = new Map();
+    for (const ref of refs) {
+        const bucket = byRepo.get(ref.repo);
+        if (bucket)
+            bucket.push(ref);
+        else
+            byRepo.set(ref.repo, [ref]);
+    }
+    const repos = [...byRepo.keys()].sort();
+    const entries = [];
+    const blocks = repos.map((repo, repoIndex) => {
+        const bucket = byRepo.get(repo).slice().sort((a, b) => a.number - b.number);
+        const fields = bucket.map((ref, refIndex) => {
+            entries.push({ ref, repoAlias: `r${repoIndex}`, issueAlias: `i${repoIndex}_${refIndex}`, pullAlias: `p${repoIndex}_${refIndex}` });
+            return `    i${repoIndex}_${refIndex}: issue(number: ${ref.number}) { state stateReason closedAt url }\n` +
+                `    p${repoIndex}_${refIndex}: pullRequest(number: ${ref.number}) { state mergedAt closedAt url }`;
+        });
+        const [owner, name] = repo.split("/");
+        return `  r${repoIndex}: repository(owner: "${owner}", name: "${name}") {\n${fields.join("\n")}\n  }`;
+    });
+    return { query: `query {\n${blocks.join("\n")}\n}`, repos, entries };
+}
+/**
+ * Split references into fixed-size batches.
+ *
+ * @param refs - References to batch.
+ * @param size - Maximum references per batch (at least 1).
+ * @returns Consecutive slices of the input, in order.
+ */
+export function chunkBlockerReferences(refs, size) {
+    if (!Number.isInteger(size) || size < 1)
+        throw new CommandError("Blocker batch size must be a positive integer.");
+    const batches = [];
+    for (let i = 0; i < refs.length; i += size)
+        batches.push(refs.slice(i, i + size));
+    return batches;
+}
+/**
+ * Map one reference's aliased issue/pull-request nodes to its live state.
+ *
+ * Null nodes for both the issue and the PR field mean GitHub would not resolve
+ * the reference — nonexistent, or present but invisible to the token; GitHub
+ * answers both identically, so both are reported `not_found`. An issue node
+ * wins over a PR node (only one of the two can exist for a number); an
+ * unrecognized state string is reported as an error rather than guessed.
+ *
+ * @param ref - The reference the nodes answer.
+ * @param issue - The aliased issue node, when GitHub resolved one.
+ * @param pullRequest - The aliased pull-request node, when GitHub resolved one.
+ * @returns The reference's live state.
+ */
+function mapBlockerReferenceNode(ref, issue, pullRequest) {
+    const base = { repo: ref.repo, number: ref.number, form: ref.form, raw: ref.raw };
+    if (issue) {
+        if (issue.state === "OPEN")
+            return { ...base, state: "open" };
+        if (issue.state === "CLOSED") {
+            return {
+                ...base,
+                state: "closed",
+                ...(issue.stateReason ? { state_reason: issue.stateReason } : {}),
+                ...(issue.closedAt ? { closed_at: issue.closedAt } : {}),
+                ...(issue.url ? { url: issue.url } : {}),
+            };
+        }
+        return { ...base, state: "error", error: "Unexpected GitHub issue state." };
+    }
+    if (pullRequest) {
+        if (pullRequest.state === "OPEN")
+            return { ...base, state: "open" };
+        if (pullRequest.state === "MERGED") {
+            return {
+                ...base,
+                state: "merged",
+                ...(pullRequest.mergedAt ? { merged_at: pullRequest.mergedAt } : {}),
+                ...(pullRequest.closedAt ? { closed_at: pullRequest.closedAt } : {}),
+                ...(pullRequest.url ? { url: pullRequest.url } : {}),
+            };
+        }
+        if (pullRequest.state === "CLOSED") {
+            return {
+                ...base,
+                state: "closed",
+                ...(pullRequest.closedAt ? { closed_at: pullRequest.closedAt } : {}),
+                ...(pullRequest.url ? { url: pullRequest.url } : {}),
+            };
+        }
+        return { ...base, state: "error", error: "Unexpected GitHub pull request state." };
+    }
+    return { ...base, state: "not_found" };
+}
+/**
+ * Query the live state of every resolved reference, batched.
+ *
+ * References are batched ({@link BLOCKER_STATES_BATCH_SIZE} per request) through
+ * the shared client, auth, and rate-limit handling. A batch whose transport
+ * fails (no usable data — e.g. an invalid token or a total GraphQL error) marks
+ * every reference in it `error` and the run continues, so one inaccessible repo
+ * cannot blind the report on the others.
+ *
+ * @param refs - Every resolved reference across all items.
+ * @param transport - GraphQL transport (the production one closes over the token).
+ * @returns Live state by {@link BlockerReference.key}.
+ */
+export async function fetchBlockerReferenceStates(refs, transport) {
+    const states = new Map();
+    for (const batch of chunkBlockerReferences(refs, BLOCKER_STATES_BATCH_SIZE)) {
+        const plan = buildBlockerStatesQueryPlan(batch);
+        let response;
+        try {
+            response = await transport(plan.query);
+        }
+        catch {
+            for (const ref of batch)
+                states.set(ref.key, { repo: ref.repo, number: ref.number, form: ref.form, raw: ref.raw, state: "error", error: "GitHub blocker state request failed." });
+            continue;
+        }
+        for (const entry of plan.entries) {
+            const failure = response.errors?.find((error) => error.type !== "NOT_FOUND" &&
+                (!error.path || (error.path[0] === entry.repoAlias &&
+                    (error.path.length === 1 || error.path[1] === entry.issueAlias || error.path[1] === entry.pullAlias))));
+            if (failure) {
+                states.set(entry.ref.key, { ...entry.ref, state: "error", error: "GitHub rejected blocker state access." });
+                continue;
+            }
+            const repoBlock = response.data?.[entry.repoAlias];
+            if (repoBlock === undefined || (repoBlock !== null && (repoBlock[entry.issueAlias] === undefined || repoBlock[entry.pullAlias] === undefined))) {
+                states.set(entry.ref.key, { ...entry.ref, state: "error", error: "Incomplete GitHub blocker state response." });
+                continue;
+            }
+            states.set(entry.ref.key, mapBlockerReferenceNode(entry.ref, repoBlock?.[entry.issueAlias], repoBlock?.[entry.pullAlias]));
+        }
+    }
+    return states;
+}
+/**
+ * The revalidation verdict over one item's reference states.
+ *
+ * `cleared` requires every reference closed or merged; a partially cleared item
+ * (some blocker closed, some still open or unreadable) is reported as such
+ * rather than cleared, because an unreadable reference can always be open. An
+ * item with no references at all — a blocked_reason naming no GitHub reference —
+ * is `unresolvable`: its static text can never be revalidated automatically.
+ *
+ * @param states - The item's reference states.
+ * @returns The item's verdict.
+ */
+export function blockerItemVerdict(states) {
+    if (states.length === 0)
+        return "unresolvable";
+    let cleared = 0;
+    let open = 0;
+    for (const state of states) {
+        if (state.state === "closed" || state.state === "merged")
+            cleared++;
+        else if (state.state === "open")
+            open++;
+    }
+    if (cleared === states.length)
+        return "cleared";
+    if (cleared > 0)
+        return "partially_cleared";
+    if (open > 0)
+        return "still_blocked";
+    return "unresolvable";
+}
+/** Marker a blockers comment carries so re-runs can skip it (`pm-github:blockers:…`). */
+export const BLOCKERS_COMMENT_MARKER_REGEX = /<!--\s*pm-github:blockers:([A-Za-z0-9][A-Za-z0-9_.-]*\/[A-Za-z0-9_.-]+)#(\d+):(closed|merged):([^\s<>]+)\s*-->/g;
+/**
+ * Build the idempotency marker for one cleared blocker reference.
+ *
+ * Identity is the reference PLUS its observed state (repo, number, closed or
+ * merged, and the exact timestamp): if the blocker later reopens and closes
+ * again, the changed timestamp makes the marker a new one and a fresh comment
+ * is appended, while an unchanged state never repeats.
+ *
+ * @param repo - The blocker's `owner/repo`.
+ * @param number - The blocker's number.
+ * @param disposition - `closed` or `merged`.
+ * @param at - The close/merge ISO timestamp.
+ * @returns The marker string embedded in the comment.
+ */
+export function blockerCommentMarker(repo, number, disposition, at) {
+    return `<!-- pm-github:blockers:${repo}#${number}:${disposition}:${at} -->`;
+}
+/**
+ * The disposition and timestamp one cleared reference is reported under.
+ *
+ * Shared by the comment builder and its idempotency marker so both always
+ * agree on whether a reference closed or merged, and on which date.
+ *
+ * @param state - The cleared reference's live state.
+ * @returns `closed`/`merged` plus the close or merge ISO timestamp (empty when GitHub sent none).
+ */
+function blockerDispositionAndDate(state) {
+    const disposition = state.state === "merged" ? "merged" : "closed";
+    const at = (state.state === "merged" ? state.merged_at : state.closed_at) ?? "";
+    return { disposition, at };
+}
+/**
+ * Build the comment appended for one cleared blocker reference.
+ *
+ * Human text first (what the blocker was and when it closed, then the ask —
+ * revalidate), marker last, mirroring the GitHub comment sync's layout so stored
+ * comments stay scannable and machine-skippable.
+ *
+ * @param state - The cleared reference's live state.
+ * @returns The comment text.
+ */
+export function buildBlockerClearedComment(state) {
+    const repo = state.repo ?? "";
+    const { disposition, at } = blockerDispositionAndDate(state);
+    const human = at === "" ? "an unknown date" : at.slice(0, 10);
+    const marker = blockerCommentMarker(repo, state.number, disposition, at === "" ? "unknown" : at);
+    return `Blocker ${repo}#${state.number} ${disposition} on ${human}; revalidate.\n\n${marker}`;
+}
+/**
+ * Collect the blocker markers already present in an item's comments.
+ *
+ * Mirrors {@link extractSyncedCommentIds}: each stored comment's text is scanned
+ * for the marker; hand-written comments simply contribute nothing.
+ *
+ * @param stored - The item's existing native comments.
+ * @returns The set of marker strings already present.
+ */
+export function extractBlockerCommentMarkers(stored) {
+    const markers = new Set();
+    for (const entry of stored) {
+        if (!entry?.text)
+            continue;
+        for (const m of entry.text.matchAll(BLOCKERS_COMMENT_MARKER_REGEX)) {
+            markers.add(blockerCommentMarker(m[1].toLowerCase(), Number(m[2]), m[3], m[4]));
+        }
+    }
+    return markers;
+}
+/**
+ * Append one idempotent comment per cleared item reference on its item.
+ *
+ * Never unblocks, reopens, or edits anything — a cleared blocker does not
+ * always mean the work is unblocked, so the comment only names the closed
+ * blocker and asks a human to revalidate. Idempotent across re-runs and safe
+ * across concurrent runs: the per-item comment lock serializes the read-markers-then-append
+ * window, and a comment whose marker is already present is skipped, so the
+ * same reference state is never announced twice.
+ *
+ * @param pmRoot - Workspace root or pm data dir.
+ * @param cleared - Cleared reference states grouped by their item id.
+ * @param dryRun - Preview the comments without writing anything.
+ * @returns How many comments were added, skipped as already present, and not written.
+ * @internal Exported so the lock-contention and write-failure paths are directly
+ * testable without racing a real process; stripped from the published declaration.
+ */
+export async function appendBlockerComments(pmRoot, cleared, dryRun) {
+    let added = 0;
+    let skipped = 0;
+    let failed = 0;
+    for (const entry of cleared) {
+        const acquisition = await acquireImportLock(pmRoot, entry.itemId);
+        if (acquisition.status !== "acquired") {
+            console.error(`${entry.itemId}: blocker comment skipped — comment-sync lock unavailable; re-run to record it`);
+            failed++;
+            continue;
+        }
+        const release = () => acquisition.lock.release();
+        try {
+            let existing;
+            try {
+                const list = await pmCommentsFn(entry.itemId, {}, { pmRoot, cwd: pmRoot });
+                existing = list.comments;
+            }
+            catch (err) {
+                console.error(`${entry.itemId}: could not read existing comments — ${errorMessage(err)}`);
+                failed++;
+                continue;
+            }
+            const markers = extractBlockerCommentMarkers(existing);
+            const pending = entry.states.filter((state) => {
+                const { disposition, at } = blockerDispositionAndDate(state);
+                return !markers.has(blockerCommentMarker(state.repo ?? "", state.number, disposition, at === "" ? "unknown" : at));
+            });
+            if (pending.length === 0) {
+                skipped++;
+                continue;
+            }
+            const text = pending.map(buildBlockerClearedComment).join("\n\n");
+            if (dryRun) {
+                added++;
+                continue;
+            }
+            try {
+                await pmCommentsFn(entry.itemId, { add: text, author: "pm-github" }, { pmRoot, cwd: pmRoot });
+                added++;
+            }
+            catch (err) {
+                console.error(`${entry.itemId}: blocker comment failed — ${errorMessage(err)}`);
+                failed++;
+            }
+        }
+        finally {
+            release();
+        }
+    }
+    return { added, skipped, failed };
+}
+/**
+ * Run `pm github blockers`: revalidate blocked items against the live state of their GitHub blockers.
+ *
+ * Reads the complete corpus through the SDK with a completeness certificate, selects blocked items plus non-terminal items with an external GitHub
+ * `blocked_by` dependency, parses their blocker text, queries each reference's
+ * live state in batched GraphQL, and reports a verdict per item. REPORT-ONLY:
+ * nothing is unblocked or edited; `--comment` only appends idempotent comments.
+ * Exit codes: 0 when nothing cleared, {@link EXIT_CODE.BLOCKERS_CLEARED} when
+ * something cleared or partially cleared, {@link EXIT_CODE.USAGE} for usage or a
+ * missing token, {@link EXIT_CODE.GENERIC_FAILURE} when any reference state query
+ * or any requested comment failed (takes precedence over 4).
+ *
+ * @param ctx - The host command-handler context.
+ * @returns The full report for the host renderer (JSON/TOON).
+ * @throws {@link CommandError} For usage or requested-item selection errors.
+ */
+async function runBlockers(ctx) {
+    const options = ctx.options;
+    const fallbackRepo = optionString(options, "repo");
+    if (fallbackRepo !== undefined && !BLOCKER_REPO_SHAPE.test(fallbackRepo)) {
+        throw new CommandError("Usage: pm github blockers [--repo owner/repo] [--ids pm-1,pm-2] [--comment] [--dry-run]  " +
+            "(--repo must be owner/repo)", EXIT_CODE.USAGE);
+    }
+    const scopedIds = optionCsv(options, "ids");
+    if (optionProvided(options, "ids") && scopedIds.length === 0) {
+        throw new CommandError("--ids requires at least one pm item id (comma-separated), e.g. --ids pm-123,pm-456.", EXIT_CODE.USAGE);
+    }
+    const withComments = optionEnabled(options, "comment");
+    const dryRun = optionEnabled(options, "dry-run", "dryRun");
+    const token = resolveGitHubToken();
+    if (!token) {
+        throw new CommandError("pm github blockers reads blocker state from GitHub and needs a token " +
+            "(set GITHUB_TOKEN/GH_TOKEN or run `gh auth login`).", EXIT_CODE.USAGE);
+    }
+    const corpus = await readBlockerPmItems(ctx.pm_root);
+    const selected = requireRequestedItems(corpus, scopedIds);
+    const candidates = selectBlockerCandidates(selected);
+    const perItem = candidates.map((item) => ({ item, references: collectBlockerReferences(item, fallbackRepo) }));
+    const unique = new Map();
+    for (const entry of perItem) {
+        for (const ref of entry.references) {
+            if (ref.repo !== undefined && !unique.has(ref.key)) {
+                unique.set(ref.key, { key: ref.key, repo: ref.repo, number: ref.number, form: ref.form, raw: ref.raw });
+            }
+        }
+    }
+    const stateByKey = await fetchBlockerReferenceStates([...unique.values()], (query) => githubGraphQLResponse(token, query, {}));
+    const queried = [...stateByKey.values()];
+    const items = perItem.map(({ item, references }) => {
+        const refStates = references.map((ref) => stateByKey.get(ref.key)
+            ?? { repo: ref.repo, number: ref.number, form: ref.form, raw: ref.raw, state: "unresolved" });
+        return {
+            id: item.id,
+            status: item.status,
+            verdict: blockerItemVerdict(refStates),
+            references: refStates,
+        };
+    });
+    const counts = {
+        cleared: items.filter((entry) => entry.verdict === "cleared").length,
+        partially_cleared: items.filter((entry) => entry.verdict === "partially_cleared").length,
+        still_blocked: items.filter((entry) => entry.verdict === "still_blocked").length,
+        unresolvable: items.filter((entry) => entry.verdict === "unresolvable").length,
+    };
+    let comment;
+    if (withComments) {
+        const cleared = items
+            .filter((entry) => entry.verdict === "cleared")
+            .map((entry) => ({
+            itemId: entry.id,
+            states: entry.references,
+        }));
+        const receipt = await appendBlockerComments(ctx.pm_root, cleared, dryRun);
+        comment = { requested: true, dry_run: dryRun, ...receipt };
+    }
+    const report = {
+        command: "github blockers",
+        generated_at: new Date().toISOString(),
+        items_read: selected.length,
+        candidates: candidates.length,
+        items,
+        counts,
+        ...(comment === undefined ? {} : { comment }),
+    };
+    const failed = queried.some((state) => state.state === "error") || (comment?.failed ?? 0) > 0;
+    if (failed)
+        return { ...report, exit_code: EXIT_CODE.GENERIC_FAILURE };
+    if (counts.cleared > 0 || counts.partially_cleared > 0)
+        return { ...report, exit_code: EXIT_CODE.BLOCKERS_CLEARED };
+    return report;
+}
+// ---------------------------------------------------------------------------
 // Search provider — reach GitHub from `pm search` for imported items
 // ---------------------------------------------------------------------------
 //
@@ -3314,6 +4102,10 @@ function graphqlUrl() {
 // 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) {
+    return (await githubGraphQLResponse(token, query, variables)).data;
+}
+/** Shared GraphQL client retaining partial errors for reference-level classification. */
+async function githubGraphQLResponse(token, query, variables) {
     if (!token) {
         throw new CommandError("GitHub GraphQL requires a token (set GITHUB_TOKEN/GH_TOKEN or run `gh auth login`).", EXIT_CODE.USAGE);
     }
@@ -3330,7 +4122,7 @@ async function githubGraphQL(token, query, variables) {
         const messages = (parsed.errors ?? []).map((e) => e.message).join("; ");
         throw new CommandError(`GitHub GraphQL error${messages ? `: ${messages}` : ` (HTTP ${res.status})`}.`);
     }
-    return parsed.data;
+    return parsed;
 }
 const STATUS_FIELD_GQL = `
   statusField: field(name: "Status") {
@@ -4103,6 +4895,8 @@ export function isMutatingGithubCommand(command, options) {
 // Extension
 // ---------------------------------------------------------------------------
 const IMPORT_FLAGS = [
+    { long: "--issue", value_name: "N[,N...]", description: "Fetch exactly these issue numbers, #N, or same-repo owner/repo#N references; conflicts with --state/--all/--labels/--since/--assignee/--milestone/--limit. Missing numbers fail before writes (reported by --dry-run); PRs require --include-prs" },
+    { long: "--limit", value_name: "n", description: "Positive list-mode issue cap, newest-updated first; reports limit and truncated when more exist (one extra matching issue is fetched to check). Invalid with --issue" },
     { long: "--all", description: "Include closed issues (shorthand for --state all)" },
     { long: "--state", value_name: "state", description: "Issue state: open | closed | all (default: open)" },
     { long: "--labels", value_name: "labels", description: "Comma-separated label filter" },
@@ -4142,6 +4936,12 @@ const GATE_FLAGS = [
 const VALIDATE_FLAGS = [
     { long: "--repo", value_name: "owner/repo", description: "Also check this repo is accessible with the resolved token" },
 ];
+const BLOCKERS_FLAGS = [
+    { long: "--repo", value_name: "owner/repo", description: "Fallback repo for bare `#N`, `GH-N`, and `name#N` references that carry no owner (after the item's own gh: provenance repo)" },
+    { long: "--ids", value_name: "pm-1,pm-2", description: "Only revalidate these pm item IDs (comma-separated)" },
+    { long: "--comment", description: "Append one idempotent pm comment per cleared item (never unblocks or edits the item; re-runs skip an already-announced reference state)" },
+    { long: "--dry-run", description: "With --comment: preview the comments without writing anything (the report itself never mutates)" },
+];
 const PROJECT_LIST_FLAGS = [
     { long: "--owner", value_name: "login", description: "GitHub user or org login (or pass positionally)" },
 ];
@@ -4176,7 +4976,7 @@ const PROJECT_SYNC_FLAGS = [
 const defineExtension = (module) => module;
 export default defineExtension({
     name: "pm-github",
-    version: "2026.10.9",
+    version: "2026.10.14",
     activate(api) {
         // -----------------------------------------------------------------------
         // schema — declare the GitHub provenance fields so the workspace knows them
@@ -4235,6 +5035,8 @@ export default defineExtension({
                 { name: "owner/repo", required: true, description: "GitHub repository to import" },
             ],
             examples: [
+                "pm github import owner/repo --issue 189",
+                "pm github import owner/repo --limit 10",
                 "pm github import unbraind/pm-cli",
                 "pm github import owner/repo --since 7d",
                 "pm github import owner/repo --include-comments",
@@ -4399,6 +5201,8 @@ export default defineExtension({
             ],
             examples: [
                 "pm gh-issues import unbraind/pm-cli",
+                "pm gh-issues import owner/repo --issue 189",
+                "pm gh-issues import owner/repo --limit 10",
                 "pm gh-issues import unbraind/pm-cli --all",
                 "pm gh-issues import unbraind/pm-cli --labels bug,enhancement",
                 "pm gh-issues import unbraind/pm-cli --since 2026-01-01T00:00:00Z",
@@ -4497,6 +5301,45 @@ export default defineExtension({
             },
         });
         // -----------------------------------------------------------------------
+        // command — `pm github blockers` (revalidate blocked items against the
+        // live state of their GitHub blockers). REPORT-ONLY: it never unblocks,
+        // reopens, or edits any item; --comment only appends idempotent comments.
+        // Exit codes: 0 nothing cleared; 4 something cleared or partially cleared
+        // (so CI and the scheduled sync can alert); 2 usage/missing token;
+        // 1 failure (any reference state query or requested comment failed, which
+        // takes precedence over 4).
+        // -----------------------------------------------------------------------
+        api.registerCommand({
+            name: "github blockers",
+            description: "Revalidate blocked items against the live state of the GitHub issues and pull requests their " +
+                "blocked_reason, description, comments, and external blocked_by dependencies name " +
+                "(owner/repo#N, bare #N vs the item's repo or --repo, full issue/PR URLs, GH-N). " +
+                "Queries current state (open, closed with reason, merged, not found) in batched GraphQL and reports a " +
+                "verdict per item: cleared, partially_cleared, still_blocked, or unresolvable. NEVER auto-unblocks. " +
+                "Read-only; --comment appends one idempotent pm comment per cleared item. " +
+                "Exits 4 when something is cleared so CI and the scheduled sync can alert; use --json for machine output.",
+            intent: "revalidate blocked items against the live state of their GitHub blockers",
+            examples: [
+                "pm github blockers",
+                "pm github blockers --json",
+                "pm github blockers --repo unbraind/pm-cli",
+                "pm github blockers --ids pm-123,pm-456 --json",
+                "pm github blockers --comment",
+                "pm github blockers --comment --dry-run",
+            ],
+            flags: BLOCKERS_FLAGS,
+            failure_hints: [
+                "Set GITHUB_TOKEN/GH_TOKEN or run `gh auth login`; blockers reads live GitHub state.",
+                "Pass --repo owner/repo so bare `#N`, `GH-N`, and `name#N` references resolve; imported items resolve against their own provenance repo.",
+                "Exit code 4 means at least one blocked item has a cleared or partially cleared blocker; nothing was changed — revalidate the item by hand.",
+                "--comment never unblocks: it only appends one idempotent comment per cleared item.",
+                "Use --ids <pm-1,pm-2> to scope revalidation; unknown IDs fail fast.",
+            ],
+            async run(ctx) {
+                return runBlockers(ctx);
+            },
+        });
+        // -----------------------------------------------------------------------
         // command — `pm github project list <owner>` (discover ProjectsV2)
         // -----------------------------------------------------------------------
         api.registerCommand({