release-skill 0.2.6 → 0.2.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "release-skill",
-  "version": "0.2.6",
+  "version": "0.2.7",
   "description": "Safe preparation and frozen GitHub/npm production publishing with full happy end verification",
   "author": {
     "name": "广州市风荷科技有限公司"

package/skills/release-prepare/SKILL.md

@@ -36,6 +36,10 @@ description: Freeze an immutable release plan with local configuration, document
 
 若用户明确要求 GitHub+npm 生产发布，加入 `--production`。该模式还会封存独立
 Git commit/tree 和 npm tarball，并把路径、SHA/integrity、branch/tag 写入计划。
+每个 npm tarball 在计划落盘前必须静态验证 `package.json` 的具体
+`bin`/`main`/`module`/`types`/`typings`/`exports` 入口均为 tarball 内普通文件；
+该门禁不依赖项目是否配置 `requiredPublicFiles` 或 `smokeBin`。通配符 exports 不做
+猜测展开；它与 fallback array 都属于首版最小边界外的阻断形态。
 每个 release unit 必须显式配置 `previousPublicBaseline`。只有确认不存在前序公开
 版本时用 `mode: none`；已有版本必须用 `mode: bound` + 精确 repo/ref/commit，并以
 `--online --production` 逐 unit 观察 ref→commit mapping。默认 observer 不下载远端
@@ -79,6 +83,7 @@ node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" prepare --root <path> --offli
 | GATE_FAILED (gate 授权) | 向用户展示 snapshot gate 命令和风险，获得授权后加 `--acknowledge-gate-side-effects` 重试 |
 | GATE_FAILED (bound + offline) | 改用 `--online --production`，不得把 unobserved-offline plan 交给 publish |
 | GATE_FAILED (前序基线漂移) | 先取得并比较实际远端内容；人工选择 merge/adopt/reject。merge/adopt 都必须把接受内容落回 human-owned 权威源，并把 `previousPublicBaseline` 更新为接受状态的精确 repo/ref/commit 后重新 online production prepare；reject 停止调查，禁止改 `mode: none` 绕过 |
+| GATE_FAILED (`npm-entry-closure`) | 修复打包内容或入口声明后重新 prepare；不得用 `requiredPublicFiles`/`smokeBin` 缺省绕过 |
 | GATE_FAILED (其他) | 修复门失败原因后重试；以 CLI exit code 为准 |
 | RELEASE_DOCS_STALE | 文档相对说明源已陈旧；按详情运行只读演练，展示文件/语种/版本/摘要，经用户授权“本地发布文档写入”后执行写入，审阅提交再重新 prepare |
 | RELEASE_DOCS_INVALID / TRANSLATION_MISSING / CONFLICT / REFRESH_STALE | 修复配置/说明源/目标或重新演练取得新 `refreshDigest`；不得扩大写入范围绕过 |

package/skills/release-setup/SKILL.md

@@ -14,6 +14,9 @@ description: "首次接入 release-skill：只读发现发布单元与个性化
 - 默认只读。README、slogan、CHANGELOG、业务脚本和已有配置均为人工权威内容，不得重写或覆盖。
 - 发现脚本不等于选择或授权。间接脚本以 `SIDE_EFFECTS_UNPROVEN` 排除；项目特有 hook/gate 只能人工增量注册。
 - 仓库、公开文件等证据冲突时停止自动提案，交给人工修正权威事实后重新发现。
+- npm 单元只读提取 `package.json` 的具体入口和旧 `npmRequiredPackagePaths`，报告
+  tracked/untracked/ignored/missing/non-regular 状态与覆盖漂移；这些是人工复核候选，
+  不得自动写入 `publicFiles` 或 `requiredPublicFiles`。
 - 写入只允许 create-once（仅创建一次），必须同时提供 answers 与精确 `setupDigest`；无安全原生写入能力时失败关闭。
 - Agent 的多次 shell 调用彼此独立；只能用首轮打印的会话目录绝对路径续接，不得假设变量仍存在。
 
@@ -43,7 +46,13 @@ node -e 'const fs=require("node:fs");const r=JSON.parse(fs.readFileSync(process.
 node -e 'const fs=require("node:fs");const r=JSON.parse(fs.readFileSync(process.argv[1],"utf8"));if((r.proposalConflicts??[]).length){console.error("proposal conflicts require human resolution");process.exit(2)}if(!r.recommendedAnswers){console.error("recommendedAnswers missing");process.exit(2)}fs.writeFileSync(process.argv[2],JSON.stringify(r.recommendedAnswers,null,2)+"\n",{flag:"wx",mode:0o600})' "$REPORT" "$ANSWERS"
 ```
 
-若 `proposalConflicts` 非空，暂停，让用户修正仓库/映射权威事实，删除本会话目录后从第 2 步重跑，不得猜测选边。无冲突时可人工增量编辑 `answers.json`：hook 写入 `recommendedAnswers.projectConfig.hooks` 对应的 `projectConfig.hooks`；gate 写入 `verificationGates`，并把同一 id 加入 `selectedGateIds`。人工文件保持 `mode: preserve`，跨单元共享源使用 `sourceScope: workspace`。
+若 `proposalConflicts` 非空，暂停，让用户修正仓库/映射权威事实或 npm 入口候选，
+删除本会话目录后从第 2 步重跑，不得猜测选边。构建后才产生且被忽略的入口应先由
+人工确认构建流程与最终 tarball 边界，不能因为 setup 发现了路径就自动信任或纳入公开
+配置。无冲突时可人工增量编辑 `answers.json`：hook 写入
+`recommendedAnswers.projectConfig.hooks` 对应的 `projectConfig.hooks`；gate 写入
+`verificationGates`，并把同一 id 加入 `selectedGateIds`。人工文件保持
+`mode: preserve`，跨单元共享源使用 `sourceScope: workspace`。
 
 3. 使用上一步打印的两个绝对字面量重新赋值，运行绑定 dry-run；任何人工编辑后都必须重跑本步：
 

package/skills/release-verify/SKILL.md

@@ -17,7 +17,7 @@ verify 只接受 `PUBLISHED` 状态的源 run；`VERIFIED` 是终态，不会再
 
 ## 职责与边界
 
-验证远端所有 action 的实际状态与冻结计划一致。执行精确 `<package>@<version>` npm 安装到隔离目录，验证包名、版本、bin 路径安全和 CLI 烟雾输出。对每个声明的 marketplace distribution 执行全新隔离消费者安装验证。
+验证远端所有 action 的实际状态与冻结计划一致。执行精确 `<package>@<version>` npm 安装到隔离目录，验证包名、版本、静态入口闭包，并在配置时验证 bin 路径安全和 CLI 烟雾输出。对每个声明的 marketplace distribution 执行全新隔离消费者安装验证。
 
 **阶段通过规则**: 只有 CLI exit code 0 和结构化状态码 `VERIFIED` 才是完整终态。
 
@@ -55,8 +55,10 @@ node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" verify --root <path> --plan <
 - 在 `os.tmpdir()` 创建隔离目录
 - 执行 `npm install <package>@<version>` 带安全标志
 - 验证安装的 `package.json` name 和 version 精确匹配
+- 无条件静态验证已安装包中具体 `bin`/`main`/`module`/`types`/`typings`/`exports`
+  目标是普通文件；失败时不得写入 `VERIFIED`
 - 若配置了 `smokeBin`：验证 bin 路径安全（无逃逸、无 symlink），从精确安装根、隔离 HOME 和最小环境执行并验证输出；这会运行已安装代码，必须显式授权
-- 若未配置 `smokeBin`：仅安装 + name/version 检查即通过
+- 若未配置 `smokeBin`：跳过运行代码，但静态入口闭包检查仍然强制执行
 
 ## 常见错误
 

package/skills-src/release-prepare/SKILL.md

@@ -36,6 +36,10 @@ description: Freeze an immutable release plan with local configuration, document
 
 若用户明确要求 GitHub+npm 生产发布，加入 `--production`。该模式还会封存独立
 Git commit/tree 和 npm tarball，并把路径、SHA/integrity、branch/tag 写入计划。
+每个 npm tarball 在计划落盘前必须静态验证 `package.json` 的具体
+`bin`/`main`/`module`/`types`/`typings`/`exports` 入口均为 tarball 内普通文件；
+该门禁不依赖项目是否配置 `requiredPublicFiles` 或 `smokeBin`。通配符 exports 不做
+猜测展开；它与 fallback array 都属于首版最小边界外的阻断形态。
 每个 release unit 必须显式配置 `previousPublicBaseline`。只有确认不存在前序公开
 版本时用 `mode: none`；已有版本必须用 `mode: bound` + 精确 repo/ref/commit，并以
 `--online --production` 逐 unit 观察 ref→commit mapping。默认 observer 不下载远端
@@ -79,6 +83,7 @@ node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" prepare --root <path> --offli
 | GATE_FAILED (gate 授权) | 向用户展示 snapshot gate 命令和风险，获得授权后加 `--acknowledge-gate-side-effects` 重试 |
 | GATE_FAILED (bound + offline) | 改用 `--online --production`，不得把 unobserved-offline plan 交给 publish |
 | GATE_FAILED (前序基线漂移) | 先取得并比较实际远端内容；人工选择 merge/adopt/reject。merge/adopt 都必须把接受内容落回 human-owned 权威源，并把 `previousPublicBaseline` 更新为接受状态的精确 repo/ref/commit 后重新 online production prepare；reject 停止调查，禁止改 `mode: none` 绕过 |
+| GATE_FAILED (`npm-entry-closure`) | 修复打包内容或入口声明后重新 prepare；不得用 `requiredPublicFiles`/`smokeBin` 缺省绕过 |
 | GATE_FAILED (其他) | 修复门失败原因后重试；以 CLI exit code 为准 |
 | RELEASE_DOCS_STALE | 文档相对说明源已陈旧；按详情运行只读演练，展示文件/语种/版本/摘要，经用户授权“本地发布文档写入”后执行写入，审阅提交再重新 prepare |
 | RELEASE_DOCS_INVALID / TRANSLATION_MISSING / CONFLICT / REFRESH_STALE | 修复配置/说明源/目标或重新演练取得新 `refreshDigest`；不得扩大写入范围绕过 |

package/skills-src/release-setup/SKILL.md

@@ -14,6 +14,9 @@ description: "首次接入 release-skill：只读发现发布单元与个性化
 - 默认只读。README、slogan、CHANGELOG、业务脚本和已有配置均为人工权威内容，不得重写或覆盖。
 - 发现脚本不等于选择或授权。间接脚本以 `SIDE_EFFECTS_UNPROVEN` 排除；项目特有 hook/gate 只能人工增量注册。
 - 仓库、公开文件等证据冲突时停止自动提案，交给人工修正权威事实后重新发现。
+- npm 单元只读提取 `package.json` 的具体入口和旧 `npmRequiredPackagePaths`，报告
+  tracked/untracked/ignored/missing/non-regular 状态与覆盖漂移；这些是人工复核候选，
+  不得自动写入 `publicFiles` 或 `requiredPublicFiles`。
 - 写入只允许 create-once（仅创建一次），必须同时提供 answers 与精确 `setupDigest`；无安全原生写入能力时失败关闭。
 - Agent 的多次 shell 调用彼此独立；只能用首轮打印的会话目录绝对路径续接，不得假设变量仍存在。
 
@@ -43,7 +46,13 @@ node -e 'const fs=require("node:fs");const r=JSON.parse(fs.readFileSync(process.
 node -e 'const fs=require("node:fs");const r=JSON.parse(fs.readFileSync(process.argv[1],"utf8"));if((r.proposalConflicts??[]).length){console.error("proposal conflicts require human resolution");process.exit(2)}if(!r.recommendedAnswers){console.error("recommendedAnswers missing");process.exit(2)}fs.writeFileSync(process.argv[2],JSON.stringify(r.recommendedAnswers,null,2)+"\n",{flag:"wx",mode:0o600})' "$REPORT" "$ANSWERS"
 ```
 
-若 `proposalConflicts` 非空，暂停，让用户修正仓库/映射权威事实，删除本会话目录后从第 2 步重跑，不得猜测选边。无冲突时可人工增量编辑 `answers.json`：hook 写入 `recommendedAnswers.projectConfig.hooks` 对应的 `projectConfig.hooks`；gate 写入 `verificationGates`，并把同一 id 加入 `selectedGateIds`。人工文件保持 `mode: preserve`，跨单元共享源使用 `sourceScope: workspace`。
+若 `proposalConflicts` 非空，暂停，让用户修正仓库/映射权威事实或 npm 入口候选，
+删除本会话目录后从第 2 步重跑，不得猜测选边。构建后才产生且被忽略的入口应先由
+人工确认构建流程与最终 tarball 边界，不能因为 setup 发现了路径就自动信任或纳入公开
+配置。无冲突时可人工增量编辑 `answers.json`：hook 写入
+`recommendedAnswers.projectConfig.hooks` 对应的 `projectConfig.hooks`；gate 写入
+`verificationGates`，并把同一 id 加入 `selectedGateIds`。人工文件保持
+`mode: preserve`，跨单元共享源使用 `sourceScope: workspace`。
 
 3. 使用上一步打印的两个绝对字面量重新赋值，运行绑定 dry-run；任何人工编辑后都必须重跑本步：
 

package/skills-src/release-verify/SKILL.md

@@ -17,7 +17,7 @@ verify 只接受 `PUBLISHED` 状态的源 run；`VERIFIED` 是终态，不会再
 
 ## 职责与边界
 
-验证远端所有 action 的实际状态与冻结计划一致。执行精确 `<package>@<version>` npm 安装到隔离目录，验证包名、版本、bin 路径安全和 CLI 烟雾输出。对每个声明的 marketplace distribution 执行全新隔离消费者安装验证。
+验证远端所有 action 的实际状态与冻结计划一致。执行精确 `<package>@<version>` npm 安装到隔离目录，验证包名、版本、静态入口闭包，并在配置时验证 bin 路径安全和 CLI 烟雾输出。对每个声明的 marketplace distribution 执行全新隔离消费者安装验证。
 
 **阶段通过规则**: 只有 CLI exit code 0 和结构化状态码 `VERIFIED` 才是完整终态。
 
@@ -55,8 +55,10 @@ node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" verify --root <path> --plan <
 - 在 `os.tmpdir()` 创建隔离目录
 - 执行 `npm install <package>@<version>` 带安全标志
 - 验证安装的 `package.json` name 和 version 精确匹配
+- 无条件静态验证已安装包中具体 `bin`/`main`/`module`/`types`/`typings`/`exports`
+  目标是普通文件；失败时不得写入 `VERIFIED`
 - 若配置了 `smokeBin`：验证 bin 路径安全（无逃逸、无 symlink），从精确安装根、隔离 HOME 和最小环境执行并验证输出；这会运行已安装代码，必须显式授权
-- 若未配置 `smokeBin`：仅安装 + name/version 检查即通过
+- 若未配置 `smokeBin`：跳过运行代码，但静态入口闭包检查仍然强制执行
 
 ## 常见错误
 

package/src/adapters/npm.mjs

@@ -16,6 +16,11 @@ import {
   createResult,
   matchObservation,
 } from './contract.mjs';
+import {
+  checkNpmEntryClosure,
+  buildTarballFileIndex,
+} from '../npm/npm-entry-closure.mjs';
+import { ReleaseError, GATE_FAILED } from '../core/errors.mjs';
 
 const execFile = promisify(execFileCb);
 const NAME = 'npm';
@@ -349,6 +354,53 @@ export async function verifyFrozenNpmTarballIdentity(action, root) {
   });
 }
 
+async function verifyNpmTarballBufferContract(buffer, action, tarballDir) {
+  const manifest = extractManifestFromTarball(buffer, {
+    name: action.package,
+    version: action.version,
+  });
+  const fileIndex = await buildTarballFileIndex(buffer, tarballDir);
+  const closureResult = checkNpmEntryClosure(manifest, fileIndex);
+  if (closureResult.errors.length > 0) {
+    throw new ReleaseError(
+      GATE_FAILED,
+      `npm entry closure check failed for ${action.package}@${action.version}: ${closureResult.errors.length} error(s)`,
+      {
+        gate: 'npm-entry-closure',
+        package: action.package,
+        version: action.version,
+        entries: closureResult.entries,
+        errors: closureResult.errors,
+        diagnostics: closureResult.diagnostics,
+      },
+    );
+  }
+  return { manifest, closureResult };
+}
+
+/**
+ * Shared frozen tarball contract helper: reads the verified tarball bytes ONCE
+ * and performs both identity verification (name/version from manifest) and
+ * entry closure validation (bin/main/module/types/typings/exports targets
+ * exist as regular files inside the tarball).
+ *
+ * The same Buffer that passes `readVerifiedTarballBytes` is reused for both
+ * the existing identity reader and the controlled extraction/file-index
+ * boundary. This adds no new tar parser and performs no second source read.
+ *
+ * @param {object} action - The frozen action with tarballPath, tarballSha256,
+ *   integrity, package, and version.
+ * @param {string} root - Absolute project root.
+ * @param {string} [tarballDir] - Temp directory for tar extraction (defaults to os.tmpdir()).
+ * @returns {Promise<{ manifest: object, closureResult: object }>}
+ * @throws {ReleaseError} GATE_FAILED with details.gate='npm-entry-closure'
+ *   when any declared entry is missing or invalid.
+ */
+export async function verifyFrozenNpmTarballContract(action, root, tarballDir) {
+  const buffer = await readVerifiedTarballBytes(action, root);
+  return verifyNpmTarballBufferContract(buffer, action, tarballDir);
+}
+
 /**
  * Read and verify the frozen tarball, then write it to a controlled named
  * temp file under a temp directory adjacent to the source. Returns the temp
@@ -700,7 +752,7 @@ export function createNpmAdapter(deps = {}) {
           }
           const cwd = resolvePackageCwd(action.cwd, context.root);
           if (action.tarballPath) {
-            await verifyFrozenNpmTarballIdentity(action, context.root);
+            await verifyFrozenNpmTarballContract(action, context.root);
           }
 
           let whoamiUser;
@@ -775,7 +827,7 @@ export function createNpmAdapter(deps = {}) {
             throw new Error('frozen npm tarball requires a stable Buffer publish capability');
           }
           const buffer = await readVerifiedTarballBytes(action, context.root);
-          const manifest = extractManifestFromTarball(buffer, { name: action.package, version: action.version });
+          const { manifest } = await verifyNpmTarballBufferContract(buffer, action);
           let token;
           try {
             token = await resolveAuthToken({ registry: normalizedRegistry, cwd, exec, env: authEnv });

package/src/adapters/plugin-marketplace.mjs

@@ -2393,7 +2393,7 @@ export function createPluginMarketplaceAdapter(deps = {}) {
 
           // A non-automatable platform (kimi) has NO scriptable install CLI.
           // It is handled entirely by its manual-requirement strategy, which
-          // uses a stable plan-digest-keyed home and deliberately SKIPS the
+          // uses a stable plugin-level authority directory and deliberately SKIPS the
           // per-run isolated consumer dir and its runDir containment check
           // (that model only fits structured-cli platforms, which exec a real
           // CLI into a per-run HOME).
@@ -2913,25 +2913,12 @@ export function createPluginMarketplaceAdapter(deps = {}) {
               });
             }
 
-            // installPath 验证：必须在 managed root 内，不得逃逸，不得是符号链接
+            // installPath 验证：必须是真实目录，不得是符号链接。
+            // 安装路径不要求位于 attestationDir 内（用户使用实际全局/用户安装目录）。
             let verifiedInstallPath = null;
             if (normalizedAttestation.installPath) {
-              const managedRoot = resolve(attestationDir, 'kimi-home', 'plugins', 'managed');
               const installPathAbs = resolve(normalizedAttestation.installPath);
 
-              // 先验证 managed root 存在（KIMI_CODE_HOME 检查）
-              const managedRootReal = await realpath(managedRoot).catch(() => null);
-              if (!managedRootReal) {
-                return createResult({
-                  actionType,
-                  status: ActionStatus.OBSERVED,
-                  observation: {
-                    installed: false,
-                    error: 'KIMI_CODE_HOME does not exist',
-                  },
-                });
-              }
-
               // 检查 installPath 词法路径是否存在（lstat 在 realpath 之前）
               let lexicalStat;
               try {
@@ -2968,18 +2955,6 @@ export function createPluginMarketplaceAdapter(deps = {}) {
                   },
                 });
               }
-              const rel = relative(managedRootReal, installPathReal);
-              const sep = process.platform === 'win32' ? '\\' : '/';
-              if (rel === '' || rel === '..' || isAbsolute(rel) || rel.startsWith(`..${sep}`)) {
-                return createResult({
-                  actionType,
-                  status: ActionStatus.OBSERVED,
-                  observation: {
-                    installed: false,
-                    error: `kimi attestation installPath escapes the managed root: ${normalizedAttestation.installPath}`,
-                  },
-                });
-              }
               verifiedInstallPath = installPathReal;
             }
 
@@ -3283,7 +3258,7 @@ export function createPluginMarketplaceAdapter(deps = {}) {
                 try {
                   codexRequirement = JSON.parse(await readFile(resolve(codexAttestationDir, CODEX_REQUIREMENT_FILE), 'utf8'));
                 } catch {
-                  // No requirement file — must not read isolated attestation
+                  // No requirement file — must not read the stable attestation
                 }
 
                 // Validate requirement binds to this action and plan (完整绑定验证)

package/src/commands/prepare.mjs

@@ -58,7 +58,7 @@ import {
 } from '../core/source-authority.mjs';
 import { acquireProjectLock } from '../artifacts/project-lock.mjs';
 import { assertPreviousPublicBaselineTarget, observePreviousPublicBaseline } from '../core/previous-public-baseline.mjs';
-import { verifyFrozenNpmTarballIdentity } from '../adapters/npm.mjs';
+import { verifyFrozenNpmTarballContract } from '../adapters/npm.mjs';
 import { createProductionPrepareRunDir } from '../core/run.mjs';
 import { PLATFORMS } from '../platforms/registry.mjs';
 import { validateMarketplaceSourceSelection, MARKETPLACE_SOURCE_TYPES, resolvePluginManifestFromMarketplaceEntrySource, resolveMarketplaceRoot } from '../adapters/plugin-marketplace.mjs';
@@ -930,13 +930,13 @@ async function buildProductionAssets(
         tarballDir: resolveUnitScopedPath(resolve(runDir, 'tarballs'), unit.id),
         expectedSnapshotDigest: sealed.digest,
       });
-      await verifyFrozenNpmTarballIdentity({
+      await verifyFrozenNpmTarballContract({
         package: npmDistribution.package,
         version,
         tarballPath: relative(root, npm.tarballPath),
         tarballSha256: npm.sha256,
         integrity: npm.integrity,
-      }, root);
+      }, root, resolveUnitScopedPath(resolve(runDir, 'tarballs'), unit.id));
     }
 
     assets.push({

package/src/commands/publish.mjs

@@ -77,7 +77,7 @@ import {
   verifyFrozenGitRepository,
   verifyFrozenSnapshot,
 } from '../snapshot/frozen.mjs';
-import { verifyFrozenNpmTarballIdentity } from '../adapters/npm.mjs';
+import { verifyFrozenNpmTarballContract } from '../adapters/npm.mjs';
 
 function assertInsideAssetRoot(assetRoot, candidate, label) {
   const rel = relative(assetRoot, candidate);
@@ -607,7 +607,7 @@ export async function publishRelease(options) {
           if (!npmDistribution) {
             throw new ReleaseError(GATE_FAILED, `unit "${unit.id}" has a frozen npm tarball but no npm distribution`);
           }
-          await verifyFrozenNpmTarballIdentity({
+          await verifyFrozenNpmTarballContract({
             package: npmDistribution.package,
             version: unit.targetVersion,
             tarballPath: frozen.npm.tarballPath,

package/src/commands/reconcile.mjs

@@ -62,6 +62,7 @@ import { assertTransition, PARTIAL, PUBLISHED, BLOCKED } from '../core/state-mac
 import { verifySourceAuthorityReceipt } from '../core/source-authority.mjs';
 import { matchObservation } from '../adapters/contract.mjs';
 import { observeWithRetry, clampPolicyToTimeout, DEFAULT_OBSERVE_RETRY_POLICY } from '../core/observe-retry.mjs';
+import { verifyFrozenNpmTarballContract } from '../adapters/npm.mjs';
 
 // ---------------------------------------------------------------------------
 // Constants
@@ -210,6 +211,44 @@ export async function reconcileRelease(options) {
 
     await evidence.append({ phase: 'safety-gate', gate: 'action-completeness', status: 'passed' });
 
+    // =======================================================================
+    // Safety Gate 2c: Unconditional frozen npm entry-closure recheck
+    // This is plan-global and intentionally precedes source-run observation:
+    // a previously consistent npm checkpoint must not exempt a bad frozen
+    // tarball while another action is being reconciled.
+    // =======================================================================
+    for (const unit of plan.units ?? []) {
+      const frozen = unit.frozenSnapshot;
+      if (!frozen?.npm) continue;
+      const npmDistribution = (unit.distributions ?? []).find((distribution) => distribution.type === 'npm');
+      if (!npmDistribution) {
+        throw new ReleaseError(
+          GATE_FAILED,
+          `unit "${unit.id}" has a frozen npm tarball but no npm distribution`,
+          { gate: 'npm-entry-closure', unitId: unit.id },
+        );
+      }
+      await evidence.append({
+        phase: 'safety-gate',
+        gate: 'npm-entry-closure',
+        unitId: unit.id,
+        status: 'started',
+      });
+      await verifyFrozenNpmTarballContract({
+        package: npmDistribution.package,
+        version: unit.targetVersion,
+        tarballPath: frozen.npm.tarballPath,
+        tarballSha256: frozen.npm.tarballSha256,
+        integrity: frozen.npm.integrity,
+      }, root);
+      await evidence.append({
+        phase: 'safety-gate',
+        gate: 'npm-entry-closure',
+        unitId: unit.id,
+        status: 'passed',
+      });
+    }
+
     // =======================================================================
     // Safety Gate 3: Load and validate source run
     // =======================================================================

package/src/commands/setup.mjs

@@ -24,6 +24,7 @@ import addFormats from 'ajv-formats';
 import { canonicalJson, sha256Hex } from '../core/digest.mjs';
 import { acquireProjectLock } from '../artifacts/project-lock.mjs';
 import { getPlatform, PLATFORMS } from '../platforms/registry.mjs';
+import { checkNpmEntryClosure } from '../npm/npm-entry-closure.mjs';
 import {
   CONFIG_EXISTS,
   CONFIG_INVALID,
@@ -201,6 +202,8 @@ function summarizeLegacyReleaseConfig(value, path) {
       tagPrefix: optionalString(repo.tagPrefix),
       npmPackage: optionalString(repo.npmPackage),
       npmPackageDeclared: Object.hasOwn(repo, 'npmPackage'),
+      npmRequiredPathCandidates: stringList(repo.npmRequiredPackagePaths),
+      npmRequiredPathsDeclared: Object.hasOwn(repo, 'npmRequiredPackagePaths'),
       docsSource: optionalString(repo.docsSource),
       requiredPathCandidates: stringList(repo.requiredPackagePaths),
       snapshotCommands: Array.isArray(repo.snapshotCommands) ? repo.snapshotCommands : [],
@@ -223,6 +226,8 @@ function summarizeLegacyReleaseConfig(value, path) {
       npmPackageDeclared: plugins.some((plugin) => (
         plugin && typeof plugin === 'object' && !Array.isArray(plugin) && Object.hasOwn(plugin, 'npmPackage')
       )),
+      npmRequiredPathCandidates: stringList(value.npmRequiredPackagePaths),
+      npmRequiredPathsDeclared: Object.hasOwn(value, 'npmRequiredPackagePaths'),
       docsSource: null,
       requiredPathCandidates: stringList(value.requiredPaths),
       snapshotCommands: Array.isArray(value.snapshotCommands) ? value.snapshotCommands : [],
@@ -467,6 +472,111 @@ async function discoverUnitGit(unitAbsDir, parentRoot) {
   };
 }
 
+async function pathIsGitIgnored(unitAbsDir, target) {
+  // --no-index also classifies generated paths that do not exist yet.
+  try {
+    await execFile('git', ['check-ignore', '--no-index', '--quiet', '--', target], {
+      cwd: unitAbsDir,
+      shell: false,
+      timeout: 5000,
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function classifyNpmEntryCandidate(unitAbsDir, target, trackedFiles) {
+  const tracked = trackedFiles.includes(target);
+  const ignored = await pathIsGitIgnored(unitAbsDir, target);
+  let stat = null;
+  try {
+    stat = await lstat(join(unitAbsDir, target));
+  } catch (error) {
+    if (error.code !== 'ENOENT') throw error;
+  }
+  const exists = stat !== null;
+  const regular = stat?.isFile() === true && stat?.isSymbolicLink() !== true;
+  const state = exists && !regular
+    ? 'NON_REGULAR'
+    : exists && tracked
+      ? 'TRACKED_PRESENT'
+      : exists && ignored
+        ? 'IGNORED_PRESENT'
+        : exists
+          ? 'UNTRACKED_PRESENT'
+          : ignored
+            ? 'IGNORED_MISSING'
+            : 'MISSING';
+  return { path: target, state, exists, tracked, ignored };
+}
+
+async function discoverNpmEntryCandidates(root, pkg, matchingLegacyUnits, unitGitEntry) {
+  const emptyIndex = new Map();
+  const semantic = checkNpmEntryClosure(pkg.entryManifest, emptyIndex);
+  const byPath = new Map();
+  const add = (target, source) => {
+    const current = byPath.get(target) ?? { path: target, sources: new Set() };
+    current.sources.add(source);
+    byPath.set(target, current);
+  };
+  for (const entry of semantic.entries) add(entry.target, `package.json:${entry.field}`);
+
+  const diagnostics = [
+    ...semantic.errors
+      .filter((error) => error.reason !== 'entry_missing')
+      .map((error) => ({ code: 'NPM_ENTRY_DECLARATION_INVALID', ...error })),
+    ...semantic.diagnostics.map((diagnostic) => ({
+      code: 'NPM_ENTRY_WILDCARD_REQUIRES_REVIEW',
+      ...diagnostic,
+    })),
+  ];
+  const declaredLegacyPaths = new Set();
+  const legacyCoverageDeclared = matchingLegacyUnits.some((unit) => unit.npmRequiredPathsDeclared);
+  for (const legacy of matchingLegacyUnits) {
+    for (const target of legacy.npmRequiredPathCandidates) {
+      const checked = checkNpmEntryClosure({ main: target }, emptyIndex);
+      const normalized = checked.entries[0]?.target;
+      if (!normalized) {
+        diagnostics.push({
+          code: 'LEGACY_NPM_REQUIRED_PATH_INVALID',
+          path: target,
+          reason: checked.errors[0]?.reason ?? 'invalid_path',
+        });
+        continue;
+      }
+      declaredLegacyPaths.add(normalized);
+      add(normalized, 'public-release.json:npmRequiredPackagePaths');
+    }
+  }
+  if (legacyCoverageDeclared) {
+    for (const entry of semantic.entries) {
+      if (!declaredLegacyPaths.has(entry.target)) {
+        diagnostics.push({
+          code: 'LEGACY_NPM_ENTRY_COVERAGE_MISSING',
+          path: entry.target,
+          field: entry.field,
+        });
+      }
+    }
+  }
+
+  const unitAbsDir = resolve(root, pkg.directory);
+  const candidates = [];
+  for (const item of [...byPath.values()].sort((a, b) => a.path.localeCompare(b.path))) {
+    candidates.push({
+      ...await classifyNpmEntryCandidate(
+        unitAbsDir,
+        item.path,
+        unitGitEntry?.trackedFiles ?? [],
+      ),
+      sources: [...item.sources].sort(),
+    });
+  }
+  diagnostics.sort((a, b) => canonicalJson(a).localeCompare(canonicalJson(b)));
+  return { candidates, diagnostics };
+}
+
 async function discoverFacts(root) {
   const files = await walkDiscoveryFiles(root);
   const packageFiles = files.filter((path) => (
@@ -494,6 +604,11 @@ async function discoverFacts(root) {
       private: pkg.private === true,
       repository: parseGithubRepo(pkg.repository),
       publishRegistry: typeof pkg.publishConfig?.registry === 'string' ? pkg.publishConfig.registry : null,
+      entryManifest: Object.fromEntries(
+        ['bin', 'main', 'module', 'types', 'typings', 'exports']
+          .filter((field) => Object.hasOwn(pkg, field))
+          .map((field) => [field, pkg[field]]),
+      ),
       files: Array.isArray(pkg.files) ? pkg.files.filter((item) => typeof item === 'string').sort() : [],
       scripts: Object.fromEntries(Object.entries(pkg.scripts ?? {})
         .filter(([, value]) => typeof value === 'string')
@@ -557,6 +672,22 @@ async function discoverFacts(root) {
   for (const pkg of packages) {
     const unitAbsDir = resolve(root, pkg.directory);
     unitGit[pkg.directory] = await discoverUnitGit(unitAbsDir, root);
+    const inferredId = safeUnitId(pkg, pkg.directory);
+    const matchingLegacyUnits = legacyReleaseConfigs
+      .flatMap((config) => config.releaseUnits)
+      .filter((unit) => (
+        unit.id === inferredId ||
+        unit.source === pkg.directory ||
+        unit.source === dirname(pkg.path)
+      ));
+    const npmDiscovery = await discoverNpmEntryCandidates(
+      root,
+      pkg,
+      matchingLegacyUnits,
+      unitGit[pkg.directory],
+    );
+    pkg.npmEntryCandidates = npmDiscovery.candidates;
+    pkg.npmEntryDiagnostics = npmDiscovery.diagnostics;
   }
 
   return { git, packages, manifests, skills, legacyReleaseConfigs, fileDigests, unitGit };
@@ -871,6 +1002,8 @@ function buildCandidates(facts) {
       publicFileMappingCandidates: mappingResult.mappings,
       publicFileMappingConflicts: mappingResult.conflicts,
       requiredPublicFileCandidates,
+      npmEntryCandidates: pkg.npmEntryCandidates ?? [],
+      npmEntryDiagnostics: pkg.npmEntryDiagnostics ?? [],
       entrySkillCandidates: entrySkillCandidatesForUnit(facts, pkg, id),
       ...(hasAuthorityConflict ? {
         authorityConflict: {
@@ -1027,6 +1160,24 @@ function buildRecommendedProposal(facts, candidates) {
         assumptions,
       };
     }
+    if (
+      unit.distributionCandidates.includes('npm') &&
+      (
+        (unit.npmEntryCandidates ?? []).some((candidate) => candidate.state !== 'TRACKED_PRESENT') ||
+        (unit.npmEntryDiagnostics ?? []).length > 0
+      )
+    ) {
+      return {
+        answers: null,
+        conflicts: [{
+          code: 'NPM_ENTRY_REVIEW_REQUIRED',
+          unit: unit.id,
+          candidates: unit.npmEntryCandidates,
+          diagnostics: unit.npmEntryDiagnostics,
+        }],
+        assumptions,
+      };
+    }
 
     // Infer npm publisher: prefer legacy owner, then parse from repo slug
     const repoOwner = publicRepo.includes('/') ? publicRepo.split('/')[0] : null;
@@ -1245,6 +1396,15 @@ function buildDecisionsRequired(candidates, localOnly) {
       id: `unit:${unit.id}:distributions-and-files`,
       description: `逐项确认渠道 ${JSON.stringify(unit.distributionCandidates)}、公开文件边界和 requiredPublicFiles；候选不是授权。`,
     });
+    if (
+      (unit.npmEntryCandidates ?? []).length > 0 ||
+      (unit.npmEntryDiagnostics ?? []).length > 0
+    ) {
+      decisions.push({
+        id: `unit:${unit.id}:npm-entry-closure`,
+        description: '审阅 package.json 入口及旧 npmRequiredPackagePaths 的 tracked/untracked/ignored/missing 状态；setup 只报告候选，不自动写入 publicFiles 或 requiredPublicFiles。',
+      });
+    }
   }
   decisions.push({
     id: 'verification-gates',
@@ -1271,6 +1431,8 @@ function buildCompactSummary(report) {
       distributionCandidates: [...unit.distributionCandidates].sort(),
       publicFileMappingCount: (unit.publicFileMappingCandidates ?? []).length,
       requiredPublicFileCount: (unit.requiredPublicFileCandidates ?? []).length,
+      npmEntryCandidates: unit.npmEntryCandidates ?? [],
+      npmEntryDiagnostics: unit.npmEntryDiagnostics ?? [],
     })),
     gateCandidates: (report.gateCandidates ?? []).map((gate) => ({
       id: gate.id,
@@ -1519,6 +1681,12 @@ export async function setupProject({ root, answersPath, write = false, confirmSe
           ...(unconfiguredGateCandidateIds.length > 0
             ? ['存在未配置的验证候选；逐项审阅副作用后决定是否人工注册。']
             : []),
+          ...(candidates.units.some((unit) => (
+            (unit.npmEntryCandidates ?? []).some((candidate) => candidate.state !== 'TRACKED_PRESENT') ||
+            (unit.npmEntryDiagnostics ?? []).length > 0
+          ))
+            ? ['npm 入口候选存在未跟踪、被忽略、缺失、非普通文件或声明覆盖疑点；人工增量修复配置或构建流程，setup 不自动改写。']
+            : []),
         ],
       },
       recommendedGateIds: [],