@deftai/directive-core 0.107.0 → 0.108.0

package/dist/product-first-done-gate/acceptance-resolver.js

@@ -106,19 +106,30 @@ export function formatAcceptanceVerdict(verdictResult) {
     return `${lead}\n  remedy: ${verdictResult.remedy}`;
 }
 /**
- * Clause-walk composition (#3323 / #3497).
+ * Clause-walk composition (#3323 / #3497 / #3826).
  *
  * A clause the shipped artifact contradicts (`failed`) always blocks. A clause the
  * static walk cannot decide (`unverifiable`) is evidence of nothing — it blocks only
  * when nothing else verified the product. A green executable acceptance run IS that
  * something: the product-first oracle already ran. Before #3497 an all-unverifiable
  * clause set refused an artifact whose stated command had just exited 0.
+ *
+ * #3826 excused a set the walk has no oracle for at all: a clause with no bound
+ * artifact path can only ever come back `unverifiable`, so demanding a positive
+ * `verified` from a set of them cannot be satisfied by doing the work correctly.
+ * Where the walk has no oracle, `failed === 0` is the strongest verdict available
+ * and `evaluateAcceptanceEvidenceGate` adjudicates those criteria at `scope:complete`.
+ *
+ * #3835 makes that excusal per clause. As a *set* predicate, `verified > 0` was
+ * re-armed for every clause by any single bound one, so one verified binding
+ * covered siblings that had their own oracle and did not meet it.
+ * `adjudicableUnverified` counts exactly those siblings.
  */
 export function clauseWalkBlocks(input) {
     if (input.failed > 0) {
         return true;
     }
-    if (input.walked === 0 || input.verified > 0) {
+    if (input.walked === 0 || input.adjudicableUnverified === 0) {
         return false;
     }
     return !input.hasGreenExecutableRun;

package/dist/product-first-done-gate/evaluate.js

@@ -17,7 +17,7 @@ import { resolveAcReuse, resolveScopeIdForAcReuse, snapshotFromReuseFields, } fr
 import { gitHead } from "../session/git.js";
 import { hashProductState } from "../session/product-state-hash.js";
 import { resolveVerifyAcSessionId, writeVerifyAcSessionCache, } from "../session/verify-ac-session-cache.js";
-import { formatClauseWalkMessage, walkAcceptanceClauses, } from "../verify-ac/clauses.js";
+import { countUnverifiedAdjudicableClauses, formatClauseWalkMessage, readDeclaredArtifactScope, walkAcceptanceClauses, } from "../verify-ac/clauses.js";
 import { emitVerifyAcAttempts, evaluateProductOracleIntegrity, mergeOracleVerdict, } from "../verify-ac/evaluate.js";
 import { readPlanAcceptance, validatePlanAcceptance } from "./acceptance.js";
 import { clauseWalkBlocks, formatAcceptanceVerdict, resolveAcceptanceVerdict, } from "./acceptance-resolver.js";
@@ -475,21 +475,24 @@ export function emitVerifyAcTerminalOutcome(input) {
         resolvedCommandCount: 0,
     }, { projectRoot: input.projectRoot, env: input.env }, resolve(input.projectRoot));
 }
-function applyClauseWalk(result, options) {
+function applyClauseWalk(result, options, plan) {
     const clauses = result.acceptance.clauses ?? [];
     if (clauses.length === 0 || result.resolution === "config" || result.resolution === "skipped") {
         return result;
     }
     const projectRoot = resolve(options.projectRoot ?? process.cwd());
-    const report = walkAcceptanceClauses(clauses, projectRoot);
+    // #3835: the walk reads files, so it reads only what this brief declared.
+    const report = walkAcceptanceClauses(clauses, projectRoot, {
+        declaredScope: readDeclaredArtifactScope(plan),
+    });
     const message = options.quiet ? result.message : formatClauseWalkMessage(report, result.message);
     // #3497: a clause the static walk cannot decide is evidence of nothing. It blocks
     // only when nothing else verified the product; a green executable acceptance run
     // already is the product-first oracle. Failed clauses still block unconditionally.
     const blocked = clauseWalkBlocks({
         failed: report.failed.length,
-        verified: report.verified.length,
         walked: report.clauses.length,
+        adjudicableUnverified: countUnverifiedAdjudicableClauses(report.clauses),
         hasGreenExecutableRun: result.ok && result.runs.length > 0 && result.runs.every((run) => run.ok),
     });
     const ok = result.ok && !blocked;
@@ -498,8 +501,10 @@ function applyClauseWalk(result, options) {
         ok,
         code: ok ? result.code : result.code === 2 ? 2 : 1,
         message,
+        // #3835: only a clause that actually verified may relabel an empty pass as
+        // verified. A walk that verified nothing has not verified anything.
         resolution: ok
-            ? result.resolution === "empty-pass"
+            ? result.resolution === "empty-pass" && report.verified.length > 0
                 ? "verified-pass"
                 : result.resolution
             : "fail",
@@ -549,8 +554,13 @@ function labelVerdict(result) {
 }
 function applyOracle(result, options, plan = {}) {
     const projectRoot = resolve(options.projectRoot ?? process.cwd());
-    const walked = applyClauseWalk(applyRejectedNoop(result), options);
-    const gated = walked.clauseWalked === true ? walked : applyEmptyFloorPolicy(walked, options);
+    const walked = applyClauseWalk(applyRejectedNoop(result), options, plan);
+    // #3835: the clause walk may stand in for the empty floor only when it actually
+    // verified something. A walk that verified nothing is not positive evidence, so
+    // an otherwise-empty acceptance still answers to the project floor rather than
+    // passing on the strength of a clause set nothing adjudicated.
+    const walkVerified = (walked.clauseOutcomes ?? []).some((row) => row.outcome === "verified");
+    const gated = walked.clauseWalked === true && walkVerified ? walked : applyEmptyFloorPolicy(walked, options);
     // Emit/read disk only when the caller supplied env (CLI passes process.env).
     // Tests stay isolated unless they opt in with env or runSummaryText.
     if (options.env !== undefined) {

package/dist/release/cli-drift-report.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Local-vs-released CLI drift report after a cut (#3753).
+ *
+ * Report-only: never runs `npm i -g`. Never fails the release. Polls all four
+ * workspace packages with `--prefer-online` so a lag-poisoned npm cache cannot
+ * masquerade as a missing publish.
+ */
+import { type ActiveCliCheckResult } from "../session/active-cli.js";
+import type { ReleaseConfig } from "./types.js";
+/** Workspace packages published by npm-publish.yml (sibling propagate is not atomic). */
+export declare const WORKSPACE_PACKAGES: readonly ["@deftai/directive-types", "@deftai/directive-core", "@deftai/directive-content", "@deftai/directive"];
+export type WorkspacePackageName = (typeof WORKSPACE_PACKAGES)[number];
+/** Observed sibling lag was ~7 minutes; Phase 7 wait sits under this ceiling. */
+export declare const CLI_DRIFT_POLL_TIMEOUT_MS: number;
+export declare const CLI_DRIFT_POLL_INTERVAL_MS = 30000;
+/** Pipeline completion is a single probe — Step 13 returns before npm-publish.yml is green. */
+export declare const CLI_DRIFT_PIPELINE_POLL_TIMEOUT_MS = 0;
+export type RegistryVisibility = "all-visible" | "still-propagating" | "publish-incomplete" | "skipped";
+export interface WorkspacePackageProbe {
+    readonly name: WorkspacePackageName;
+    readonly visible: boolean;
+    readonly version: string | null;
+}
+export interface CliDriftReport {
+    readonly releasedVersion: string;
+    readonly localVersion: string | null;
+    readonly localPath: string | null;
+    readonly match: boolean;
+    readonly shadowed: boolean;
+    readonly registry: RegistryVisibility;
+    readonly packages: readonly WorkspacePackageProbe[];
+    readonly remediation: string;
+    readonly lines: readonly string[];
+}
+export interface CliDriftReportSeams {
+    readonly checkActiveCli?: (targetVersion: string) => ActiveCliCheckResult;
+    readonly viewPackage?: (name: WorkspacePackageName, version: string) => WorkspacePackageProbe;
+    readonly nowMs?: () => number;
+    readonly sleepMs?: (ms: number) => void;
+}
+export declare function remediationCommand(version: string): string;
+export declare function npmViewArgs(name: WorkspacePackageName, version: string): string[];
+export declare function defaultViewWorkspacePackage(name: WorkspacePackageName, version: string): WorkspacePackageProbe;
+export declare function classifyRegistryVisibility(opts: {
+    readonly probes: readonly WorkspacePackageProbe[];
+    readonly waitExhausted: boolean;
+    readonly skipped: boolean;
+}): RegistryVisibility;
+export declare function pollWorkspacePackages(version: string, opts: {
+    readonly timeoutMs: number;
+    readonly intervalMs?: number;
+    readonly viewPackage: (name: WorkspacePackageName, version: string) => WorkspacePackageProbe;
+    readonly nowMs?: () => number;
+    readonly sleepMs?: (ms: number) => void;
+}): {
+    readonly probes: readonly WorkspacePackageProbe[];
+    readonly waitExhausted: boolean;
+};
+export declare function shouldSkipRegistryPoll(config: Pick<ReleaseConfig, "dryRun" | "skipTag" | "version">, env?: NodeJS.ProcessEnv): boolean;
+export declare function buildCliDriftReport(releasedVersion: string, opts?: {
+    readonly skipRegistryPoll: boolean;
+    readonly pollTimeoutMs?: number;
+    readonly pollIntervalMs?: number;
+} & CliDriftReportSeams): CliDriftReport;
+export declare function formatCliDriftReport(report: CliDriftReport): string;
+/** Best-effort wrapper — a report failure must never fail the cut. */
+export declare function emitCliDriftReportBestEffort(releasedVersion: string, opts: Parameters<typeof buildCliDriftReport>[1], write?: (text: string) => void): void;
+//# sourceMappingURL=cli-drift-report.d.ts.map

package/dist/release/cli-drift-report.js

@@ -0,0 +1,189 @@
+/**
+ * Local-vs-released CLI drift report after a cut (#3753).
+ *
+ * Report-only: never runs `npm i -g`. Never fails the release. Polls all four
+ * workspace packages with `--prefer-online` so a lag-poisoned npm cache cannot
+ * masquerade as a missing publish.
+ */
+import { spawnSync } from "node:child_process";
+import { PUBLIC_NPM_REGISTRY } from "../doctor/constants.js";
+import { checkActiveCliAgainstTarget } from "../session/active-cli.js";
+import { RELEASE_E2E_ENV } from "./skip-ci-incident.js";
+/** Same sentinel as release-e2e `REHEARSAL_VERSION` — do not poll npm for 0.0.1. */
+const REHEARSAL_VERSION = "0.0.1";
+/** Workspace packages published by npm-publish.yml (sibling propagate is not atomic). */
+export const WORKSPACE_PACKAGES = [
+    "@deftai/directive-types",
+    "@deftai/directive-core",
+    "@deftai/directive-content",
+    "@deftai/directive",
+];
+/** Observed sibling lag was ~7 minutes; Phase 7 wait sits under this ceiling. */
+export const CLI_DRIFT_POLL_TIMEOUT_MS = 10 * 60 * 1000;
+export const CLI_DRIFT_POLL_INTERVAL_MS = 30_000;
+/** Pipeline completion is a single probe — Step 13 returns before npm-publish.yml is green. */
+export const CLI_DRIFT_PIPELINE_POLL_TIMEOUT_MS = 0;
+export function remediationCommand(version) {
+    return `npm i -g @deftai/directive@${version} --prefer-online`;
+}
+export function npmViewArgs(name, version) {
+    return [
+        "view",
+        `${name}@${version}`,
+        "version",
+        "--prefer-online",
+        "--ignore-scripts",
+        `--registry=${PUBLIC_NPM_REGISTRY}`,
+    ];
+}
+export function defaultViewWorkspacePackage(name, version) {
+    try {
+        const result = spawnSync("npm", npmViewArgs(name, version), {
+            encoding: "utf8",
+            timeout: 15_000,
+            stdio: ["ignore", "pipe", "pipe"],
+            windowsHide: true,
+        });
+        const raw = typeof result.stdout === "string" ? result.stdout : "";
+        const seen = raw.trim().split(/\r?\n/)[0]?.trim() ?? "";
+        const visible = result.status === 0 && seen === version;
+        return { name, visible, version: seen.length > 0 ? seen : null };
+    }
+    catch {
+        return { name, visible: false, version: null };
+    }
+}
+export function classifyRegistryVisibility(opts) {
+    if (opts.skipped)
+        return "skipped";
+    const visibleCount = opts.probes.filter((p) => p.visible).length;
+    if (opts.probes.length > 0 && visibleCount === opts.probes.length)
+        return "all-visible";
+    if (visibleCount === 0 && opts.waitExhausted)
+        return "publish-incomplete";
+    return "still-propagating";
+}
+export function pollWorkspacePackages(version, opts) {
+    const now = opts.nowMs ?? Date.now;
+    const sleep = opts.sleepMs ?? (() => undefined);
+    const interval = opts.intervalMs ?? CLI_DRIFT_POLL_INTERVAL_MS;
+    const start = now();
+    let probes = WORKSPACE_PACKAGES.map((name) => opts.viewPackage(name, version));
+    if (probes.every((p) => p.visible)) {
+        return { probes, waitExhausted: false };
+    }
+    if (opts.timeoutMs <= 0) {
+        return { probes, waitExhausted: false };
+    }
+    while (now() - start < opts.timeoutMs) {
+        const remaining = opts.timeoutMs - (now() - start);
+        if (remaining <= 0)
+            break;
+        sleep(Math.min(interval, remaining));
+        probes = WORKSPACE_PACKAGES.map((name) => opts.viewPackage(name, version));
+        if (probes.every((p) => p.visible)) {
+            return { probes, waitExhausted: false };
+        }
+    }
+    return { probes, waitExhausted: true };
+}
+export function shouldSkipRegistryPoll(config, env = process.env) {
+    if (config.dryRun || config.skipTag)
+        return true;
+    if (config.version === REHEARSAL_VERSION)
+        return true;
+    if (env[RELEASE_E2E_ENV])
+        return true;
+    if (env.CI === "true" || env.GITHUB_ACTIONS === "true")
+        return true;
+    // Unit tests never probe the live registry; production `task release` does not set VITEST.
+    if (env.VITEST)
+        return true;
+    return false;
+}
+function formatRegistryLine(registry, packages) {
+    if (registry === "skipped") {
+        return "  registry: skipped (dry-run / skip-tag / rehearsal / CI — no publish to poll)";
+    }
+    const visible = packages.filter((p) => p.visible).map((p) => p.name);
+    const missing = packages.filter((p) => !p.visible).map((p) => p.name);
+    const counts = `visible ${visible.length}/${packages.length}`;
+    if (registry === "all-visible") {
+        return `  registry: all-visible (${counts})`;
+    }
+    if (registry === "publish-incomplete") {
+        return `  registry: publish-incomplete (${counts}; none of the four packages resolved after the wait)`;
+    }
+    const missingText = missing.length > 0 ? `; missing: ${missing.join(", ")}` : "";
+    return `  registry: still-propagating (${counts}${missingText})`;
+}
+export function buildCliDriftReport(releasedVersion, opts = { skipRegistryPoll: false }) {
+    const check = opts.checkActiveCli ?? ((target) => checkActiveCliAgainstTarget(target));
+    const cli = check(releasedVersion);
+    const localVersion = cli.active?.version ?? null;
+    const localPath = cli.active?.path ?? null;
+    const match = localVersion !== null && localVersion === releasedVersion && cli.ok;
+    const shadowed = !cli.ok && cli.candidates.length > 0;
+    let packages = [];
+    let waitExhausted = false;
+    if (!opts.skipRegistryPoll) {
+        const view = opts.viewPackage ?? defaultViewWorkspacePackage;
+        const polled = pollWorkspacePackages(releasedVersion, {
+            timeoutMs: opts.pollTimeoutMs ?? CLI_DRIFT_PIPELINE_POLL_TIMEOUT_MS,
+            intervalMs: opts.pollIntervalMs,
+            viewPackage: view,
+            nowMs: opts.nowMs,
+            sleepMs: opts.sleepMs,
+        });
+        packages = polled.probes;
+        waitExhausted = polled.waitExhausted;
+    }
+    const registry = classifyRegistryVisibility({
+        probes: packages,
+        waitExhausted,
+        skipped: opts.skipRegistryPoll,
+    });
+    const remediation = remediationCommand(releasedVersion);
+    const localLabel = localVersion === null
+        ? "none on PATH"
+        : `${localVersion}${localPath !== null ? ` (${localPath})` : ""}`;
+    const lines = [
+        "CLI drift report (#3753):",
+        `  released: ${releasedVersion}`,
+        `  local global CLI: ${localLabel}`,
+        `  match: ${match ? "yes" : "no"}`,
+        ...(shadowed
+            ? ["  note: PATH-shadowed install — bare deft --version is not sufficient (#3233)"]
+            : []),
+        formatRegistryLine(registry, packages),
+        `  remediation: ${remediation}`,
+        "  note: report-only — this pipeline does not run npm i -g",
+    ];
+    return {
+        releasedVersion,
+        localVersion,
+        localPath,
+        match,
+        shadowed,
+        registry,
+        packages,
+        remediation,
+        lines,
+    };
+}
+export function formatCliDriftReport(report) {
+    return `${report.lines.join("\n")}\n`;
+}
+/** Best-effort wrapper — a report failure must never fail the cut. */
+export function emitCliDriftReportBestEffort(releasedVersion, opts, write = (text) => {
+    process.stderr.write(text);
+}) {
+    try {
+        write(formatCliDriftReport(buildCliDriftReport(releasedVersion, opts)));
+    }
+    catch (err) {
+        const reason = err instanceof Error ? err.message : String(err);
+        write(`CLI drift report (#3753): skipped (${reason.replace(/\r?\n/g, " ")})\n`);
+    }
+}
+//# sourceMappingURL=cli-drift-report.js.map

package/dist/release/index.d.ts

@@ -1,5 +1,6 @@
 export * from "./auto-hatch.js";
 export * from "./build-dist.js";
+export * from "./cli-drift-report.js";
 export * from "./closed-verb-gate.js";
 export * from "./constants.js";
 export * from "./coverage-debt-ledger.js";

package/dist/release/index.js

@@ -1,6 +1,7 @@
 /* v8 ignore file -- re-export barrel; covered via main.ts */
 export * from "./auto-hatch.js";
 export * from "./build-dist.js";
+export * from "./cli-drift-report.js";
 export * from "./closed-verb-gate.js";
 export * from "./constants.js";
 export * from "./coverage-debt-ledger.js";

package/dist/release/issue-state-fetch.d.ts

@@ -1,4 +1,4 @@
-import { type FetchIssueStatesOptions } from "../intake/reconcile-issues.js";
+import { IssueState } from "../intake/reconcile-issues.js";
 import { type CallOptions, type CompletedProcess } from "../scm/call.js";
 export type ScmCallFn = (source: string, verb: string, args: readonly string[] | null, options?: CallOptions) => CompletedProcess;
 /** Max seconds to sleep before the single rate-limit retry (operator-locked cap). */
@@ -9,13 +9,15 @@ export interface RateLimitProbe {
     readonly coreResetUnix: number | null;
     readonly graphqlRemaining: number | null;
 }
-export interface FetchIssueStatesForReleaseOptions extends FetchIssueStatesOptions {
+export interface FetchIssueStatesForReleaseOptions {
+    readonly cwd?: string;
+    readonly scmCall?: ScmCallFn;
     readonly sleep?: SleepFn;
     readonly now?: () => number;
 }
 export type FetchIssueStatesForReleaseResult = {
     readonly ok: true;
-    readonly states: Map<number, import("../intake/reconcile-issues.js").IssueState>;
+    readonly states: Map<number, IssueState>;
 } | {
     readonly ok: false;
     readonly reason: string;

package/dist/release/issue-state-fetch.js

@@ -1,9 +1,11 @@
 /**
  * Release Step 3 issue-state fetch with capped rate-limit retry (#2577).
+ * Open-issue inventory via one paginated REST subprocess (#3752).
  */
 import { detectRateLimit } from "../cache/fetch.js";
-import { fetchIssueStates } from "../intake/reconcile-issues.js";
+import { IssueState } from "../intake/reconcile-issues.js";
 import { call } from "../scm/call.js";
+import { GhRestError, restIssueListOpenInventory } from "../scm/gh-rest.js";
 /** Max seconds to sleep before the single rate-limit retry (operator-locked cap). */
 export const MAX_RATE_LIMIT_RETRY_SLEEP_S = 120;
 const X_RATE_LIMIT_RESET_RE = /X-RateLimit-Reset:\s*(\d+)/i;
@@ -15,6 +17,71 @@ function defaultSleep(seconds) {
     const shared = new Int32Array(new SharedArrayBuffer(4));
     Atomics.wait(shared, 0, 0, ms);
 }
+function scmCallToRunGhApi(scmCall, cwd) {
+    return (args, options) => {
+        const result = scmCall("github-issue", "api", args, {
+            timeout: options?.timeout ?? 120,
+            cwd,
+        });
+        return {
+            returncode: result.returncode,
+            stdout: result.stdout,
+            stderr: result.stderr,
+        };
+    };
+}
+function buildStatesFromOpenInventory(issueNumbers, openInventory) {
+    const openNumbers = new Set();
+    for (const row of openInventory) {
+        const n = row.number;
+        if (typeof n === "number" && Number.isInteger(n)) {
+            openNumbers.add(n);
+        }
+    }
+    const states = new Map();
+    for (const n of [...issueNumbers].sort((a, b) => a - b)) {
+        states.set(n, openNumbers.has(n) ? new IssueState("OPEN") : new IssueState("NOT_FOUND"));
+    }
+    return states;
+}
+function fetchOpenInventoryAttempt(repo, runGhApiFn) {
+    let sawRateLimit = false;
+    let rateLimitStderr = "";
+    const trackingFn = (args, options) => {
+        const result = runGhApiFn(args, options);
+        if (result.returncode !== 0 && detectRateLimit(result.stderr)[0]) {
+            sawRateLimit = true;
+            rateLimitStderr = result.stderr;
+        }
+        return result;
+    };
+    try {
+        return {
+            inventory: restIssueListOpenInventory(repo, { runGhApiFn: trackingFn }),
+            sawRateLimit,
+            rateLimitStderr,
+            failureReason: null,
+        };
+    }
+    catch (err) {
+        const stderr = err instanceof GhRestError ? err.stderr : "";
+        if (stderr.length > 0 && detectRateLimit(stderr)[0]) {
+            sawRateLimit = true;
+            rateLimitStderr = stderr;
+        }
+        const reason = err instanceof GhRestError
+            ? `open-issue inventory fetch failed: ${err.message}`
+            : err instanceof Error
+                ? err.message
+                : String(err);
+        return {
+            inventory: null,
+            sawRateLimit,
+            rateLimitStderr,
+            failureReason: reason,
+        };
+    }
+}
 function parseRateLimitProbe(stdout) {
     try {
         const body = JSON.parse(stdout);
@@ -101,37 +168,34 @@ export function formatRateLimitFailureDetails(probe, rateLimitRelated) {
     return lines.join("\n");
 }
 export function fetchIssueStatesForRelease(repo, issueNumbers, options = {}) {
+    if (issueNumbers.size === 0) {
+        return { ok: true, states: new Map() };
+    }
+    process.stderr.write(`[release Step 3] checking ${issueNumbers.size} unique anchored issue(s) via open-issue inventory\n`);
     const sleepFn = options.sleep ?? defaultSleep;
     const nowFn = options.now ?? (() => Math.floor(Date.now() / 1000));
     const baseScmCall = options.scmCall ?? call;
     const cwd = options.cwd ?? undefined;
-    let sawRateLimit = false;
-    let lastRateLimitStderr = "";
-    const trackingScmCall = (source, verb, args, callOptions) => {
-        const result = baseScmCall(source, verb, args, callOptions);
-        if (result.returncode !== 0 && detectRateLimit(result.stderr)[0]) {
-            sawRateLimit = true;
-            lastRateLimitStderr = result.stderr;
-        }
-        return result;
+    const runGhApiFn = scmCallToRunGhApi(baseScmCall, cwd);
+    const finishSuccess = (inventory) => {
+        process.stderr.write(`[release Step 3] open-issue inventory: ${inventory.length} open issue(s)\n`);
+        return { ok: true, states: buildStatesFromOpenInventory(issueNumbers, inventory) };
     };
-    let states = fetchIssueStates(repo, issueNumbers, { ...options, scmCall: trackingScmCall });
-    if (states !== null) {
-        return { ok: true, states };
+    let attempt = fetchOpenInventoryAttempt(repo, runGhApiFn);
+    if (attempt.inventory !== null) {
+        return finishSuccess(attempt.inventory);
     }
-    if (sawRateLimit) {
+    if (attempt.sawRateLimit) {
         const probe = probeGithubRateLimit(baseScmCall, cwd);
-        const sleepS = computeRateLimitSleepSeconds(lastRateLimitStderr, probe, nowFn());
+        const sleepS = computeRateLimitSleepSeconds(attempt.rateLimitStderr, probe, nowFn());
         process.stderr.write(`[release Step 3] GitHub REST rate limit hit; sleeping ${sleepS}s before one retry\n`);
         sleepFn(sleepS);
-        sawRateLimit = false;
-        lastRateLimitStderr = "";
-        states = fetchIssueStates(repo, issueNumbers, { ...options, scmCall: trackingScmCall });
-        if (states !== null) {
-            return { ok: true, states };
+        attempt = fetchOpenInventoryAttempt(repo, runGhApiFn);
+        if (attempt.inventory !== null) {
+            return finishSuccess(attempt.inventory);
         }
     }
-    const rateLimitRelated = sawRateLimit || lastRateLimitStderr.length > 0;
+    const rateLimitRelated = attempt.sawRateLimit || attempt.rateLimitStderr.length > 0;
     if (rateLimitRelated) {
         const probe = probeGithubRateLimit(baseScmCall, cwd);
         const details = formatRateLimitFailureDetails(probe, true);
@@ -141,6 +205,7 @@ export function fetchIssueStatesForRelease(repo, issueNumbers, options = {}) {
             reason: "GitHub REST rate limit exhausted (see stderr for recovery steps)",
         };
     }
+    process.stderr.write(`${attempt.failureReason ?? "open-issue inventory fetch failed"}\n`);
     return { ok: false, reason: "failed to fetch issue states from gh" };
 }
 //# sourceMappingURL=issue-state-fetch.js.map

package/dist/release/native-steps.js

@@ -43,6 +43,7 @@ export function checkVbriefLifecycleSyncNative(projectRoot, repo) {
                 anchorIssueNumbers.add(num);
             }
         }
+        process.stderr.write(`[release Step 3] ${anchors.length} lifecycle anchor(s), ${anchorIssueNumbers.size} unique issue number(s) to evaluate\n`);
         const fetchResult = fetchIssueStatesForRelease(repo, anchorIssueNumbers, {
             cwd: projectRoot,
         });

package/dist/release/pipeline.js

@@ -4,6 +4,7 @@ import { assertProjectionContained } from "../fs/projection-containment.js";
 import { readCoverageTotalsFromReport } from "../vitest-runner/coverage-debt.js";
 import { buildCoverageDebtIssueDraft, classifyStep5FailureWithFreshness, evaluateAutoHatch, formatAutoHatchBanner, parseExitCodeFromReason, reasonLooksLikeTimeout, } from "./auto-hatch.js";
 import { prependUpgradeBanner, promoteChangelog, sectionForVersion } from "./changelog.js";
+import { emitCliDriftReportBestEffort, shouldSkipRegistryPoll, } from "./cli-drift-report.js";
 import { assertTagPushClosedVerb } from "./closed-verb-gate.js";
 import { EXIT_CONFIG_ERROR, EXIT_OK, EXIT_VIOLATION, RELEASE_ARTIFACTS, RELEASE_CHECK_TIMEOUT_MINUTES, TOTAL_STEPS, VERIFY_DRAFT_INTERVAL_SECONDS, VERIFY_DRAFT_MAX_ATTEMPTS, } from "./constants.js";
 import { createCoverageDebtIssue, probeOpenCoverageDebtLedger } from "./coverage-debt-ledger.js";
@@ -472,6 +473,24 @@ export function runPipeline(config, seams = {}) {
         }
     }
     process.stderr.write(`Release v${version} pipeline complete (dry_run=${config.dryRun ? "True" : "False"}, skip_tag=${config.skipTag ? "True" : "False"}, skip_release=${config.skipRelease ? "True" : "False"}).\n`);
+    // #3753 — report-only. Never runs npm i -g. Never fails the cut.
+    // Single-shot registry probe (no wait): Step 13 returns before npm-publish.yml
+    // is green; Phase 7 of the release skill owns the bounded wait.
+    emitCliDriftReportBestEffort(version, {
+        skipRegistryPoll: shouldSkipRegistryPoll(config),
+        pollTimeoutMs: 0,
+        checkActiveCli: seams.checkActiveCli,
+        viewPackage: seams.viewWorkspacePackage
+            ? (name, ver) => {
+                const probe = seams.viewWorkspacePackage?.(name, ver);
+                return {
+                    name: name,
+                    visible: probe?.visible ?? false,
+                    version: probe?.version ?? null,
+                };
+            }
+            : undefined,
+    });
     return EXIT_OK;
 }
 //# sourceMappingURL=pipeline.js.map

package/dist/release/types.d.ts

@@ -89,5 +89,19 @@ export interface ReleaseSeams {
      * Tests inject `{}` so a host env bypass cannot leak into fail-closed cases.
      */
     readonly closedVerbEnv?: EnvMap;
+    /**
+     * #3753 — override the active-CLI probe used by the local-vs-released report.
+     * When omitted, production calls `checkActiveCliAgainstTarget`.
+     */
+    readonly checkActiveCli?: (targetVersion: string) => import("../session/active-cli.js").ActiveCliCheckResult;
+    /**
+     * #3753 — override one `npm view <pkg>@<ver> --prefer-online` (tests).
+     * When omitted, production spawns npm. Never used to install.
+     */
+    readonly viewWorkspacePackage?: (name: string, version: string) => {
+        readonly name: string;
+        readonly visible: boolean;
+        readonly version: string | null;
+    };
 }
 //# sourceMappingURL=types.d.ts.map

package/dist/render/constants.d.ts

@@ -13,8 +13,12 @@ export declare const DEFAULT_INCLUDE_SCOPES_MODE: "off";
 /** Lifecycle scope aggregation modes for rendered specs (#1566). */
 export type IncludeScopesMode = "off" | "current" | "all";
 export declare const LIFECYCLE_BUCKETS: ReadonlyArray<readonly [string, string]>;
+/** Build a specification banner from the actual specification artifact path. */
+export declare function buildSpecRenderBanner(specPath: string): string;
 export declare const SPEC_RENDER_BANNER: string;
 export declare const PRD_NARRATIVE_KEY_ORDER: readonly ["Overview", "ProblemStatement", "Goals", "UserStories", "Requirements", "SuccessMetrics", "Architecture"];
+/** Build a PRD banner from the actual resolved authority path. */
+export declare function buildPrdBanner(sourcePath: string): string;
 export declare const PRD_BANNER: string;
 export declare const PRD_GENERATED_SENTINEL = "AUTO-GENERATED by task prd:render";
 /** Max completed scopes listed under ## Completed in ROADMAP.md (#2653). */