@abelxiaoxing/cadence 1.5.1 → 1.5.3

package/README.md

@@ -31,6 +31,9 @@ node /absolute/path/to/cadence/src/operator-cli.mjs runs /path/to/consumer
 ```
 
 `doctor` 检查 Git、Node、OpenSpec 入口、实际 Bubblewrap 启动、请求预算和常用脚本静态能力；不调用模型、不执行产品测试、不保证所有集成服务均可用。
+包管理器优先采用 `package.json.packageManager`，其次推断唯一锁文件所属的管理器；没有声明和锁文件时明确标为 npm 默认值。
+输出包含 `selectedPackageManager`、`selectionSource`、`lockfiles` 和 `ambiguousLockfiles`；多个管理器锁文件且无明确声明时阻塞脚本探测，不静默选择 Bun。
+Doctor 不读取私有计划，计划中的显式 runner 仍由正式预检检查；请让项目声明与计划保持一致。
 `runs` 只读列出该项目最多 1,000 个 run 和有界存储占用；不会创建、迁移或删除数据库，不自动清理暂停任务。
 
 ### 可信本地项目：显式复用宿主环境
@@ -87,6 +90,7 @@ Gate、交付校验和执行状态转换由控制面代码保证。
 当前任务的 Gate 回答与续轮保持阶段有效；用户结束工作流或转向无关任务时，父模型先调用 `{"action":"finish"}`，扩展等待活动操作停止并恢复原工具，保留可恢复进度。
 此退出同样适用于 Implement，不表示完成或丢弃。
 显式调用 Init 也会先退出已有阶段。
+Design 同任务续轮重新收紧允许的工具集合，预检失败或暂停不自动退出；会话重载/恢复不继承阶段激活权限，需重新显式调用对应命令，已保存的 run 不会因此完成或丢弃。
 
 Implement 只暴露 `start`、`status`、`resume`、`rebind`、`cancel` 和 `discard` 控制命令。
 `status` 完全本地可用；相同 operation id 幂等重放，进程、会话或 Worker 更换后仍从 durable checkpoint 继续。
@@ -99,6 +103,12 @@ Design 从第一步起统一使用 `action: "design"`：新需求通过 `start(r
 内联原子验证也可省略 `id` / `classification`；任务公共 `read` 与阶段读取合并，固定 baseline/repair 保护字段由编译器补齐，恢复次数和 AGENTS 影响仍需作者明确选择。
 [多任务示例](config/plan-draft.multiple-tasks.example.json) 保留显式依赖和产物 producer；ordered steps 仍使用完整内联合同。
 `validate-plan-draft` 返回有界的最终权限、验证用途、恢复次数和实际派生来源摘要；摘要不充当批准或封存证明。
+编译结果的 `checks` 分开报告 `structure`、`verificationCapability`、`contractCoverage` 和 `sealing`；静态 `closure.executable: true` 不代表产品测试已运行或 `READY_TO_IMPLEMENT`。
+独立 `compileImplementPlan` 未传合同则 `contractCoverage: "not-checked"`；传入合同也不证明该合同已获批准。
+正式预检从私有 journal 注入当前 Gate A 合同并报告 `gateA: "current"`，但仍是 `sealing: "not-performed"`；只有正式控制面可以批准和封存交付。
+验收缺失诊断列出 acceptance ID；仅当验证 ID 唯一对应一个不同义务时返回字段差异，不猜测最接近的验证器，也不回显命令或参数。
+`changedSurfaces` 仅接受 `none`、`route-authorization`、`page-state`、`api-response`、`public-html`；公共影响不得改标为 `none` 来绕过闭包。
+`verification.change.affected` 是固定标记 `"task-affected-contracts"`，不能使用 `{ "use": "..." }`；`affectedSuite` 中公共影响测试必须在 `relatedTests` 声明证据和实际 owner。
 推导有歧义时拒绝编译，显式错误仍会报错；代码不会据此扩大路径、依赖或产物权限，封存计划保持完整、严格的结构。
 预检集中返回不同任务的独立结构错误，并提供字段位置、期望/实际路径和修正提示；工具反馈与 TUI 共用有界脱敏投影。
 Design status 将可调用的 `legalOperations` 与顶层 `packetActions` 分开；显式退出只能发送 `{"action":"finish"}`，不能伪装成 `operation: "finish"`。
@@ -140,6 +150,58 @@ Gate 等待和可恢复暂停保持激活以接收直接后续操作。
 暂停会保留最小结构化恢复事实；完成或显式 discard 后安全清理。
 不会持久化凭据、环境值、原始 prompt、隐藏推理、完整子会话或原始模型输出。
 
+### 公共 UI 的 impactClosure 作者格式
+
+`page-state` 与 `public-html` 可以同时声明。
+以下是 **PlanDraft 任务片段**，合并到现有 `tasks[i]`，不是完整计划；其余 Gate A、阶段、产物和验证合同仍按单任务示例填写。
+路径和证据仅用于说明，必须替换为仓库真实调查结果。
+假设 Red 修改 `test/page-state.mjs`，已有 `test/public-html.mjs` 只读保留：
+
+```json
+{
+  "read": ["test/page-state.mjs", "test/public-html.mjs"],
+  "impactClosure": {
+    "changedSurfaces": ["page-state", "public-html"],
+    "searchEvidence": [
+      "检索页面状态的调用点及 test/、tests/ 中的覆盖：test/page-state.mjs 需更新状态切换断言，test/public-html.mjs 覆盖现有公开 HTML。"
+    ],
+    "relatedTests": [
+      {
+        "path": "test/page-state.mjs",
+        "evidence": "本任务 Red 更新页面状态切换回归；由阶段 write 推导为 current-task。"
+      },
+      {
+        "path": "test/public-html.mjs",
+        "evidence": "保留已有 HTML 断言并执行受影响验证；无任务写入，推导为 unaffected。"
+      }
+    ],
+    "affectedSuite": ["test/page-state.mjs", "test/public-html.mjs"]
+  }
+}
+```
+
+完整规则：
+
+- `impactClosure` 恰好包含 `changedSurfaces`、`searchEvidence`、`relatedTests`、`affectedSuite` 四个字段，不接受任意扩展字段。
+- `changedSurfaces` 是非空、无重复的合法枚举数组；`none` 不能与其他值混用。
+  不得为了通过校验将公共影响改为 `none`。
+- 存在公共影响时，后三个数组均不得为空；`searchEvidence` 每项为非空字符串，记录实际检索及结论，不是路径对象，也不是可省略的推导字段。
+- `relatedTests` 每项包含 `path` 和非空字符串 `evidence`；路径无重复，必须是 `test/` 或 `tests/` 下的仓库相对文件路径，并位于本任务各阶段合并后的 read/write 范围。
+  `src/foo.test.ts` 不满足当前测试路径规则。
+- PlanDraft 可省略 `disposition`：本任务写入则推导为 `current-task`，只有另一任务写入则为 `regression-task` 并推导 `regressionTaskId`，没有任务写入则为 `unaffected`；多个其他写入者时必须消除歧义。
+  `unaffected` 表示不修改该测试，不表示不运行该测试。
+- 显式作者格式为 `{ "path": "test/page-state.mjs", "disposition": "current-task", "evidence": "实际证据" }`；只读保留用 `unaffected`。
+  跨任务格式为 `{ "path": "test/page-state.mjs", "disposition": "regression-task", "evidence": "实际证据", "regressionTaskId": "ui-regression" }`。
+  只有 `regression-task` 携带 `regressionTaskId`；依赖、产物和阶段权限仍需按实际计划声明，不会由闭包新增。
+- `affectedSuite` 是无重复的测试路径数组，每项必须有对应的 `relatedTests` 条目；具备快照的运行时校验还要求其中至少一个是已有普通测试文件，不能全靠未来新增测试充当已有证据。
+- `affectedSuite` 是影响清单，不是验证器。
+  显式 `affectedVerification` 应实际运行这些测试，例如 Vitest 的 `testFiles` 列出二者，或使用仓库真实的测试脚本。
+  仍需声明验证输入并遵守 Gate A，不能只补清单就宣称测试已运行。
+
+`validate-plan-draft` 对三个空数组分别返回字段级 category：`search-evidence-required`、`related-tests-required`、`affected-suite-required`，并提供代码维护的 `hint`。
+测试漏列仍返回 `impactClosure.affectedSuite.<index>` / `related-test-missing` 和具体 `path`。
+空数组不足以确定应选哪些测试，因此不会虚构 `expectedPaths`；按实际证据补齐后，在同一个 Design run 重试预检。
+
 ## 内部边界与运行验证
 
 扩展入口负责宿主生命周期与服务装配，交付加载和验证适配器分别由独立模块负责。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abelxiaoxing/cadence",
-  "version": "1.5.1",
+  "version": "1.5.3",
   "description": "Four explicit Abel workflow prompts with stage-isolated design and diagnosis, durable resumable implementation, and three package-owned professional Agents.",
   "license": "MIT",
   "type": "module",

package/src/change-contract.ts

@@ -6,7 +6,10 @@ import {
   validateVerificationContract,
   verificationInputPaths,
 } from "./contracts.ts";
-import { DesignPlanValidationError } from "./design-diagnostics.ts";
+import {
+  type DesignPlanDiagnostic,
+  DesignPlanValidationError,
+} from "./design-diagnostics.ts";
 import { canonicalJson } from "./run-state.ts";
 
 export interface ChangeContract {
@@ -151,25 +154,73 @@ export function assertPlanWithinChangeContract(
   })[],
   verifications: readonly StructuredVerificationContract[],
 ): void {
-  const available = new Set(
-    [
-      ...verifications,
-      ...tasks.flatMap((task) => [
-        task.affectedVerification,
-        ...Object.entries(task.phases)
-          .filter(
-            ([phase]) =>
-              phase !== "red" ||
-              !task.verificationMode ||
-              task.verificationMode === "behavior",
-          )
-          .map(([, phase]) => phase.verification),
-      ]),
-    ].map(verificationObligation),
-  );
-  for (const accepted of contract.acceptance)
-    if (!available.has(verificationObligation(accepted.verification)))
-      throw new Error("change-contract-acceptance-missing");
+  const candidates = [
+    ...verifications,
+    ...tasks.flatMap((task) => [
+      task.affectedVerification,
+      ...Object.entries(task.phases)
+        .filter(
+          ([phase]) =>
+            phase !== "red" ||
+            !task.verificationMode ||
+            task.verificationMode === "behavior",
+        )
+        .map(([, phase]) => phase.verification),
+    ]),
+  ];
+  const available = new Set(candidates.map(verificationObligation));
+  const diagnostics: DesignPlanDiagnostic[] = [];
+  for (const [index, accepted] of contract.acceptance.entries()) {
+    if (available.has(verificationObligation(accepted.verification))) continue;
+    // Only attribute a mismatch when the display ID selects one distinct
+    // obligation. Never guess a "closest" verifier or echo command/argument bytes.
+    const matching = [
+      ...new Set(
+        candidates
+          .filter((candidate) => candidate.id === accepted.verification.id)
+          .map(verificationObligation),
+      ),
+    ];
+    const expected = JSON.parse(verificationObligation(accepted.verification));
+    const actual =
+      matching.length === 1 && matching[0]
+        ? JSON.parse(matching[0])
+        : undefined;
+    diagnostics.push({
+      code: "change-contract-acceptance-missing",
+      acceptanceId: accepted.id,
+      verificationId: accepted.verification.id,
+      field: `changeContract.acceptance.${index}.verification`,
+      ...(actual
+        ? {
+            mismatchedFields: [
+              "kind",
+              "runner",
+              "packageManager",
+              "script",
+              "command",
+              "args",
+              "testFiles",
+              "minTests",
+              "classification",
+              "expectedFailure",
+              "steps",
+            ]
+              .filter(
+                (key) =>
+                  canonicalJson(expected[key] ?? null) !==
+                  canonicalJson(actual[key] ?? null),
+              )
+              .sort(),
+          }
+        : {}),
+    });
+  }
+  if (diagnostics.length)
+    throw new DesignPlanValidationError(
+      "change-contract-acceptance-missing",
+      diagnostics,
+    );
   for (const task of tasks) {
     if (
       !contract.policy.verificationModes.includes(

package/src/contracts.ts

@@ -1233,6 +1233,7 @@ export type ImplementGraphContractDiagnostic =
       path?: string;
       expectedPaths?: string[];
       actualPaths?: string[];
+      allowedValues?: string[];
     }
   | {
       code: "invalid-output-path";
@@ -1518,6 +1519,99 @@ function taskBoundaryContractDiagnostic(
     : diagnostic("task", "contract");
 }
 
+/** Refine rejected author input; this never admits a partial or repaired task. */
+function taskFieldDiagnostics(
+  task: Record<string, unknown>,
+): ImplementGraphContractDiagnostic[] {
+  const diagnostics: ImplementGraphContractDiagnostic[] = [];
+  const add = (
+    detail: Omit<
+      Extract<
+        ImplementGraphContractDiagnostic,
+        { code: "invalid-implement-graph" }
+      >,
+      "code"
+    >,
+  ) => {
+    if (diagnostics.length < 64)
+      diagnostics.push({
+        code: "invalid-implement-graph",
+        ...(validIdentifier(task.taskId) ? { taskId: task.taskId } : {}),
+        ...detail,
+      });
+  };
+  if (task.phases && typeof task.phases === "object") {
+    const phases = task.phases as Record<string, unknown>;
+    for (const phase of IMPLEMENTATION_PHASES) {
+      const boundary = phases[phase];
+      if (!boundary || typeof boundary !== "object") continue;
+      for (const field of ["read", "write", "delete"] as const) {
+        const paths = (boundary as Record<string, unknown>)[field];
+        if (!Array.isArray(paths)) continue;
+        const seen = new Set<string>();
+        for (const [index, file] of paths.entries()) {
+          if (!isValidRelativePath(file)) continue;
+          if (seen.has(file))
+            add({
+              phase,
+              field: `phases.${phase}.${field}.${index}`,
+              category: "duplicate-path",
+              path: file,
+            });
+          seen.add(file);
+        }
+      }
+    }
+  }
+  if (task.impactClosure && typeof task.impactClosure === "object") {
+    const closure = task.impactClosure as Record<string, unknown>;
+    if (Array.isArray(closure.changedSurfaces)) {
+      for (const [index, surface] of closure.changedSurfaces.entries()) {
+        if (!(IMPACT_SURFACES as readonly unknown[]).includes(surface))
+          add({
+            field: `impactClosure.changedSurfaces.${index}`,
+            category: "enum",
+            allowedValues: [...IMPACT_SURFACES],
+          });
+      }
+      const publicImpact = closure.changedSurfaces.some(
+        (surface) =>
+          surface !== "none" &&
+          (IMPACT_SURFACES as readonly unknown[]).includes(surface),
+      );
+      if (publicImpact) {
+        for (const [field, category] of [
+          ["searchEvidence", "search-evidence-required"],
+          ["relatedTests", "related-tests-required"],
+          ["affectedSuite", "affected-suite-required"],
+        ] as const) {
+          if (Array.isArray(closure[field]) && closure[field].length === 0)
+            add({ field: `impactClosure.${field}`, category });
+        }
+      }
+      if (
+        publicImpact &&
+        Array.isArray(closure.affectedSuite) &&
+        Array.isArray(closure.relatedTests)
+      ) {
+        const related = new Set(
+          closure.relatedTests.flatMap((item) =>
+            item && typeof item === "object" ? [item.path] : [],
+          ),
+        );
+        for (const [index, file] of closure.affectedSuite.entries())
+          if (isValidRelativePath(file) && !related.has(file))
+            add({
+              field: `impactClosure.affectedSuite.${index}`,
+              category: "related-test-missing",
+              path: file,
+            });
+      }
+    }
+  }
+  return diagnostics;
+}
+
 export function validateImplementGraphBoundary(value: unknown):
   | { ok: true; value: ImplementGraphBoundary }
   | {
@@ -1573,11 +1667,24 @@ export function validateImplementGraphBoundary(value: unknown):
           { changeId: value.changeId, ...task },
           undefined,
         );
-    if (diagnostic)
-      failures.push({
-        reason: "invalid Implement task boundary",
-        diagnostic: { code: "invalid-implement-graph", ...diagnostic },
-      });
+    if (diagnostic) {
+      const fields = taskFieldDiagnostics(task);
+      // Replace a broad diagnostic only when these details refine that field;
+      // retain unrelated shape/authority failures in the same batch.
+      if (
+        !fields.some(
+          (detail) =>
+            diagnostic.field &&
+            detail.field?.startsWith(`${diagnostic.field}.`),
+        )
+      )
+        fields.push({ code: "invalid-implement-graph", ...diagnostic });
+      for (const detail of fields)
+        failures.push({
+          reason: "invalid Implement task boundary",
+          diagnostic: detail,
+        });
+    }
   }
   for (const candidate of value.outputs) {
     if (

package/src/delivery-compiler.ts

@@ -264,6 +264,13 @@ export type {
 export type { PlanDraft, PlanPhaseDraft, PlanTaskInput } from "./plan-draft.ts";
 
 export interface CompiledDelivery {
+  /** Static checks only: neither compilation nor preflight seals a delivery. */
+  checks: {
+    structure: "passed";
+    verificationCapability: "passed";
+    contractCoverage: "passed" | "not-checked";
+    sealing: "not-performed";
+  };
   plan: ImplementPlan;
   bytes: Uint8Array;
   rawSha256: string;
@@ -945,6 +952,20 @@ function normalizeAgentsCheckpointOperations(
 }
 
 function normalizeVerificationPlan(value: unknown): PlanVerification {
+  if (
+    isRecord(value) &&
+    isRecord(value.change) &&
+    value.change.affected !== "task-affected-contracts"
+  ) {
+    throw new DesignPlanValidationError("delivery-verification-plan-invalid", [
+      {
+        code: "delivery-verification-plan-invalid",
+        field: "verification.change.affected",
+        category: "enum",
+        allowedValues: ["task-affected-contracts"],
+      },
+    ]);
+  }
   if (
     !isRecord(value) ||
     !exactKeys(value, [
@@ -1289,6 +1310,12 @@ export function compileImplementPlan(
     const planHash = hashCanonicalValue(plan);
     const closure = structuredClone(readiness.closure);
     return {
+      checks: {
+        structure: "passed",
+        verificationCapability: "passed",
+        contractCoverage: plan.changeContract ? "passed" : "not-checked",
+        sealing: "not-performed",
+      },
       plan,
       bytes,
       rawSha256,

package/src/design-control.ts

@@ -978,6 +978,7 @@ export class DesignController {
       operation: request.operation,
       runId: request.runId,
       valid: true,
+      checks: { ...compiled.checks, gateA: "current" },
       summary: planAuthoringSummary(compiled.plan, authoredDraft),
       plan: {
         taskCount: compiled.plan.tasks.length,

package/src/design-diagnostics.ts

@@ -11,6 +11,7 @@ const IDENTITIES = new Set([
   "category",
   "owner",
   "verificationId",
+  "acceptanceId",
   "outputId",
   "dependencyTaskId",
   "producerTaskId",
@@ -22,6 +23,19 @@ const IDENTITIES = new Set([
 ]);
 const HINTS = new Map<string, string>(
   Object.entries({
+    "duplicate-path":
+      "Remove the repeated path at the indicated index; keep the existing declaration and do not widen phase permissions.",
+    enum: "Use one of allowedValues at the indicated field. For public impact, choose the actual changed surface; do not substitute none to bypass closure checks.",
+    "public-impact-incomplete":
+      "Public impact requires non-empty searchEvidence, relatedTests and affectedSuite; every affectedSuite path must have a relatedTests entry. Keep the actual changedSurfaces; do not substitute none.",
+    "search-evidence-required":
+      "Add non-empty searchEvidence strings describing actual searches of changed public surfaces, callers and existing tests. Do not invent evidence or substitute none for changedSurfaces.",
+    "related-tests-required":
+      "Add relatedTests entries with path and non-empty evidence for actual tests under test/ or tests/, within the task's declared read/write scope. In PlanDraft omit disposition to derive ownership from task writes; do not widen writes or substitute none.",
+    "affected-suite-required":
+      "Add actual affected test paths under test/ or tests/ to affectedSuite and declare each in relatedTests. Bind their execution in affectedVerification; retained snapshot validation requires at least one existing test. Do not invent paths or substitute none.",
+    "related-test-missing":
+      "Add this affected-suite test to relatedTests with evidence and its actual owner. Do not remove public impact or widen writes to satisfy ownership.",
     "change-contract-acceptance-missing":
       "Read the current approved ChangeContract from Design status and include each accepted verification obligation in the plan's phase, affected, full-suite or post-apply verification. Command, arguments, inputs and classification must match; copying only its ID is insufficient. Keep accepted IDs, statements and scope unchanged.",
     "script-command-mismatch":
@@ -96,6 +110,18 @@ export function projectDesignDiagnostic(
           : entry;
     else if (key === "path" && safePath(entry)) result.path = entry;
     else if (
+      (key === "allowedValues" || key === "mismatchedFields") &&
+      Array.isArray(entry)
+    ) {
+      result[key] = [
+        ...new Set(
+          entry.filter(
+            (item): item is string =>
+              typeof item === "string" && CODE.test(item),
+          ),
+        ),
+      ].slice(0, 32);
+    } else if (
       (key === "expectedPaths" || key === "actualPaths") &&
       Array.isArray(entry)
     ) {
@@ -120,6 +146,9 @@ export interface DesignPlanDiagnostic {
   category?: string;
   owner?: string;
   verificationId?: string;
+  acceptanceId?: string;
+  allowedValues?: string[];
+  mismatchedFields?: string[];
   outputId?: string;
   dependencyTaskId?: string;
   producerTaskId?: string;

package/src/index.ts

@@ -887,6 +887,8 @@ export function registerWorkflowControl(
     pi.registerTool({
       name: DISPATCH_TOOL,
       label: "Abel Control",
+      promptSnippet:
+        "Control the explicitly activated Abel stage; retain paused work across same-task follow-ups.",
       description:
         kind === "command"
           ? 'Private stage-bound Abel workflow control. Accepts durable Implement commands, batch-bound {"action":"amend"} artifact revisions, or {"action":"finish"} to leave and preserve resumable work.'
@@ -1394,7 +1396,8 @@ export function registerWorkflowControl(
       activePrompt = prompt;
     }
     if (prompt) activateDispatcher(pi, activation, prompt, event.prompt);
-    if (verified && prompt === "abel-design") enforceDesignTools();
+    if (activation.isActive() && activePrompt === "abel-design")
+      enforceDesignTools();
     const boundary = activePrompt
       ? `Abel stage ${activePrompt} is active only for the invoked task and its direct follow-ups. If the user ends it or requests an unrelated task, first call abel_dispatch with {"action":"finish"}, then handle that task normally with the restored tools. A successful finish ends stage authority immediately, including within this turn. Do not extend Gates or workflow rules to that task. A direct Gate answer or same-task continuation stays in this stage. Never invoke another Abel stage automatically.`
       : init

package/src/operator-cli.mjs

@@ -1239,6 +1239,26 @@ function validateAcceptedVerificationCapability(root, verification, dependencyOw
 }
 
 // src/operator-tools.ts
+var PACKAGE_LOCKS = {
+  bun: ["bun.lock", "bun.lockb"],
+  npm: ["package-lock.json", "npm-shrinkwrap.json"],
+  pnpm: ["pnpm-lock.yaml"],
+  yarn: ["yarn.lock"]
+};
+function packageManagerSelection(root, declaration) {
+  const managers = Object.keys(PACKAGE_LOCKS);
+  const lockfiles = managers.flatMap((manager) => PACKAGE_LOCKS[manager].filter((file) => lstatSync6(path5.join(root, file), { throwIfNoEntry: false })?.isFile()));
+  const inferred = managers.filter((manager) => PACKAGE_LOCKS[manager].some((file) => lockfiles.includes(file)));
+  const declared = typeof declaration === "string" ? managers.find((manager) => new RegExp(`^${manager}@[0-9]+\\.[0-9]+\\.[0-9]+(?:[-+][a-z0-9._+-]+)?$`, "iu").test(declaration)) : undefined;
+  const selectedPackageManager = declaration !== undefined ? declared ?? null : inferred.length === 1 ? inferred[0] ?? null : inferred.length > 1 ? null : "npm";
+  const selectionSource = declaration !== undefined ? declared ? "package.json" : "invalid-declaration" : inferred.length === 1 ? "lockfile" : inferred.length > 1 ? "ambiguous" : "default";
+  return {
+    selectedPackageManager,
+    selectionSource,
+    lockfiles,
+    ambiguousLockfiles: inferred.length > 1
+  };
+}
 function inspectConsumer(root) {
   root = realpathSync4(root);
   const checks = [];
@@ -1317,6 +1337,7 @@ function inspectConsumer(root) {
     return `${links} repository workspace link(s); their targets must be included in the candidate baseline`;
   }, "Repair dangling/external workspace links and ensure local package sources are tracked or admitted in the candidate.");
   const manifest = path5.join(root, "package.json");
+  let selection = packageManagerSelection(root, undefined);
   if (lstatSync6(manifest, { throwIfNoEntry: false })?.isFile()) {
     check("manifest", () => {
       const parsed2 = JSON.parse(readFileSync4(manifest, "utf8"));
@@ -1326,19 +1347,23 @@ function inspectConsumer(root) {
     }, "Repair package.json.");
     const parsed = (() => {
       try {
-        return JSON.parse(readFileSync4(manifest, "utf8"));
+        const value = JSON.parse(readFileSync4(manifest, "utf8"));
+        return value && typeof value === "object" && !Array.isArray(value) ? value : {};
       } catch {
         return {};
       }
     })();
+    selection = packageManagerSelection(root, parsed.packageManager);
+    check("package-manager", () => {
+      if (!selection.selectedPackageManager)
+        throw new Error(`package-manager-${selection.selectionSource}`);
+      return `${selection.selectedPackageManager} (${selection.selectionSource})`;
+    }, "Declare the intended packageManager in package.json; doctor does not read private plans, install runners or remove lockfiles.");
     for (const script of ["test", "check", "build"].filter((name) => typeof parsed.scripts?.[name] === "string")) {
       check(`script:${script}`, () => {
-        const manager = ["bun", "pnpm", "yarn", "npm"].find((name) => lstatSync6(path5.join(root, {
-          bun: "bun.lock",
-          pnpm: "pnpm-lock.yaml",
-          yarn: "yarn.lock",
-          npm: "package-lock.json"
-        }[name]), { throwIfNoEntry: false })) ?? "npm";
+        const manager = selection.selectedPackageManager;
+        if (!manager)
+          throw new Error(`package-manager-${selection.selectionSource}`);
         const result = validateVerificationAdapterCapability(root, {
           kind: "package-script",
           id: `doctor-${script}`,
@@ -1349,12 +1374,12 @@ function inspectConsumer(root) {
           classification: "expected-green"
         });
         if (!result.ok)
-          throw new Error(result.diagnostic.code);
+          throw new Error(`${manager}:${result.diagnostic.code}`);
         return "statically admitted; tests not executed";
       }, "Check the runner, installed dependencies and execution configuration; this probe does not execute your tests.");
     }
   }
-  return { root, ok: checks.every((entry) => entry.ok), checks };
+  return { root, ...selection, ok: checks.every((entry) => entry.ok), checks };
 }
 function storageUsage(root, maximum = 1e5) {
   let entries = 0;

package/src/operator-tools.ts

@@ -14,6 +14,59 @@ export interface DoctorCheck {
   detail: string;
   nextStep?: string;
 }
+const PACKAGE_LOCKS = {
+  bun: ["bun.lock", "bun.lockb"],
+  npm: ["package-lock.json", "npm-shrinkwrap.json"],
+  pnpm: ["pnpm-lock.yaml"],
+  yarn: ["yarn.lock"],
+} as const;
+type PackageManager = keyof typeof PACKAGE_LOCKS;
+
+function packageManagerSelection(root: string, declaration: unknown) {
+  const managers = Object.keys(PACKAGE_LOCKS) as PackageManager[];
+  const lockfiles = managers.flatMap((manager) =>
+    PACKAGE_LOCKS[manager].filter((file) =>
+      lstatSync(path.join(root, file), { throwIfNoEntry: false })?.isFile(),
+    ),
+  );
+  const inferred = managers.filter((manager) =>
+    PACKAGE_LOCKS[manager].some((file) => lockfiles.includes(file)),
+  );
+  const declared =
+    typeof declaration === "string"
+      ? managers.find((manager) =>
+          new RegExp(
+            `^${manager}@[0-9]+\\.[0-9]+\\.[0-9]+(?:[-+][a-z0-9._+-]+)?$`,
+            "iu",
+          ).test(declaration),
+        )
+      : undefined;
+  const selectedPackageManager =
+    declaration !== undefined
+      ? (declared ?? null)
+      : inferred.length === 1
+        ? (inferred[0] ?? null)
+        : inferred.length > 1
+          ? null
+          : "npm";
+  const selectionSource =
+    declaration !== undefined
+      ? declared
+        ? "package.json"
+        : "invalid-declaration"
+      : inferred.length === 1
+        ? "lockfile"
+        : inferred.length > 1
+          ? "ambiguous"
+          : "default";
+  return {
+    selectedPackageManager,
+    selectionSource,
+    lockfiles,
+    ambiguousLockfiles: inferred.length > 1,
+  };
+}
+
 export function inspectConsumer(root: string) {
   root = realpathSync(root);
   const checks: DoctorCheck[] = [];
@@ -136,6 +189,7 @@ export function inspectConsumer(root: string) {
     "Repair dangling/external workspace links and ensure local package sources are tracked or admitted in the candidate.",
   );
   const manifest = path.join(root, "package.json");
+  let selection = packageManagerSelection(root, undefined);
   if (lstatSync(manifest, { throwIfNoEntry: false })?.isFile()) {
     check(
       "manifest",
@@ -151,51 +205,51 @@ export function inspectConsumer(root: string) {
     );
     const parsed = (() => {
       try {
-        return JSON.parse(readFileSync(manifest, "utf8"));
+        const value = JSON.parse(readFileSync(manifest, "utf8"));
+        return value && typeof value === "object" && !Array.isArray(value)
+          ? value
+          : {};
       } catch {
         return {};
       }
     })();
+    selection = packageManagerSelection(root, parsed.packageManager);
+    check(
+      "package-manager",
+      () => {
+        if (!selection.selectedPackageManager)
+          throw new Error(`package-manager-${selection.selectionSource}`);
+        return `${selection.selectedPackageManager} (${selection.selectionSource})`;
+      },
+      "Declare the intended packageManager in package.json; doctor does not read private plans, install runners or remove lockfiles.",
+    );
     for (const script of ["test", "check", "build"].filter(
       (name) => typeof parsed.scripts?.[name] === "string",
     )) {
       check(
         `script:${script}`,
         () => {
-          const manager =
-            ["bun", "pnpm", "yarn", "npm"].find((name) =>
-              lstatSync(
-                path.join(
-                  root,
-                  (
-                    {
-                      bun: "bun.lock",
-                      pnpm: "pnpm-lock.yaml",
-                      yarn: "yarn.lock",
-                      npm: "package-lock.json",
-                    } as Record<string, string>
-                  )[name],
-                ),
-                { throwIfNoEntry: false },
-              ),
-            ) ?? "npm";
+          const manager = selection.selectedPackageManager;
+          if (!manager)
+            throw new Error(`package-manager-${selection.selectionSource}`);
           const result = validateVerificationAdapterCapability(root, {
             kind: "package-script",
             id: `doctor-${script}`,
-            packageManager: manager as "bun" | "pnpm" | "yarn" | "npm",
+            packageManager: manager,
             script,
             command: parsed.scripts[script],
             args: [],
             classification: "expected-green",
           });
-          if (!result.ok) throw new Error(result.diagnostic.code);
+          if (!result.ok)
+            throw new Error(`${manager}:${result.diagnostic.code}`);
           return "statically admitted; tests not executed";
         },
         "Check the runner, installed dependencies and execution configuration; this probe does not execute your tests.",
       );
     }
   }
-  return { root, ok: checks.every((entry) => entry.ok), checks };
+  return { root, ...selection, ok: checks.every((entry) => entry.ok), checks };
 }
 
 /** Bounded metadata traversal, no symlink following and no automatic deletion. */