@agile-team/wl-skills-ui 1.17.0 → 1.19.0

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [1.19.0] - 2026-10-11
+
+- 区分当前请求、否定动作与历史引用，增加动作模式；解释/规划不自动检查，意图不作为业务写入授权。
+- 公开协议保持 v1 和原有字段，增加带 Schema 的 result.integration、规则身份与包自有只读执行器目录。
+- 编辑器 gateway 展示真实动作与规则回执；补充独立包语料、统一契约和执行边界回归，无兄弟包/Harness 依赖。
+- 触发词迁至独立目录并双向核验，明确 scan 样式检查与 check 接入检查的职责。
+
+
+## [1.18.0] - 2026-10-11
+
+- 任务路由前校验目标项目自身接入与平台；未接入/移动端零规则零任务写入，不继承父安装。
+- 最近项目边界与跨项目拆分、独立包禁用、严格范围Schema、notice/doctor/status范围与过期证据。
+- 原生及编辑器入口收窄适用描述；补充单包、移动端、开源未接入、工作区、异常配置和Maven模块回归。
+
 All notable changes to **@agile-team/wl-skills-ui** will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).

package/README.md

@@ -1,5 +1,7 @@
 # @agile-team/wl-skills-ui
 
+> 项目范围：只对目标自身已接入且平台适用的项目判定规则；父工作区安装不启用子项目。移动端与未接入开源项目不套用。详见 [精准触发与范围配置](docs/project-scope.md)。
+
 **企业级 UI 一致性与 AI 精确治理工具包 v1.17.0** — 面向 Vue 3 + Element Plus 的设计令牌、能力 Profile、样式皮肤、页面骨架、运行时能力、静态扫描、确定性修复、AI Skill、MCP 与脱敏 UI 模板契约。
 
 它把“视觉统一、问题识别、机械修复、项目适配和样例沉淀”拆成可验证、可组合的工程能力。脚本、规则和 MCP 先完成确定性工作，AI 只处理业务语义与人工决策，从而减少重复读源码、上下文 token 和误修改。
@@ -508,7 +510,7 @@ npx wl-ui doctor --project . --print-overrides
 
 ## 版本与进一步阅读
 
-当前 v1.17.0：公开集成协议 describe/request 统一信封（能力清单与路由语料经真实打包产物验证）、输入校验收口与 MCP 目录对齐真实 tools/list。v1.15.0：任务判定、真实执行/验证回执、实际检查范围和过期检测；Codex 原生薄入口按需加载 canonical Skill。确定性路由覆盖已发布目录与显式缺口，不保证识别所有自然语言。v1.14.0：明确独立能力边界，安装、更新、清理按本包贡献保护用户及其他包内容；共享文件采用单文件原子替换，支持历史路由与 `.clinerules` 目录迁移。v1.13.2：R044 审查多列表单超宽标签，R040 识别自定义 `stepper`，均供人工复核。v1.13.0：新增 `native-jh-ag` Profile、显式 Profile 兼容承诺与联邦 AG 依赖识别。
+当前 v1.19.0：公开集成协议 describe/request 统一信封（能力清单与路由语料经真实打包产物验证）、输入校验收口与 MCP 目录对齐真实 tools/list。v1.15.0：任务判定、真实执行/验证回执、实际检查范围和过期检测；Codex 原生薄入口按需加载 canonical Skill。确定性路由覆盖已发布目录与显式缺口，不保证识别所有自然语言。v1.14.0：明确独立能力边界，安装、更新、清理按本包贡献保护用户及其他包内容；共享文件采用单文件原子替换，支持历史路由与 `.clinerules` 目录迁移。v1.13.2：R044 审查多列表单超宽标签，R040 识别自定义 `stepper`，均供人工复核。v1.13.0：新增 `native-jh-ag` Profile、显式 Profile 兼容承诺与联邦 AG 依赖识别。
 
 - [版本摘要](docs/version-history.md)
 - [完整 Changelog](CHANGELOG.md)
@@ -530,3 +532,15 @@ npm run pack:dry
 ```
 
 视觉测试基线按操作系统管理；如果本机没有对应平台截图，完整 `test:visual` 会明确报告缺失，不应自动生成并提交一套未经评审的新基线。发布门禁使用跨浏览器计算样式契约 `test:visual:contracts`；真实浏览器兼容契约也可以单独执行 `browser-compat.spec.ts`。
+
+### 当前请求、动作边界与 Harness 集成
+
+任务判定保留原始文本，并将当前请求、历史引用和明确否定分开。自然语言判定覆盖已公开语料与规则，不能承诺任意表述都自动命中；遇到歧义或缺口应补充目标/领域或显式指定本包能力，不能静默选择。编辑前显示真实 `notice`，包括版本、技能、规则、目标、runId、动作与待检查项。
+
+`protocol describe --json` 声明 `task-intent-v1`、`result-core-v1`、`executor-catalog-v1`；`schemas.resultCore` 与五操作 `schemas.results` 可供宿主验证。原有结果字段保留，新增 `result.integration`：项目适用范围、动作模式、规则身份、目标、就绪状态、允许执行器和真实执行/验证状态。`ok` 只表示调用成功。未声明使用的输入字段进入 diagnostics，不会转成授权依据。
+
+`action.mode` 为 explain/plan/inspect/apply/unspecified；解释和规划不自动启动检查。`businessWritesAuthorized=false`，任务意图不能替代业务写入授权。`ruleRefs` 为包自有规则身份（包名、规则 ID、版本、来源、性质），自然语言约束有稳定 ID；原规则名称与列表保留。所有规则的机械/语义验证仍以实际回执为准。
+
+`inventory.executors` 声明本包业务只读检查器、目标与参数 Schema；其适用条件由本包判定。外部适配器须核对同项目、同包、同版本、同 runId 的真实计划、新鲜度与允许动作，指定一个目标，不能扩大范围；支持规则子集的执行器不得选择计划外规则。多目标需拆分调用。五包和 Harness 均为可选组合，不新增兄弟包或 Harness 运行时依赖；卸下适配器后原 CLI/MCP 继续独立使用。
+
+样式规则检查使用 `scan`（支持计划内规则子集）；`check` 只核验接入完整性。技能触发词由本包 `bin/task-triggers.json` 维护并接受目录一致性检查。

package/SKILL.md

@@ -1,11 +1,15 @@
 ---
 name: wl-skills-ui
 description: |
+  Only for PC Vue admin projects that adopted wl-skills-ui; excludes mobile and unadopted projects.
   Audit and align Vue 3 + Element Plus enterprise UI projects with deterministic
   scanning, profile-aware fixes, design tokens, vendor adapters, and runtime guards.
   Use for UI consistency, legacy skin migration, rule diagnostics, or safe UI fixes.
 ---
 
+先确认目标项目自身的接入证据（本包安装清单、直接依赖或 `.wl-skills-scope.json` 显式启用），再判定任务。只在目标已接入且平台适用时读取规则；父目录安装、兄弟包、Vue 文件或触发词不能证明接入。未接入的开源项目不套用规则、不建议自动安装；UniApp/小程序/App/PDA/移动 H5 不适用。跨项目目标分别判定，沿最近项目边界停止，不能越过未接入子项目找父清单。工具返回 `scope` 作为静态范围证据，宿主加载仍需实际事件。
+
+
 # wl-skills-ui
 
 Use deterministic project facts before reading or editing business source. Rules,

package/bin/__tests__/protocol-cli.test.mjs

@@ -3,7 +3,7 @@
  */
 import { test } from "node:test";
 import assert from "node:assert/strict";
-import { mkdtempSync } from "node:fs";
+import fs, { mkdtempSync } from "node:fs";
 import { tmpdir } from "node:os";
 import path from "node:path";
 import { spawnSync } from "node:child_process";
@@ -17,7 +17,9 @@ const pkg = require("../../package.json");
 const BIN = path.join(here, "..", "wl-ui.js");
 
 function tempRoot() {
-  return mkdtempSync(path.join(tmpdir(), "wl-ui-protocol-"));
+  const root = mkdtempSync(path.join(tmpdir(), "wl-ui-protocol-"));
+  fs.writeFileSync(path.join(root, "package.json"), JSON.stringify({ devDependencies: { "@agile-team/wl-skills-ui": "*" } }));
+  return root;
 }
 
 test("describe 返回协议版本、能力目录与五个统一操作", () => {

package/bin/__tests__/protocol-evidence.test.mjs

@@ -3,14 +3,16 @@
  */
 import { test } from "node:test";
 import assert from "node:assert/strict";
-import { mkdtempSync } from "node:fs";
+import fs, { mkdtempSync } from "node:fs";
 import { tmpdir } from "node:os";
 import path from "node:path";
 
 const { protocol, runOperation } = await import("../protocol-cli.mjs");
 
 function tempRoot() {
-  return mkdtempSync(path.join(tmpdir(), "wl-ui-evidence-"));
+  const root = mkdtempSync(path.join(tmpdir(), "wl-ui-evidence-"));
+  fs.writeFileSync(path.join(root, "package.json"), JSON.stringify({ devDependencies: { "@agile-team/wl-skills-ui": "*" } }));
+  return root;
 }
 
 test("status 严格回查同一 runId：字段精确、不兜底", () => {

package/bin/__tests__/protocol-routing.test.mjs

@@ -4,7 +4,7 @@
  */
 import { test, before } from "node:test";
 import assert from "node:assert/strict";
-import { mkdtempSync, rmSync } from "node:fs";
+import fs, { mkdtempSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
 import path from "node:path";
 import { spawnSync } from "node:child_process";
@@ -22,6 +22,7 @@ function tempRoot() {
 }
 
 function routeAt(projectRoot, task) {
+  if (!fs.existsSync(path.join(projectRoot, "package.json"))) fs.writeFileSync(path.join(projectRoot, "package.json"), JSON.stringify({ devDependencies: { "@agile-team/wl-skills-ui": "*" } }));
   return protocol.request({ operation: "route", projectRoot, task }, runOperation);
 }
 
@@ -40,7 +41,7 @@ for (const item of cases) {
   const expectedBare = item.skill ? "gap" : item.status;
   const expectedInstalled = item.installedStatus || (item.skill ? "matched" : item.status);
 
-  test(`未安装：「${item.task}」→ ${expectedBare}${item.skill ? ` + ${item.skill}` : ""}`, () => {
+  test(`已声明接入但未初始化：「${item.task}」→ ${expectedBare}${item.skill ? ` + ${item.skill}` : ""}`, () => {
     const envelope = routeAt(tempRoot(), item.task);
     assert.equal(envelope.ok, true);
     const decision = envelope.result.decision || envelope.result;

package/bin/__tests__/task-intent-cases.json

@@ -0,0 +1,34 @@
+[
+  {
+    "task": "旧需求写过“UI迁移迁移tokens”，本次只审查表单尺寸",
+    "status": "matched",
+    "skills": [
+      "element/el-form"
+    ],
+    "mode": "inspect"
+  },
+  {
+    "task": "不要迁移tokens，只检查现有表单样式",
+    "status": "matched",
+    "skills": [
+      "element/el-form"
+    ],
+    "mode": "inspect"
+  },
+  {
+    "task": "只说明 UI修复 的影响，不执行修改",
+    "status": "matched",
+    "skills": [
+      "ops/fix"
+    ],
+    "mode": "explain"
+  },
+  {
+    "task": "迁移tokens",
+    "status": "matched",
+    "skills": [
+      "ops/migrate"
+    ],
+    "mode": "apply"
+  }
+]

package/bin/__tests__/task-intent-routing.test.mjs

@@ -0,0 +1,41 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import {spawnSync} from 'node:child_process';
+const dirname = import.meta.dirname;
+const repo = path.resolve(dirname, "../..");
+const pkg = JSON.parse(fs.readFileSync(path.join(repo, 'package.json'), 'utf8'));
+const cli = path.join(repo, 'bin/wl-ui.js');
+const cases = JSON.parse(fs.readFileSync(path.join(dirname, 'task-intent-cases.json'), 'utf8'));
+const key = "ui";
+test('当前请求、否定、历史引用与只讨论：公开协议精确回归', () => {
+  const temporary = fs.mkdtempSync(path.join(os.tmpdir(), 'wl-intent-ui-'));
+  const project = path.join(temporary, 'project');fs.mkdirSync(project);
+  const run = args => {
+    const result = spawnSync(process.execPath,[cli,...args],{cwd:project,encoding:'utf8',timeout:30000});
+    assert.equal(result.status,0,result.stderr || result.stdout);return result.stdout;
+  };
+  try {
+    fs.writeFileSync(path.join(project,'package.json'),JSON.stringify({private:true,devDependencies:{[pkg.name]:'*'}}));
+    const scoped = path.join(project,'node_modules/@agile-team');fs.mkdirSync(scoped,{recursive:true});fs.symlinkSync(repo,path.join(scoped,'wl-skills-ui'),'dir');
+    run(['init','--project',project,'--editor','agents-generic','--profile','native-element','--skills-only']);
+    for(const row of cases){
+      if(row.javaProject)fs.writeFileSync(path.join(project,'pom.xml'),'<project><modelVersion>4.0.0</modelVersion><groupId>audit</groupId><artifactId>fixture</artifactId><version>1</version></project>');
+      const file = path.join(temporary,'request.json');
+      fs.writeFileSync(file,JSON.stringify({operation:'route',projectRoot:project,task:row.task,...(row.domain ? {domain:row.domain} : {})}));
+      const envelope = JSON.parse(run(['protocol','request','--input-file',file,'--json']));
+      assert.equal(envelope.ok,true,row.task);const d = envelope.result.decision || envelope.result;
+      assert.equal(d.status,row.status,row.task);assert.deepEqual(d.selectedSkills,row.skills,row.task);
+      if(row.rules)assert.deepEqual(d.requiredRules,row.rules,row.task);
+      assert.equal(d.action.mode,row.mode,row.task);assert.equal(d.action.businessWritesAuthorized,false);
+      if(row.mode === 'explain')assert.equal(d.action.checksAllowed,false);
+      const core = envelope.result.integration;assert.equal(core.packageName,pkg.name);assert.equal(core.packageVersion,pkg.version);
+      assert.equal(core.contractVersion,1);assert.equal(core.runId,null);
+      assert.ok(core.ruleRefs.every(rule => rule.packageName === pkg.name && rule.ruleVersion === pkg.version));
+    }
+    const storage = {kit:'.wl-skills',ui:'.wl-skills-ui',bd:'.wl-skills-bd',design:'.wl-skills-design',test:'.wl-skills-test'}[key];
+    assert.equal(fs.existsSync(path.join(project,storage,'runs')),false,'route 不写任务记录');
+  } finally {fs.rmSync(temporary,{recursive:true,force:true});}
+});

package/bin/__tests__/task-trigger-catalog.test.mjs

@@ -0,0 +1,7 @@
+import test from 'node:test';import assert from 'node:assert/strict';import fs from 'node:fs';
+import {taskCatalog} from '../task-integration.mjs';
+test('触发词清单与本包技能目录双向完整且不含空词',() => {
+ const triggers = JSON.parse(fs.readFileSync(new URL('../task-triggers.json',import.meta.url),'utf8'));const catalog = taskCatalog();
+ assert.deepEqual(Object.keys(triggers).sort(),catalog.map(s => s.id).sort());
+ for(const skill of catalog){assert.ok(skill.triggers.length,skill.id);assert.ok(skill.triggers.every(p => typeof p === 'string' && p.trim()));assert.deepEqual(skill.triggers,triggers[skill.id]);}
+});

package/bin/executors.json

@@ -0,0 +1,48 @@
+[
+  {
+    "id": "scan",
+    "command": [
+      "scan"
+    ],
+    "when": {
+      "checks": [
+        "scan"
+      ]
+    },
+    "parameters": {
+      "type": "object",
+      "required": [
+        "targets"
+      ],
+      "properties": {
+        "targets": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1,
+            "pattern": "\\S"
+          },
+          "minItems": 1,
+          "maxItems": 1
+        },
+        "rules": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "pattern": "^R[0-9]{3}$"
+          },
+          "minItems": 1,
+          "uniqueItems": true
+        }
+      },
+      "additionalProperties": false
+    },
+    "sideEffects": {
+      "business": "none",
+      "records": true,
+      "reports": "stdout"
+    },
+    "authorization": "read-only-business-check",
+    "receipt": "package-execution-record-v1"
+  }
+]

package/bin/integration-protocol.cjs

@@ -16,6 +16,7 @@
  */
 
 const PROTOCOL_VERSION = 1;
+const resultCore = require("./integration-result.cjs");
 const SUPPORTED_VERSIONS = [1];
 const ERROR_CODES = ["unsupported-protocol", "unknown-operation", "missing-input", "invalid-input", "internal-error"];
 const OPTIONAL_STRING_FIELDS = ["requestId", "runId", "projectRoot", "skill", "host", "type", "domain", "profile"];
@@ -233,6 +234,7 @@ function validateFieldTypes(input) {
       commands: inventory.commands || [],
       mcpTools: inventory.mcpTools || [],
       loadErrors: inventory.loadErrors || [],
+      executors: config.executors || [],
       note: "业务执行仍走各包原 CLI/MCP；inventory 只声明公开调用映射与入口，不改变执行归属；loadErrors 非空表示目录派生存在异常，不得忽略",
     };
   }
@@ -255,9 +257,11 @@ function validateFieldTypes(input) {
       return {
         ...base(null, null),
         capabilities: config.capabilities || [],
+        features: ["task-intent-v1", "result-core-v1", "executor-catalog-v1"],
         operations: config.operations.map((operation) => ({ ...operation })),
         inventory: buildInventory(config),
-        schemas: { request: requestSchema(config), envelope: envelopeSchema(config.packageName) },
+        schemas: { request: requestSchema(config), envelope: envelopeSchema(config.packageName), resultCore: resultCore.SCHEMA,
+          results: Object.fromEntries(config.operations.map((operation) => [operation.id, { type: "object", required: ["integration"], properties: { integration: resultCore.SCHEMA }, additionalProperties: true }])) },
         constraints: buildConstraints(config),
         errorCodes: [...ERROR_CODES],
       };
@@ -267,8 +271,13 @@ function validateFieldTypes(input) {
       const { operation, error } = validateRequest(input);
       if (error) return error;
       const diagnostics = [];
+      const supportedFields = new Set(["operation", "protocolVersion", "requestId", ...operation.required, ...(operation.requireAny || []), ...operation.optional]);
+      for (const field of Object.keys(input)) {
+        if (!supportedFields.has(field)) diagnostics.push(`操作 ${operation.id} 未声明使用字段 ${field}；该字段不构成执行或授权依据`);
+      }
       try {
-        const result = runOperation(operation.id, input, diagnostics) ?? {};
+        const original = runOperation(operation.id, input, diagnostics) ?? {};
+        const result = resultCore.projectResult(original, input, config);
         return { ...base(operation.id, input.requestId), ok: true, result, diagnostics };
       } catch (thrown) {
         diagnostics.push(String((thrown && thrown.message) || thrown));

package/bin/integration-result.cjs

@@ -0,0 +1,76 @@
+"use strict";
+
+// Additive, typed core: original package-specific result fields are preserved.
+const path = require("node:path");
+const DECISIONS = ["matched", "baseline", "gap", "ambiguous", "not-applicable", "needs-context"];
+const strings = (items) => Array.isArray(items) ? items.filter((value) => typeof value === "string") : [];
+const nullableString = { type: ["string", "null"] };
+const SCHEMA = {
+  type: "object", additionalProperties: false,
+  required: ["contractVersion", "packageName", "packageVersion", "projectRoot", "runId", "decisionStatus", "scope", "action", "selectedSkills", "ruleRefs", "requiredChecks", "targets", "ready", "executionStatus", "validationStatus", "stale", "planStale", "allowedExecutors"],
+  properties: {
+    contractVersion: { const: 1 }, packageName: { type: "string", minLength: 1 }, packageVersion: { type: "string", minLength: 1 },
+    projectRoot: { type: "string", minLength: 1 }, runId: nullableString,
+    decisionStatus: { enum: [...DECISIONS, null] }, scope: { oneOf: [{type:"null"}, {type:"object",required:["schemaVersion","status","reason","adopted","projectType","inherited"],
+      properties:{schemaVersion:{const:1},status:{enum:["applicable","not-applicable","needs-context"]},reason:{type:"string"},adopted:{type:"boolean"},projectType:{type:"string"},inherited:{const:false}},additionalProperties:true}] },
+    action: { oneOf: [{ type: "null" }, { type: "object", required: ["mode", "checksAllowed", "businessWritesAuthorized", "authorization"],
+      properties: { mode: { enum: ["explain", "inspect", "plan", "apply", "unspecified"] }, checksAllowed: { type: "boolean" }, businessWritesAuthorized: { const: false }, authorization: { type: "string" } }, additionalProperties: false }] },
+    selectedSkills: { type: "array", items: { type: "string" } }, requiredChecks: { type: "array", items: { type: "string" } },
+    targets: { type: "array", items: { type: "string" } }, allowedExecutors: { type: "array", items: { type: "string" } },
+    ruleRefs: { type: "array", items: { type: "object", required: ["packageName", "ruleId", "legacyId", "name", "ruleVersion", "source", "kind", "verification"],
+      properties: { packageName: nullableString, ruleId: { type: "string" }, legacyId: { type: "string" }, name: { type: "string" }, ruleVersion: nullableString, source: nullableString, kind: { type: "string" }, verification: { const: "unverified" } }, additionalProperties: false } },
+    ready: { type: ["boolean", "null"] }, executionStatus: nullableString, validationStatus: nullableString,
+    stale: { type: ["boolean", "null"] }, planStale: { type: ["boolean", "null"] },
+  },
+};
+
+function allowedExecutors(decision, executors) {
+  if (!["matched", "baseline"].includes(decision.status) || !decision.action?.checksAllowed) return [];
+  return executors.filter((executor) => {
+    const when = executor.when || {};
+    return strings(when.skills).some((id) => decision.selectedSkills?.includes(id))
+      || strings(when.checks).some((id) => decision.requiredChecks?.includes(id))
+      || strings(when.rulePrefixes).some((prefix) => decision.requiredRules?.some((id) => id.startsWith(prefix)));
+  }).map((executor) => executor.id);
+}
+
+function resultReadiness(result, decision, status) {
+  if (typeof result.ready === "boolean") return result.ready;
+  if (typeof decision.ready === "boolean") return decision.ready;
+  return status ? ["matched", "baseline"].includes(status) && !(decision.missingInputs || []).length : null;
+}
+
+function executionState(result) {
+  return {
+    runId: result.runId || null,
+    executionStatus: result.executionStatus || null,
+    validationStatus: result.validationStatus || null,
+    stale: typeof result.stale === "boolean" ? result.stale : null,
+    planStale: typeof result.planStale === "boolean" ? result.planStale : null,
+  };
+}
+
+function decisionReadout(decision) {
+  return {action:decision.action || null, selectedSkills:strings(decision.selectedSkills), ruleRefs:decision.ruleRefs || [], requiredChecks:strings(decision.requiredChecks)};
+}
+function targetReadout(result,input) { return strings(result.targets || input.targets || result.notice?.targets); }
+function projectIdentity(scope,result,input) { return path.resolve(scope?.projectRoot || result.projectRoot || result.root || input.projectRoot || process.cwd()); }
+
+function projectResult(result, input, config) {
+  const decision = result.decision || result;
+  const scope = result.currentScope || decision.scope || result.scope || null;
+  const status = DECISIONS.includes(decision.status) ? decision.status : null;
+  const ready = resultReadiness(result, decision, status);
+  return {
+    ...result,
+    integration: {
+      contractVersion: 1, packageName: config.packageName, packageVersion: config.packageVersion,
+      projectRoot: projectIdentity(scope,result,input),
+      ...executionState(result), decisionStatus: status, scope,
+      ...decisionReadout(decision), targets: targetReadout(result,input), ready,
+      allowedExecutors: ready && scope?.status === "applicable" ? allowedExecutors(decision, config.executors || []) : [],
+    },
+  };
+}
+
+module.exports = { SCHEMA, projectResult };

package/bin/project-scope.cjs

@@ -0,0 +1,198 @@
+"use strict";
+
+// Independent snapshot: project adoption is checked before skill intent or writes.
+const fs = require("node:fs");
+const path = require("node:path");
+const crypto = require("node:crypto");
+const CONFIG = ".wl-skills-scope.json";
+const MANIFESTS = {
+  kit: ".wl-skills-manifest.json", ui: ".wl-skills-ui-manifest.json",
+  bd: ".wl-skills-bd-manifest.json", design: ".wl-skills-design/state.json", test: ".wl-skills-test/manifest.json",
+};
+const TYPES = new Set(["pc", "backend", "documents", "testing", "mobile", "workspace", "unknown"]);
+
+function inside(root, target) {
+  const rel = path.relative(root, target);
+  return !path.isAbsolute(rel) && rel !== ".." && !rel.startsWith(`..${path.sep}`);
+}
+
+// Resolve missing paths through their nearest existing ancestor, including symlinks.
+function realTarget(target) {
+  if (fs.existsSync(target)) return fs.realpathSync(target);
+  const parent = path.dirname(target);
+  if (parent === target) throw new Error("Cannot resolve target ancestor");
+  return path.join(realTarget(parent), path.basename(target));
+}
+
+function readJson(root, relative) {
+  const file = path.join(root, relative);
+  if (!fs.existsSync(file)) return { present: false, value: null };
+  try {
+    if (!inside(root, fs.realpathSync(file))) throw new Error("metadata path escapes project");
+    const value = JSON.parse(fs.readFileSync(file, "utf8"));
+    if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("expected object");
+    return { present: true, value };
+  } catch (error) { return { present: true, value: null, error: `${relative}: ${error.message}` }; }
+}
+
+function boundary(root, fallback) {
+  const markers = ["package.json", ".git", CONFIG, ...Object.values(MANIFESTS)];
+  // A Java project's Maven modules share its adoption; a nested independent repo still stops lookup.
+  if (root === fallback || !fs.existsSync(path.join(fallback, "pom.xml"))) markers.push("pom.xml");
+  return markers.some((file) => fs.existsSync(path.join(root, file)));
+}
+
+function nearestRoot(target, fallback) {
+  let dir = fs.existsSync(target) && fs.statSync(target).isDirectory() ? target : path.dirname(target);
+  while (inside(fallback, dir)) {
+    if (boundary(dir, fallback) || dir === fallback) return dir;
+    dir = path.dirname(dir);
+  }
+  return null;
+}
+
+function targetRoots(root, targets) {
+  const resolved = targets.map((target) => realTarget(path.resolve(root, target)));
+  if (resolved.some((target) => !inside(root, target))) return { error: "target-outside-authorized-project", roots: [], resolved };
+  return { roots: [...new Set(resolved.map((target) => nearestRoot(target, root)))], resolved };
+}
+
+function scopeConfig(root) {
+  const config = readJson(root, CONFIG);
+  if (!config.present || config.error) return config;
+  const { value } = config;
+  const allowed = ["schemaVersion", "projectType", "packages"];
+  if (value.schemaVersion !== 1 || !TYPES.has(value.projectType) || Object.keys(value).some((key) => !allowed.includes(key)) || !validPackageSwitches(value.packages)) {
+    return { ...config, error: `${CONFIG}: invalid schemaVersion/projectType/packages` };
+  }
+  return config;
+}
+
+function validPackageSwitches(packages) {
+  if (packages === undefined) return true;
+  return Boolean(packages && typeof packages === "object" && !Array.isArray(packages) && Object.entries(packages).every(([key, enabled]) => Object.hasOwn(MANIFESTS, key) && typeof enabled === "boolean"));
+}
+
+function mobileEvidence(root, pkg) {
+  const deps = Object.keys({ ...pkg.dependencies, ...pkg.devDependencies });
+  const mobile = deps.filter((name) => /^@dcloudio\/uni(?:-|$)|^@tarojs\/|^react-native$|^expo$|^@ionic\/|^@capacitor\//.test(name));
+  if (fs.existsSync(path.join(root, "pages.json")) && fs.existsSync(path.join(root, "manifest.json"))) mobile.push("pages.json+manifest.json");
+  return mobile;
+}
+
+function adoption(root, key, packageName, pkg, config) {
+  const manifest = readJson(root, MANIFESTS[key]);
+  validateAdoptionManifest(manifest, key, packageName);
+  const declared = [pkg.dependencies, pkg.devDependencies, pkg.optionalDependencies].some((deps) => deps?.[packageName]);
+  const explicit = config.value?.packages?.[key] === true;
+  const installed = manifest.present && !manifest.error;
+  return { adopted: explicit || declared || installed, sources: [
+    ...(explicit ? [`${CONFIG}:packages.${key}`] : []), ...(declared ? ["package.json:direct-dependency"] : []),
+    ...(installed ? [MANIFESTS[key]] : []),
+  ], error: manifest.error || null };
+}
+
+function validateAdoptionManifest(manifest, key, packageName) {
+  if (!manifest.present || manifest.error) return;
+  const { value } = manifest;
+  if (typeof value.version !== "string" || !value.version.trim() || value.package && value.package !== packageName) manifest.error = `${MANIFESTS[key]}: invalid package/version`;
+}
+
+function verdict(status, reason, extra = {}) {
+  return { schemaVersion: 1, status, reason, adopted: false, projectType: "unknown", evidence: [], inherited: false, ...extra };
+}
+
+function inspectProject(root, key, packageName) {
+  const config = scopeConfig(root);
+  const packageFile = readJson(root, "package.json");
+  if (config.error || packageFile.error) return verdict("needs-context", "invalid-project-metadata", { diagnostics: [config.error || packageFile.error] });
+  const pkg = packageFile.value || {};
+  if (!["dependencies", "devDependencies", "optionalDependencies"].every((field) => validDependencies(pkg[field]))) {
+    return verdict("needs-context", "invalid-project-metadata", { diagnostics: ["package.json: dependency declarations must be nonempty strings"] });
+  }
+  const exclusion = platformExclusion(root, key, pkg, config);
+  if (exclusion) return exclusion;
+  const own = adoption(root, key, packageName, pkg, config);
+  if (own.error) return verdict("needs-context", "invalid-package-adoption", { diagnostics: [own.error] });
+  if (!own.adopted) return verdict("not-applicable", "package-not-adopted-in-target-project");
+  return adoptedScope(root, key, pkg, config, own);
+}
+
+function validDependencies(deps) {
+  if (deps === undefined) return true;
+  return Boolean(deps && typeof deps === "object" && !Array.isArray(deps) && Object.values(deps).every((value) => typeof value === "string" && value.trim()));
+}
+
+function platformExclusion(root, key, pkg, config) {
+  const mobile = mobileEvidence(root, pkg);
+  const type = config.value?.projectType;
+  if (mobile.length || type === "mobile") return verdict("not-applicable", "mobile-project-excluded", { projectType: "mobile", evidence: mobile.length ? mobile : [CONFIG] });
+  if (type === "workspace") return verdict("not-applicable", "aggregate-workspace-is-not-project", { projectType: type, evidence: [CONFIG] });
+  if (config.value?.packages?.[key] === false) return verdict("not-applicable", "package-explicitly-disabled", { projectType: type || "unknown", evidence: [CONFIG] });
+  return null;
+}
+
+function unsupportedFrontend(root, key, pkg, type) {
+  if (!["kit", "ui"].includes(key)) return false;
+  if (type && type !== "pc") return "pc-frontend-package-excluded";
+  const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+  return !deps.vue && (deps.react || deps.svelte || deps["@angular/core"] || fs.existsSync(path.join(root, "pom.xml"))) ? "unsupported-project-framework" : false;
+}
+
+function defaultType(key) { return { kit: "pc", ui: "pc", bd: "backend", design: "documents", test: "testing" }[key]; }
+
+function scopeFingerprint(root, key) {
+  const metadata = [CONFIG, "package.json", "pom.xml", MANIFESTS[key], "pages.json", "manifest.json"].map((file) => {
+    const full = path.join(root, file);
+    if (!fs.existsSync(full)) return [file, "missing"];
+    if (!inside(root, fs.realpathSync(full))) return [file, "external-metadata"];
+    try { return [file, crypto.createHash("sha256").update(fs.readFileSync(full)).digest("hex")]; }
+    catch (error) { return [file, `unreadable:${error.code}`]; }
+  });
+  return crypto.createHash("sha256").update(JSON.stringify(metadata)).digest("hex");
+}
+
+function adoptedScope(root, key, pkg, config, own) {
+  const type = config.value?.projectType;
+  if (type === "unknown") return verdict("needs-context", "project-platform-needs-context", { adopted: true, evidence: own.sources });
+  const unsupported = unsupportedFrontend(root, key, pkg, type);
+  if (unsupported) return verdict("not-applicable", unsupported, { adopted: true, projectType: type || "unknown", evidence: ["package.json/pom.xml", ...own.sources] });
+  return verdict("applicable", "target-project-explicitly-adopted-package", {
+    adopted: true, projectType: type || defaultType(key),
+    typeEvidence: type ? "explicit-config" : "adoption-default-not-host-observed", evidence: own.sources,
+  });
+}
+
+/** Parent installation, Vue files and keyword matches are never adoption evidence. */
+function resolveScope({ projectRoot, packageName, targets = [] }) {
+  const root = fs.realpathSync(path.resolve(projectRoot || process.cwd()));
+  const key = packageName.replace("@agile-team/wl-skills-", "");
+  if (!Object.hasOwn(MANIFESTS, key)) throw new Error("Unknown WL package");
+  const located = targetRoots(root, targets.filter((item) => typeof item === "string" && item.trim()));
+  if (located.error || located.roots.length > 1) return { projectRoot: root, targets, scope: verdict("needs-context", located.error || "multiple-project-targets-split-required", { projectRoots: located.roots }) };
+  const actualRoot = located.roots[0] || root;
+  const actualTargets = located.resolved.map((target) => path.relative(actualRoot, target).split(path.sep).join("/") || ".");
+  return { projectRoot: actualRoot, targets: actualTargets, scope: { ...inspectProject(actualRoot, key, packageName), projectRoot: actualRoot, fingerprint: scopeFingerprint(actualRoot, key) } };
+}
+
+function excludedDecision(scope) {
+  const messages = {
+    "mobile-project-excluded": "目标为移动端/UniApp/小程序项目，不适用本轮WL项目约束",
+    "aggregate-workspace-is-not-project": "目标是聚合工作区，请指定实际已接入项目",
+    "package-explicitly-disabled": "目标项目已明确禁用本包",
+    "package-not-adopted-in-target-project": "目标项目未接入本包，不继承父目录或兄弟项目的安装",
+    "pc-frontend-package-excluded": "目标项目不是已接入的PC前端，PC规范不适用",
+    "unsupported-project-framework": "目标技术栈不是本包支持的Vue管理端，不套用PC Vue规范",
+    "multiple-project-targets-split-required": "目标跨越多个项目，请按项目分别判定并复用任务runId",
+    "target-outside-authorized-project": "目标超出当前授权项目边界，请从实际目标项目根调用",
+    "project-platform-needs-context": "项目已接入但平台未确认，请确认PC/后端/文档/测试或移动端范围",
+  };
+  const reason = messages[scope.reason] || "项目范围元数据无效，需要核对后再应用规则";
+  return { recordVersion: 1, status: scope.status, applicable: scope.status === "needs-context" ? null : false,
+    reason, reasons: [reason], scope, selectedSkills: [], candidates: [], baselineRules: [], requiredRules: [],
+    ruleDetails: [], requiredChecks: [], requiredFiles: [], missingInputs: scope.status === "needs-context" ? ["有效的目标项目范围"] : [],
+    gaps: [], constraints: [], ready: false, executionStatus: "not-executed", validationStatus: "unverified",
+    selectionEvidence: "project-scope-before-intent", hostDiscovery: "unverified", contentLoaded: "unverified", unverified: ["host-discovery", "model-read-canonical-files"] };
+}
+
+module.exports = { CONFIG, MANIFESTS, resolveScope, excludedDecision };

package/bin/project-scope.schema.json

@@ -0,0 +1,48 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "urn:wl-skills:project-scope:1",
+  "title": "Explicit WL project scope and per-package adoption",
+  "type": "object",
+  "required": [
+    "schemaVersion",
+    "projectType"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "schemaVersion": {
+      "const": 1
+    },
+    "projectType": {
+      "enum": [
+        "pc",
+        "backend",
+        "documents",
+        "testing",
+        "mobile",
+        "workspace",
+        "unknown"
+      ]
+    },
+    "packages": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "kit": {
+          "type": "boolean"
+        },
+        "ui": {
+          "type": "boolean"
+        },
+        "bd": {
+          "type": "boolean"
+        },
+        "design": {
+          "type": "boolean"
+        },
+        "test": {
+          "type": "boolean"
+        }
+      }
+    }
+  }
+}