@agile-team/wl-skills-gate 0.12.0 → 0.13.1

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # 变更记录
 
+## [0.13.1] — 2026-10-22
+
+- Jenkins安装自动记录实际Node目录；服务器命令别名使用固定Node绝对路径，公共入口及各角色任务自动设置Node/npm的PATH。各节点可用受控WL_NODE_BIN_DIR覆盖本机差异。
+- 接入交付启动器支持WL_NODE_BIN_DIR与现场Node路径，所有安装子进程共用同一套Node/npm；启动前核验执行器原件，脚本被编辑或函数被删除时给出明确恢复提示。
+- 增加精简PATH、自定义Node路径、原件恢复与跨节点环境回归，保留完整性校验及严格构建准入。
+
+## [0.13.0] — 2026-10-22
+
+- Jenkins服务器公共入口随Gate安装，按实际Job识别检查、构建、中央、签发和维护角色；一个fleet任务批量配置，预览确认、回读、续跑及回退均留记录。
+- 节点准备与配置核对合并为同一入口；工程配置缺项列出责任人与下一步，补齐重跑，无需重复安装。缺Node或Gate时使用独立Python自检并尝试签名通知，保留真实失败结果。
+- CHECK独立发布九维详情；正式Review授权后按当前SHA严格准入并续建，归档实际制品；项目／流水线机器人分类通知、去重提醒、修复复扫与独立复验保持可追溯。
+- 统一接入主说明、固定版本与安装产物清单，移除旧步骤引导；项目与Jenkins接入均调用包内核心。真实Jenkins、SSO、群@与报告权限仍按现场清单验收。
+
 ## [0.12.0] — 2026-10-19
 
 - 完整接入固定code-scan-kit 1.1.0六引擎，提供离线分发打包、自动缓存与逐文件完整性核验；保留BD组织规则、原生HTML/CSV和统一指标。

package/README.md

@@ -33,7 +33,7 @@ Gate 是质量执行与裁决层，复用项目已有检查器和适用的 WL
 
 ## 快速接入
 
-技术经理拿到批准的 Gate 完整包后，打开 `templates/launchers/setup.command`（macOS）、`setup.cmd`（Windows）或 `setup.sh`（Linux），按菜单选择任务。先提供 Node.js 22.13+ 或 24+、项目固定的包管理器及原有构建工具。
+技术经理拿到批准的完整接入包后，填写`现场参数.json`，运行根目录`01_接入项目.sh`（macOS可双击`.command`）；运维使用运维包的`01_接入Jenkins.sh`。脚本安装固定包并调用Gate；所需参数与成功反馈见包内唯一主说明。先提供 Node.js 22.13+（22系列）或24+、项目固定的包管理器及原有构建工具。
 
 | 任务 | 人只需做什么 | 脚本完成什么 |
 | --- | --- | --- |
@@ -43,14 +43,14 @@ Gate 是质量执行与裁决层，复用项目已有检查器和适用的 WL
 | 运维接线 | 选择批准配置目录，预检后选择启动 | 核对配置/身份/凭据存在性/旧状态，启动中央采集与操作入口；消息默认预览 |
 | 组合发布输入 | 选择批准配置，确认组件与输出 | 从真实采集原件生成输入，核验来源、SHA、制品与兼容证据 |
 
-也可用一个命令启动相同交互流程；进入后无需复制计划摘要或拼接后续命令：
+已安装批准版本的维护者也可启动相同交互流程；进入后无需复制计划摘要或拼接后续命令：
 
 ```bash
-npx --yes --ignore-scripts --registry https://registry.npmjs.org/ \
-  --@agile-team:registry=https://registry.npmjs.org/ \
-  @agile-team/wl-skills-gate@0.12.0 setup project
+wl-quality init
 ```
 
+本轮统一使用`0.13.1`固定版本；交付包与批准安装源的版本和字节摘要须一致，安装脚本自动核验。
+
 | 项目 | 依赖装在哪里 | 业务构建 |
 | --- | --- | --- |
 | PC Vue 管理端，如 `wl-ui-produce` | 根 `package.json`：Gate / Kit / UI | 保留原前端构建 |
@@ -85,7 +85,7 @@ npx --yes --ignore-scripts --registry https://registry.npmjs.org/ \
 | 接线内容 | 入口 | 验证方式 |
 | --- | --- | --- |
 | GitLab MR、候选与受保护分支 | [CI 模板](./templates/ci) · [GitLab 指南](./docs/06-gitlab.md) | 违规候选不能合并，真实必需作业齐全 |
-| Jenkins 构建、制品与部署 | [Jenkins 指南](./docs/07-jenkins.md) | SHA、制品摘要、目标环境一致，缺证据拒绝推进 |
+| Jenkins 检查与构建 | 服务器本地公共入口，单维护任务批量接入／核验／回退；[Jenkins 指南](./docs/07-jenkins.md) | 两个Job共用包内入口，自动识别范围、核对配置与严格准入 |
 | 真实 CI 证据、身份与 Review | [可信 CI 采集](./docs/18-ci-source.md) · [九维 Review](./docs/19-nine-dimension-review.md) | 旧报告、缺证据、自审与过期批准被拒绝 |
 | 飞书通知、认领、超时与复验 | [中央执行接线](./templates/platform/README.md) | 实际送达、失败重试、认领和独立关闭均留记录 |
 

package/bin/wl-quality-setup.js

@@ -6,12 +6,12 @@ try {
   let args = process.argv.slice(2);
   if (!args.length) {
     if (!process.stdin.isTTY || !process.stdout.isTTY) throw new Error("启动菜单需要交互终端；自动任务请明确指定 project/workspace/central/branches/release-input 及其预览/确认参数");
-    console.log("\nWL · WORLD LEADING | 质量工程接入\n\n1 首次接入项目\n2 初始化已接项目的本机环境\n3 运维接线预检\n4 启动中央采集与操作入口（消息预览）\n5 生成组合发布输入\n6 生成同项目六分支中央接线\nEnter 退出\n");
+    console.log("\nWL · WORLD LEADING | 质量工程接入\n\n1 首次接入项目\n2 初始化已接项目的本机环境\n3 运维接线预检\n4 启动中央采集与操作入口（消息预览）\n5 生成组合发布输入\n6 生成同项目六分支中央接线\n7 生成Jenkins薄接入登记\n8 核验远端Jenkins接线\nEnter 退出\n");
     const prompt = createInterface({ input: process.stdin, output: process.stdout });
     const choice = (await prompt.question("请选择：")).trim(); prompt.close();
-    const modes = { "1": ["project"], "2": ["workspace"], "3": ["central"], "4": ["central", "--start", "--watch"], "5": ["release-input"], "6":["branches"] };
+    const modes = { "1": ["project"], "2": ["workspace"], "3": ["central"], "4": ["central", "--start", "--watch"], "5": ["release-input"], "6":["branches"], "7":['jenkins'], "8":['jenkins','--verify'] };
     if (!choice) process.exit(0);
-    if (!modes[choice]) throw new Error("请选择1到6");
+    if (!modes[choice]) throw new Error("请选择1到8");
     args = modes[choice];
   }
   process.exitCode = await runSetupCli(args);

package/bin/wl-quality.js

@@ -0,0 +1,28 @@
+#!/usr/bin/env node
+import path from 'node:path';
+import {existsSync} from 'node:fs';
+import {runSetupCli} from '../lib/setup.js';
+import {writeExclusiveJson} from '../lib/control-store.js';
+try {
+  const args=process.argv.slice(2),command=args.shift()||'init';
+  if(command==='--version'){const {GATE_VERSION,gateRuntimeHash}=await import('../lib/jenkins-integration.js');console.log('wl-quality '+GATE_VERSION+' '+gateRuntimeHash());}
+  else if(command==='init'){
+    const forwarded=[...args];let root=process.cwd();const index=forwarded.indexOf('--root');if(index>=0)root=path.resolve(forwarded[index+1]||'.');
+    const existing=existsSync(path.join(root,'quality/workspace.json'));
+    if(existing){const sourceIndex=forwarded.indexOf('--registry');if(sourceIndex>=0)forwarded.splice(sourceIndex,2);}
+    process.exitCode=await runSetupCli([existing?'workspace':'project',...forwarded]);
+  }else if(command==='jenkins'&&args[0]==='context'){
+    args.shift();const options={},flags=new Set(['--verify-entry']);
+    while(args.length){const k=args.shift();if(!['--role','--config','--out','--verify-entry'].includes(k)||Object.hasOwn(options,k))throw Error('未知或重复context参数');if(flags.has(k))options[k]=true;else{const v=args.shift();if(!v||v.startsWith('--'))throw Error('context参数缺值');options[k]=v;}}
+    const {resolveJenkinsContext,defaultClusterFile}=await import('../lib/jenkins-cluster.js');const result=await resolveJenkinsContext({role:options['--role'],configFile:options['--config']||defaultClusterFile(process.env),verifyEntry:options['--verify-entry']===true});
+    if(options['--out'])writeExclusiveJson(path.resolve(options['--out']),result);else process.stdout.write(JSON.stringify(result,null,2)+'\n');
+  }else if(command==='jenkins'&&args[0]==='install'){
+    args.shift();const o={};while(args.length){const k=args.shift();if(!['--config','--preview','--json','--confirm','--plan-hash'].includes(k)||Object.hasOwn(o,k))throw Error('未知或重复安装参数');if(['--preview','--json','--confirm'].includes(k))o[k]=true;else{const v=args.shift();if(!v||v.startsWith('--'))throw Error('安装参数缺值');o[k]=v;}}
+    if(!o['--config']||o['--preview']&&o['--confirm'])throw Error('安装需要--config，预览不能同时执行');
+    const {readControlledJson}=await import('../lib/control-store.js');const {planJenkinsInstallation,applyJenkinsInstallation}=await import('../lib/jenkins-installation.js');const input=readControlledJson(o['--config']),plan=planJenkinsInstallation(input);let result=plan;
+    if(o['--confirm'])result=applyJenkinsInstallation({...input,confirm:true,planHash:o['--plan-hash']});
+    else if(!o['--preview']&&process.stdin.isTTY&&process.stdout.isTTY&&!o['--json']){const {createInterface}=await import('node:readline/promises');console.log(JSON.stringify(plan,null,2));const prompt=createInterface({input:process.stdin,output:process.stdout});try{if((await prompt.question('输入1确认准备公共入口，Enter取消：')).trim()==='1')result=applyJenkinsInstallation({...input,confirm:true,planHash:plan.planHash});}finally{prompt.close();}}
+    console.log(JSON.stringify(result,null,2));
+  }else if(command==='jenkins'&&args[0]==='bootstrap'){args.shift();const {runBootstrapCli}=await import('../lib/jenkins-node-bootstrap.js');process.exitCode=await runBootstrapCli(args);}
+  else throw Error('用法：wl-quality init；wl-quality jenkins context|install|bootstrap。');
+}catch(error){console.error('[wl-quality] '+error.message);process.exitCode=2;}

package/bin/wl-skills-gate.js

@@ -73,12 +73,37 @@ function proofOptions(o) {
 try {
   if (command === "run") {
     process.exitCode = (await runGate({ argv: rest })).exitCode;
+  } else if (command === "report-publication") {
+    const action = rest.shift(), o = options(["--input", "--summary", "--review-index", "--out-dir", "--jenkins-build-url", "--manifest", "--jenkins-origin", "--user-env", "--token-env", "--out"]);
+    const r = await import("../lib/report-publication.js");
+    let result;
+    if (action === "archive") {
+      if (!!o["--input"] === !!o["--summary"] || !o["--out-dir"]) throw new Error("归档需要--input或--summary二选一，以及--out-dir");
+      const { readFileSync } = await import("node:fs");
+      const input = o["--input"] ? JSON.parse(readFileSync(o["--input"], "utf8")) : r.publicationInput({ summaryFile: o["--summary"], reviewIndexFile: o["--review-index"] });
+      result = r.archiveQualityReport({ input, outDir: path.resolve(o["--out-dir"]), jenkinsBuildUrl: o["--jenkins-build-url"] || process.env.BUILD_URL });
+    } else if (action === "verify") {
+      if (!o["--manifest"] || !(o["--jenkins-origin"] || process.env.JENKINS_URL)) throw new Error("验收需要--manifest和批准的Jenkins入口");
+      const userEnv = o["--user-env"] || "WL_JENKINS_REPORT_USER", tokenEnv = o["--token-env"] || "WL_JENKINS_REPORT_TOKEN";
+      if (![userEnv, tokenEnv].every((name) => /^[A-Z][A-Z0-9_]+$/.test(name))) throw new Error("凭据必须使用环境变量引用");
+      result = await r.verifyPublishedQualityReport({ manifestFile: o["--manifest"], expectedOrigin: o["--jenkins-origin"] || process.env.JENKINS_URL, user: process.env[userEnv], token: process.env[tokenEnv] });
+    } else throw new Error("report-publication仅支持archive或verify");
+    if (o["--out"]) {
+      const archiveDir = action === "archive" ? result.archiveDir : path.dirname(path.resolve(o["--manifest"]));
+      const relative = path.relative(archiveDir, path.resolve(o["--out"]));
+      if (!relative || (!relative.startsWith(`..${path.sep}`) && relative !== ".." && !path.isAbsolute(relative))) throw new Error("操作结果不能写入或覆盖固定报告归档");
+      protectOutput(o["--out"], [o["--input"], o["--summary"], o["--review-index"], o["--manifest"]]); writeJson(o["--out"], result);
+    }
+    else console.log(JSON.stringify(result));
   } else if (command === "onboard") {
     const { runOnboardCli } = await import("../lib/onboard.js");
     process.exitCode = await runOnboardCli(rest);
   } else if (command === "setup") {
     const { runSetupCli } = await import("../lib/setup.js");
     process.exitCode = await runSetupCli(rest);
+  } else if (command === "jenkins") {
+    const { runJenkinsCli } = await import("../lib/jenkins-runtime.js");
+    process.exitCode = await runJenkinsCli(rest);
   } else if (command === "java-tools") {
     const o=options(["--source","--archive","--python"]);
     const {javaDistribution,javaReferenceLock}=await import("../lib/java-distribution.js");
@@ -108,7 +133,7 @@ try {
     const review = await import("../lib/release-review.js");
     if (o["--out-dir"] && !o["--publication-dir"]) throw new Error("--out-dir 仅用于自动选择后的本次CI重查证据");
     const result = o["--publication-dir"] ? await review.selectReleaseReview({ configFile: o["--config"], project: o["--project"], sha: o["--sha"], publicationDir: o["--publication-dir"], outDir: o["--out-dir"] }) : review.verifyReleaseReview({ configFile: o["--config"], project: o["--project"], sha: o["--sha"], recordFile: o["--record"], evidenceRoot: o["--evidence-root"] });
-    process.stdout.write(JSON.stringify(Object.fromEntries(["status", "project", "sha", "reviewId", "reviewerId", "authorId", "recordHash", "reviewDigest", "bodyDigest", "evidenceDigest", "sourceDigest", "trustHash", "liveVerified", "liveCheckDirectory"].filter((key) => result[key] !== undefined).map((key) => [key, result[key]])), null, 2) + "\n");
+    process.stdout.write(JSON.stringify(Object.fromEntries(["status", "project", "sha", "reviewId", "reviewerId", "authorId", "recordHash", "reviewDigest", "bodyDigest", "evidenceDigest", "sourceDigest", "trustHash", "preBuildFindingsResolved", "liveVerified", "liveCheckDirectory"].filter((key) => result[key] !== undefined).map((key) => [key, result[key]])), null, 2) + "\n");
   } else if (command === "doctor") {
     const o = options(["--root", "--kind", "--out"]);
     if (o.positional.length) throw new Error("doctor 不接受位置参数");
@@ -326,5 +351,5 @@ try {
     if (rest.length) throw new Error("self-test 不接受额外参数");
     const { runAllFixtures } = await import("../scripts/run-fixtures.mjs");
     process.exitCode = await runAllFixtures();
-  } else throw new Error("用法: wl-skills-gate <setup|onboard|ci-prepare|verify-release-review|run|doctor|automation|control|collect-ci|review-facts|review-ci|review-collect|review-publish|lifecycle-build|lifecycle-review|governance|inspect|cost|fix|validate-report|commit-message|manifest|attest|attest-collected|release-set|deployment|review-draft|review-sign|verify-artifact|promote|promote-apply|self-test>，详见 docs/README.md");
+  } else throw new Error("用法: wl-skills-gate <setup|onboard|jenkins|ci-prepare|verify-release-review|run|doctor|automation|control|collect-ci|review-facts|review-ci|review-collect|review-publish|lifecycle-build|lifecycle-review|governance|inspect|cost|fix|validate-report|commit-message|manifest|attest|attest-collected|release-set|deployment|review-draft|review-sign|verify-artifact|promote|promote-apply|self-test>，详见 docs/README.md");
 } catch (e) { console.error(`[${command || "wl-skills-gate"}] ${e.message}`); process.exitCode = 2; }

package/docs/01-quick-start.md

@@ -15,15 +15,22 @@ node bin/wl-skills-gate.js self-test
 
 使用前须取得 AGILE TEAM 事先书面授权，并遵循该授权约定范围；公开 npm 包可下载不构成使用许可。详见 [LICENSE](../LICENSE)，申请通过 [仓库 Issues](https://github.com/ChenyCHENYU/wl-skills-gate/issues)。
 
+项目负责人优先使用完整交付包的`01_接入项目.sh`，自动识别前后端、安装配套、接入Hook并首扫；运维使用运维包的`01_接入Jenkins.sh`。均按包内主说明逐步执行。
+
+已安装固定Gate时运行：
+
+```bash
+wl-quality init
+```
+
+未安装Gate的维护者也可从批准源启动固定版本向导：
+
 ```bash
-# 取得书面授权后，从公共 npm registry 安装固定版本。
-pnpm add -D --save-exact @agile-team/wl-skills-gate@0.7.0
-mkdir -p quality
-# 从安装包 templates/quality 取模板，按真实检查器和工具版本修改。
-pnpm exec wl-skills-gate run --profile standard
+npm exec --yes --ignore-scripts --registry=https://registry.npmjs.org/ \
+  --package=@agile-team/wl-skills-gate@0.13.1 -- wl-quality init
 ```
 
-首次只读试运行先确认真实工具被调用、发现一条预设错误、报告定位正确、退出码非零；随后集成现有 Hook，禁止覆盖原有检查。
+向导展示差异与实际安装计划，确认后执行；检查异常不能当成零问题。接入后日常由Hook自动检查；正式Review、远端强制检查、群消息与报告权限仍按现场清单验收。
 
 ## 三档
 

package/docs/07-jenkins.md

@@ -1,8 +1,83 @@
-# 07 Jenkins 构建、签发与部署
+# 07 Jenkins：薄接入、严格构建与发布
 
-使用包内 [CI 模板](../templates/ci/)，由米传汇智和运维冻结实际作业、SCM/ref、镜像、脚本、凭据与修改权限。项目作者不能替换或跳过受控作业；真实环境另做验收。
+**新接入只保留一份受控登记和一个包调用入口。** 核心执行在Gate内，前后端用同一入口；不同项目、分支和模块通过独立scope／policy绑定。
 
-## 一次接好五类作业
+## 公共入口（新接入默认）
+
+Gate直接在实际节点安装服务器公共入口，随包升级，不需要新增仓库或单独发布共享库。交付包运行运维包的`01_接入Jenkins.sh`或完整包的`02_接入Jenkins.sh`；底层为`wl-quality jenkins install --config <批准安装参数>`。生成命令别名、`jenkins-cluster.json`、受控`jenkins/entry.groovy`和一行Pipeline：
+
+```groovy
+node('wl-quality-router') { load('/opt/wl-quality/gate-validation/jenkins/entry.groovy') }.call()
+```
+
+路径以安装回执为准。路由节点增加`wl-quality-router`标签，读取受控配置；入口按实际Job识别角色、核验入口／包字节，先释放路由节点再分配业务节点，不检出业务代码。业务Job必须唯一登记，不能切换为签发或配置任务。Jenkins原生`load`见[官方步骤文档](https://www.jenkins.io/doc/pipeline/steps/workflow-cps/#load-evaluate-a-groovy-source-file-into-the-pipeline-script)。
+
+运维只建一个`wl-quality-fleet` Pipeline任务，启用Sandbox并粘贴生成的一行。首次“准备公共任务”使用配置服务账号，预览／确认后创建其余四个任务，逐项回读；同名自定义配置拒绝覆盖，不启动业务或定时。中央与Review实际联验后，勾选各自`ENABLE_SCHEDULER`运行一次，启用每分钟调度。后续项目按批准登记批量接入，不逐Job复制脚本。节点准备脚本现已自动核对项目登记与中央配置；缺工程配置时保留准备成果、列出责任人与下一步，补齐后重跑同一入口，不再使用单独核对脚本。节点入口损坏仍须停止。交付包另在验收目录提供自包含环境／飞书测试任务，节点未安装Gate时也可先验流水线机器人。
+
+`wl-quality jenkins context --verify-entry`验证本轮真实Job与安装字节。CHECK及BUILD准备阶段生成`quality-reports/ci-integration/entry-context.json`，与原件一同归档；中央来源固定运行时与入口摘要，缺失或旧版本证据拒收，升级不能沿用旧绿报告。
+
+## 节点自检与失败通知
+
+正常接入先运行编号脚本，再由自动创建的`wl-quality-doctor`验环境与机器人。若要在安装Gate前先验证失败通知，使用交付包`验收/环境与飞书验证.Jenkinsfile`：首次默认环境检查；后续在参数化构建中勾选`TEST_NOTIFICATION`可只测消息。自检使用 Python3 标准库；即使 Node 或 Gate 缺失，也能记录失败并尝试签名通知。安装自动记录实际Node目录，服务器公共入口、命令别名及任务子进程统一使用该目录；其他节点路径不同时，在该节点设置受控`WL_NODE_BIN_DIR`。无需修改受控脚本，不能在自检与构建中各选一套运行时。
+
+生成的业务入口与辅助任务均先自检，再执行业务操作。异常处理使用流水线机器人凭据 `wl-feishu-ci-webhook`、`wl-feishu-ci-signing-secret`；凭据只在通知阶段绑定。缺凭据、缺 Python3、网络失败不会把原失败变成成功，也不假报送达。普通代码质量阻断由中央质量卡片通知，避免再发一张环境异常卡片；报告发布失败仍单独报执行异常。
+
+新接入的五类任务共用同一个本地入口：节点自检、接线核验、中央调度、独立Review签发、批量接入维护。旧内嵌模板由`lib/jenkins-bootstrap.js`保留兼容，不能直接复制含`__WL_*__`的源模板。签发节点保持隔离。
+
+底层CLI入口为 `node <gateHome>/bin/wl-skills-gate.js`；日常接入使用生成的一行Pipeline，正式准入由包内执行。
+
+中央调度模板显式绑定四项 Secret text：`wl-feishu-ci-webhook` → `WL_FEISHU_CI_WEBHOOK`、`wl-feishu-ci-signing-secret` → `WL_FEISHU_CI_SECRET`，项目机器人对应 `wl-feishu-project-webhook` / `wl-feishu-project-signing-secret` → `WL_FEISHU_PROJECT_WEBHOOK` / `WL_FEISHU_PROJECT_SECRET`。绑定名与治理配置保持一致；节点自检可用 `TEST_NOTIFICATION` 单独测试流水线机器人，不执行质量或构建动作。中央调度先执行同凭据上下文的只读中央预检，通过后才采集发送。中央任务另绑定`wl-jenkins-ci-readonly`、`wl-ci-review-readonly-token`、`wl-jenkins-build-dispatch`与`wl-quality-sso-client-secret`，分别注入CI读取、GitLab身份读取、批准续建及SSO预检变量。事件签名与身份服务按批准配置挂载并独立运行；代码执行和正式Review签名私钥不混入中央采集任务。
+
+## 批量接入：一次安装，一个维护入口
+
+**运维不逐个Job粘贴入口。** 每个实际Agent或固定镜像安装一次Gate及所需分析器；工程侧按项目/分支/scope交付批准登记、中央来源和构建资产。几十个Job由一个受控维护任务统一配置。
+
+| 步骤 | 运维操作 | 成功反馈 |
+|---|---|---|
+| 1 准备一次 | 安装固定包、准备持久卷及凭据；工程侧交付批准配置 | 节点自检`ready`；机器人连通测试`sent` |
+| 2 建维护入口 | 使用安装脚本生成的一行入口建立`wl-quality-fleet`；执行“准备公共任务”后再“盘点” | 真实Job清单及无法识别项；仅GET，不改任务 |
+| 3 批量接入 | `jenkins-fleet.json`选择已批准项目及分支；执行“接入”，核对预览后由指定人员确认 | 创建/更新入口、精确分支Push Hook、回读配置、同步中央摘要；逐Job返回结果 |
+| 4 联验与扩展 | 先对`test`完成真实联验；扩大批准清单后再次接入 | `configuration-verified`后另验真实合入、阻断、修复、审核、构建、通知与报告 |
+
+[批量清单模板](../templates/platform/jenkins-fleet.json)不存密钥。`registryFiles`可引用多个节点组登记，每份登记一个Agent标签；`selection`必须明确项目及分支，不按视图名或通配符授权。新增范围由工程侧完成检查计划、正式Review信任、中央来源及构建脚本的批准，运维重复同一维护入口。
+
+维护任务与其余公共任务共用安装脚本生成的一行Pipeline。配置凭据固定为：`wl-jenkins-config-manager`（Username with password，密码填API Token）、`wl-gitlab-hooks-token`（Secret text）、`wl-gitlab-jenkins-webhook-secret`（Secret text，GitLab/Jenkins共用Webhook Secret）。只授予受控维护任务，不能给项目源码执行阶段。原有GitLab插件仍需可用；不新增Job DSL插件。API Token沿用Jenkins现有认证与CSRF机制。
+
+自动处理重复执行、写后回读、部分失败续跑、配置漂移检查及原始配置留存；支持“核验”和“回退”。私有计划/原始配置放`dataDir/plans/<批次>/`，不归档到工作区；Jenkins只归档公开结果与批准人。回退已有Gate任务恢复原配置，新建任务禁用并保留历史；不删除Job或已有Hook。新增Hook可能保留，指向禁用Job不执行构建。
+
+**已有自定义部署、回滚或SCM流水线不自动覆盖。** 盘点会保留并列出；工程侧先把批准构建动作纳入Gate接入，部署/回滚另做适配。`configuration-verified`表示配置回读通过，不能代替业务运行验收。
+
+技术排查可使用`jenkins fleet inventory|plan|show|apply|verify|rollback --config <清单>`；有写入的动作必须有当前预览摘要和确认，日常由维护任务传递，不要求运维手抄。中央调度空闲时批量执行；任务运行/排队或有未完成采集时停止相关写入，不强制中断。迁移中央摘要时保留原问题台账、发现水位与历史；中断后续跑原批次，不删除维护标记或重建台账。
+
+单任务排查仍可使用启动器菜单7生成登记、菜单8只读核验。可先登记CHECK完成自动检查、九维草稿和报告发布；接入BUILD必须补齐同范围严格Review信任、批准构建脚本与真实制品范围。批量路径自动同步`stable-v1`作业摘要；该协议只忽略已知Declarative跟踪元数据，脚本、权限、参数及触发设置仍固定核验。
+
+## 粒度和防误配
+
+- 一条登记精确对应项目、目标分支、scope、一个CHECK及可选BUILD；CHECK与BUILD不得使用同一个Job。可为模块选择`quality/scopes/pl/policy.json`等已批准策略，并用`evidencePlanFile`绑定该模块的必测和证据计划。不同scope不能复用正式Review。
+- 自动生成工作副本、锁、机器策略、规则、基线、豁免、九维策略和证据计划的八项摘要；不在CI重新计算后自行批准变更。
+- 配置错拼、占位、重复Job、错仓库/分支/SHA、包/策略/信任/脚本漂移，均明确拒绝。
+- 准入结果由受控Jenkins阶段捕获摘要，绑定项目、scope、SHA、源码、Job和运行编号；缺准备记录、改回执、过期或重复执行不能继续。
+- 源码检查与业务构建子进程不继承Review/机器人凭据；安装阶段仅保留必要的包源认证环境。节点、固定包、登记及报告读取凭据仍须由运维隔离并限制权限。
+
+**包不能强迫一条未调用它的任务执行检查。** 服务端接线核验、中央固定作业配置核验、必需状态与共享分支保护共同强制，不能只看某个Jenkins Job显示绿色。目标分支Push检查发生在合并之后；合并前拦截仍需候选合并结果检查。
+
+## 当前交付边界
+
+本轮以0.13.1固定正式版本交付。包发布和隔离测试不代表两业务仓库或远端已接通。正式Review后的自动续建、验证构建结果/制品采集、紧凑检查卡片可靠投递已通过隔离贯通测试；真实项目配置、中央服务、TEST任务和飞书身份仍需现场交接／验收。
+
+团队操作以交付包根目录的完整或运维接入操作说明为准，本文供维护者排查底层契约。
+
+## 中央自动续建与两阶段通知
+
+工程侧交付固定中央配置，运维只启动一个调度器。参考[TEST自动执行配置](../templates/platform/automation-config.jenkins-test.json)、[CHECK来源](../templates/platform/ci-source.jenkins-test.json)与[BUILD来源](../templates/platform/ci-source.jenkins-build.json)；批量接入自动同步作业摘要，单任务排查可用菜单8只读核验。模板占位不能验收。
+
+- CHECK来源登记`buildDispatch`（受控登记路径和bindingId）及正式Review订阅。签发后自动核对当前分支HEAD、同范围正式Review和实际BUILD入口；传入获批SHA/追踪ID。队列/构建记录对账恢复，未知结果保留告警，不盲重发。
+- 同scope的BUILD来源登记固定`buildResultPath`与制品ZIP，无`qualitySummary`及部署环境；必须关联该CHECK的续建任务，不能跳过九维Review。成功后仍不表示部署或问题关闭。单ZIP上限256MiB/5000文件，超过时明确失败，拆分批准构建范围。
+- `scopes.<scope>.notification`固定`channel`、`surface`、`branch`与严格清零；批准的验证分支再设`validationBranch: true`。可绑定范围技术经理，项目/CI机器人按范围分流，首次发现一轮一张卡，最多3项预览。原生彩色数量、@与恢复复用中央可靠待发箱；旧台账不能直接改身份配置。
+
+## 附录：现有正式发布与部署作业
+
+以下模板用于已采用相应发布契约的作业；新项目的检查／构建按前文公共入口接入。[内嵌fleet模板](../templates/ci/Jenkinsfile.fleet)仅供历史接线兼容，由`renderJenkinsMaintenance`生成，不用于替代新公共入口。
 
 | 顺序 | 模板 | 自动执行与成功条件 |
 |---:|---|---|
@@ -20,6 +95,10 @@
 
 中央 Review 原件可只读挂载。当前 CI 复验记录写入本机 `quality-reports/release-review-live/<uuid>/`，结果和失败原因写入 `release-review-verification.json/.log`，随 `post always` 归档。
 
+要求“构建前问题全部处理完”的项目在固定信任中启用 `requireResolvedFindings: true`。真实签名和原始证据核验后，必须是源码绑定的完整报告、全部检查有效、所有发现及新旧/豁免计数为零；警告和提示也不能带入构建。该判断不会关闭治理台账，部署后才能取得的验证仍在相应阶段验收。
+
+新薄入口由包内`jenkins-runtime.js`统一断言当前项目/SHA的`preBuildFindingsResolved: true`和`liveVerified: true`；仅`status: verified`不足以放行。构建先准备固定依赖，再实时核验正式Review；只执行摘要匹配的工作区外POSIX构建脚本，制品归档不得为空。旧`Jenkinsfile.quality-check/build`和`check-project.mjs`仅兼容历史接线，不作为新项目拼装入口。
+
 `ci-prepare` 使用中央预装固定 Gate，核对已提交 `quality/workspace.json` 与依赖锁的批准字节摘要，按锁安装且关闭任意生命周期；必要准备仅用固定适配。未知脚本、版本不符、锁或源码漂移均停止。它不在 CI 激活 Hook，也不代替后续质量检查。
 
 实际构建脚本来自批准作业配置。前端 manifest 纳入真实 dist，后端纳入真实 JAR；分发配置和数据脚本用 `WL_CONFIG_PATHS` 纳入。部署只消费这些不可变制品，不重新构建。
@@ -52,6 +131,7 @@
 | 凭据 ID / 环境变量 | 只授给谁 |
 |---|---|
 | `wl-ci-review-readonly-token` → `WL_GITLAB_READ_TOKEN` | 构建前 Review 重查与独立 Review 签发；构建模板仅在校验阶段绑定 |
+| `wl-jenkins-ci-readonly` → `WL_JENKINS_READ_USER` / `WL_JENKINS_READ_TOKEN` | Jenkins来源的构建前重查和独立签发；只授固定作业的配置核验/构建/工件读取，不进入项目检查阶段。仅用GitLab来源时按实际移除该绑定 |
 | 来源配置的 `tokenEnv` / `userEnv` | 对应查询作业；Jenkins 来源另按配置注入 `WL_JENKINS_READ_USER`、`WL_JENKINS_READ_TOKEN`，不授源码执行阶段 |
 | `wl-component-proof-signing-key` → `WL_COMPONENT_KEY` | 独立组件签发 |
 | `wl-review-signing-key` → `WL_REVIEW_PRIVATE_KEY_FILE` | 独立正式 Review 签发 |
@@ -62,6 +142,18 @@
 
 中央飞书、身份与事件签名凭据由[中央接线配置](../templates/platform/README.md)引用并隔离，不放入检查/构建作业。运行前创建受控持久目录、输入队列和归档目录；通知失败保留原始检查/部署结果，并由待发箱与独立监控反馈。
 
+旧TEST模板曾使用`WL_SOURCE_REPOSITORY`等逐项变量；新薄入口从受控登记统一读取，仅受控续建传入`WL_REVIEW_SHA`。纯 CHECK 中央来源不设 `manifestPath`，可省略 `environment`，不产生业务构建成功事实；`test` 不是正式部署环境枚举。
+
+## 报告发布与人员识别
+
+新薄入口的CHECK自动调用固定[报告发布脚本](../templates/ci/jenkins-quality-report.groovy)，检查结束即发布完整九维HTML，不等构建/部署。BUILD输出本轮准入、`build-result.json`和实际`business-artifacts.zip`，非空归档后由中央独立采集，单独生成构建事实；不复用CHECK报告冒充BUILD扫描。包从受控登记读取工作区外持久卷和报告读取凭据，无需逐Job拼发布变量。旧发布模板只有实际生成本轮原始报告时，才使用它的报告发布阶段。
+
+脚本先保存不可变 HTML/JSON 到持久卷，再用 HTML Publisher 保留本次构建报告，最后认证回查页面与文件摘要。中央采集配置的 `reportPublication.manifestPath` 指向 `quality-reports/report-publication.json`，重新核验同作业、同 SHA、同阶段和在线 HTML，才能生成群内详情链接。发布失败仍归档原始检查证据，不能发送失效按钮或当作质量通过。
+
+`keepAll` 不保护被删除的整次构建。米传/运维需为报告所依附的构建记录设置保留策略，并独立备份持久卷；清理大体积业务制品时不能一并删除仍在有效期内的报告链接。服务只读账号验证通过后，仍用普通群成员账号验收访问权限。Jenkins 对外 URL、`BUILD_URL`、`JENKINS_URL` 应统一为批准的 HTTPS 入口；页面样式使用受控资源域，不关闭全局 CSP。
+
+查询凭据代表服务接入权限；人工触发人读取本次构建的 `UserIdCause`，不读取凭据用户名作为触发人。配置批准的 GitLab `actorSource` 后，自动触发与手动重建均关联唯一真实合并记录，点击构建的人单独记入 `triggerSource`；上游关联缺失时拒绝回退到点击人。未配置该关联的旧入口仍含触发人语义，不能用于正式 Review 的源码作者归属。Git 提交作者、合并申请作者、合并执行人和技术经理仍分别核对，MR 作者不等于全部代码贡献者。正式运行使用范围受限的服务凭据，无需每位开发者交 Token。
+
 ## 验收
 
 至少演练：正常完整组合、缺/旧 Review、当前 CI 失败或重试、错 SHA、替换制品/配置、错环境、无授权/重放、冒烟失败与显式恢复。成功与失败都保留原始报告和作业 ID；真实 Jenkins 权限、实际部署/冒烟与群投递另留现场证据。

package/docs/16-project-ci-integration.md

@@ -1,16 +1,16 @@
 # 16 项目、流水线与治理接入入口
 
-本页为包内导航。团队接入步骤统一维护在 **V3 接入操作手册**，本页不复制另一套操作顺序。包使用条件沿用 [LICENSE](../LICENSE)。
+本页为包内导航。项目与运维按交付包根目录的主说明操作，不从其他文档拼装步骤。包使用条件沿用 [LICENSE](../LICENSE)。
 
 ## 按读者使用文档
 
 | 文档 | 职责 |
 |---|---|
-| 《工程化与代码质量管控体系（V3）》 | 目标、九个质量维度与团队统一要求 |
-| 《工程化与代码质量管控体系-落地执行（V3）》 | 主责、阻断标准、SLA、例外、监督与关闭 |
-| 《工程化与代码质量管控体系-接入操作手册（V3）》 | 七步操作与全部必要附录；含前后端、运维/米传汇智、杨晨誉飞书、九维Review与修前后授权记录；单文档导出 |
+| 完整包 `00_完整接入操作说明.md` | 项目接入→Jenkins准备→工程登记→批量接入与联验；细节在同一文档附录 |
+| 运维包 `00_运维接入操作说明.md` | 一次节点准备、一个维护任务、批量接线、凭据与现场联验 |
+| 包内技术手册 | 工程维护者按需排查配置、证据、权限与程序契约 |
 
-操作人员从独立操作手册开始，不必先通读客户宣贯或内部制度。团队文档由受控归档随交付包提供。npm 包不包含工作区 `规范/`；包外使用者从团队受控文档归档取得这三份文件，记录相同修订与批准版本。不要把工作区路径当作已上线的认证问题或证据服务。
+两份交付包各只有一份主说明，脚本、固定安装包与验收清单同包提供。客户宣贯与内部制度用于解释管理要求，不作为另一套安装步骤。npm包只提供技术手册与模板，不包含工作区的团队文档；认证入口和报告链接须使用实际部署并验收的HTTPS地址。
 
 ## 执行入口与闭环责任
 
@@ -23,7 +23,7 @@
 | 统一质量服务 | 共享分支保护、真实候选、九维独立授权/签发；组合与部署重验当前 Review、实际制品和对应动作授权 |
 | 治理 | 可信事件、幂等主台账、主备/复核、认证跳转、可靠待发箱、SLA/对账、独立关闭 |
 
-“共享实现已验证”“业务项目已接入”“已接项目准入已验收”“业务问题已关闭”分别登记。模拟和隔离验证不能代替真实接线证据。本轮只完善共享资产，业务项目/test-qa 不改动，不发送真实消息。
+“共享实现已验证”“业务项目已接入”“已接项目准入已验收”“业务问题已关闭”分别登记。模拟和隔离验证不能代替真实接线证据。
 
 ## 后端检查的准确定位
 
@@ -43,7 +43,7 @@ BD 的 verify:quality-codecc 等属于源码包维护者夹具验证。业务项
 | doctor | 只读盘点前后端的依赖/资产/策略/POM 准备度，不执行项目测试或安装；CI/Jenkins 作业另由统一质量服务核验 |
 | JUnit 多报告与共享 producer | 显式 files/reportDirs/requiredSuites/requiredTests，真实同轮生产，全量 XML 与 testcase 校验 |
 | [Java 单元生产器](../templates/scripts-quality/java-unit.mjs) | 依批准 plan 准备依赖，再在真实测试模块运行 unit，不把跳测准备当测试 |
-| [CI 模板](../templates/ci/) | 前后端 GitLab、Jenkins 接入资产；管理员合并真实 stages/rules/权限 |
+| [CI 接入](07-jenkins.md) | Jenkins安装服务器公共入口，由fleet批量配置；[GitLab模板](../templates/ci/)按其实际候选检查与权限要求接线 |
 | [治理模板](../templates/platform/) | 独立统一质量服务签名 receipt、幂等台账、动作校验、待发箱、预览/显式发送、自然分钟 SLA/预期运行对账 |
 
 包内collect-ci提供固定GitLab/Jenkins只读查询；实际来源配置、SSO、认证网页、应用回调、工作日历和企业群权限由团队现有环境配置。receipt 签名要求统一质量服务先核验真实来源/身份。首期 SLA 为中央首次摄入起的自然分钟，源发生/接收延迟单独观测，不冒充完整工作日历。共享首期采用中央串行台账及写锁；多实例/数据库/外部系统需保留相同幂等与审计语义的适配。
@@ -61,4 +61,4 @@ BD 的 verify:quality-codecc 等属于源码包维护者夹具验证。业务项
 - [14 低 token 执行](14-low-token-execution.md)：唯一生产者、摘要阅读与成本。
 - [质量服务配置与样例](../templates/platform/README.md)：可信 receipt、事件/动作/对账及消息预览。
 
-实际文件名以包目录为准。团队操作手册只呈现一次接入、自动检查、确认后脚本修复、复扫反馈、构建部署与关闭验收；资产、CLI/POM/CI参数和来源移入明细附录。Gate 的 templates/onboarding 已纳入固定 npm 包，统一操作入口为 setup，底层首次接入契约为 onboard --complete；工作区 quality-onboarding-examples 保留历史适配与兼容入口。已复制脚本仍须经升级计划审核同步。先验前后端各一个模块与一条真实告警，再扩面；正式准入从开始就拒绝确定缺陷、必测失败和证据失效。
+实际文件名以交付清单为准。编号脚本调用固定Gate，不另行复制工作区样例。项目统一入口为`wl-quality init`，底层首次接入契约为`onboard --complete`；已生成脚本经升级计划审核同步。先验前后端各一个模块与一条真实告警，再扩面；正式准入从开始就拒绝确定缺陷、必测失败和证据失效。

package/docs/17-onboarding.md

@@ -1,6 +1,9 @@
 # 17 统一接入入口
 
-`wl-gate` 与 `wl-skills-gate` 是同一个 Gate 包的两个命令名。接入脚本、Hook 调度器、IDE 操作和配置模板随 Gate 包一起交付；不再要求从文档目录挑脚本组装。本文介绍共享程序契约，团队按独立《接入操作手册》执行项目与远端验收。
+首次接入和新工作副本统一使用`wl-quality init`。已接项目自动进入工作副本初始化；首次接入自动识别已支持PC Vue／Java Maven并展示差异。日常检查由Hook执行。交付包提供`01_接入项目.sh`／`.command`，自动安装本轮Gate和本类型配套，使用者不用选前后端安装命令。
+
+
+`wl-gate` 与 `wl-skills-gate` 是同一个 Gate 包的两个命令名。接入脚本、Hook 调度器、IDE 操作和配置模板随 Gate 包一起交付；不再要求从文档目录挑脚本组装。团队按交付包根目录的完整或运维接入操作说明执行；本文供维护者排查程序契约。
 
 ## quality-tools 是什么
 
@@ -13,7 +16,7 @@
 
 ## 技术经理一次接入，开发者由 Hook 自动检查
 
-负责人从批准的完整包打开 `templates/launchers/setup.command` / `setup.cmd` / `setup.sh`，选择任务即可。首次项目接入使用 `setup project` 交互向导：选择真实 Git 根和批准 HTTPS 安装源，查看文件、依赖、Hook 与固定安装 argv，确认当前阶段。脚本管理本阶段计划摘要，出现安装后的新差异再展示确认。
+负责人填写批准完整包的`现场参数.json`，运行根目录`01_接入项目.sh`（macOS可双击`.command`）。脚本调用`wl-quality init`，选择真实 Git 根和批准 HTTPS 安装源，查看文件、依赖、Hook 与固定安装 argv，确认当前阶段。脚本管理本阶段计划摘要，出现安装后的新差异再展示确认。已安装Gate的维护者也可使用包内`templates/launchers/setup.*`进入底层菜单。
 
 | 入口 | 自动执行 | 成功反馈 |
 |---|---|---|
@@ -21,6 +24,8 @@
 | `setup workspace` | 按已提交 `quality/workspace.json` 与依赖锁安装，恢复本机 Hook，实际验收 | `quality-reports/onboarding/workspace-execution.json`；不覆盖项目策略 |
 | `setup branches` | 首次中央配置中自动生成六个目标分支来源、独立scope、Review和UAT信任；查看完整差异并确认，保留验证/候选来源 | 未修改远端权限；已有运行台账时拒绝覆盖，逐分支现场验收 |
 | `setup central` | 中央配置、来源、身份、凭据存在性、旧状态及部署回流预检 | 逐项状态、责任人和下一步；预检不联网、不启动、不发送 |
+| `setup jenkins` | 从已提交项目自动提取八项批准摘要，绑定仓库/分支/scope、固定包和Job，生成受控登记及统一调用入口 | 菜单7；不写业务项目，不改远端权限，不自动批准Review |
+| `setup jenkins --verify` | 只读核对远端真实Pipeline script、分支和触发器，自动计算Job配置摘要 | 菜单8；接线核验不等于业务链路运行验收 |
 | `setup release-input` | 核验固定来源原件、签名、摘要、兼容证据，确认后生成组合输入 | `configHash` / `inputHash` 与实际输入文件；不代替授权或签发 |
 
 非交互入口默认只读。`setup project --root PATH --registry URL --preview --json` 可用于预检；项目首次写入由交互逐阶段批准，自动任务可继续使用下文底层 `onboard` 契约。
@@ -43,9 +48,11 @@ Java完整扫描的固定离线分发、自动缓存和环境变量由运维一
 
 GitLab/Jenkins模板用中央预装固定Gate调用`ci-prepare`，中央登记`quality/workspace.json`和依赖锁的真实字节摘要；按锁安装时关闭任意生命周期，必要准备仅用内置固定适配，不激活CI Hook。准备通过不等于质量检查通过。
 
+Jenkins新接入由Gate安装服务器公共入口，无需新增仓库；运维只建一个fleet任务，其余公共任务与业务接线由包批量配置。使用受控`jenkins-bindings.json`与包内`jenkins-gate.groovy`，两个Job共用生成的薄入口，不复制检查/准入逻辑或逐项拼环境变量。仓库、目标分支、scope和可选模块policy分别绑定；八项摘要由菜单7从已提交文件生成。CHECK可先独立接通，未登记BUILD便不能构建；补全正式Review后才开放构建门禁。接线核验会发现漏Gate或错误触发，最终强制仍依赖受保护分支、固定中央来源和任务权限。
+
 pnpm预检和安装同时禁用pnpmfile执行；发现项目或全局pnpmfile声明会停止，由工程工具维护者提供固定摘要、允许目录和幂等验证适配。`--ignore-scripts`本身不覆盖pnpmfile，[pnpm说明](https://pnpm.io/id/11.x/pnpmfile)可供维护者核对。
 
-Jenkins在准备和构建前调用`verify-release-review --publication-dir`，以checkout SHA自动选最新正式Review并重查当前CI，记录放本机quality-reports，不写只读中央原件。发布输入配置固定`reviewConfigFile`和组件`reviewPublicationDir`；组合及部署强制重验同候选Review签名、独立授权和原件。旧组合缺该证据需重新生成，不接受布尔批准。
+Jenkins新入口先`jenkins prepare`准备固定依赖，再由`jenkins admit`以checkout SHA选择当前正式Review并重查CI；`jenkins build`复核本轮准入及源码后执行批准构建。记录放本机quality-reports，不写只读中央原件。发布输入配置固定`reviewConfigFile`和组件`reviewPublicationDir`；组合及部署强制重验同候选Review签名、独立授权和原件。旧组合缺该证据需重新生成，不接受布尔批准。
 
 中央输入队列（正式Review交付、部署回流）首次由运维在受控持久卷创建；运行中缺失视为异常并提醒，不能自动造空目录。普通warning当周期汇总，首次/持续采集故障与恢复通过同一可靠待发箱反馈；配置或台账本身不可用由独立监控兜底。
 
@@ -101,8 +108,9 @@ GitLab/Jenkins 权限、可信中央模板、候选/独立 Review、构建/部
 ## 维护单源
 
 - 交互入口：`lib/setup.js` / `lib/setup-modes.js`；底层首次接入：`lib/onboard.js` / `lib/onboard-config.js` / `lib/onboard-complete.js`；新克隆：`lib/workspace-init.js`；中央预检：`lib/setup-central.js`；发布输入：`lib/release-input.js`。
-- 包内交付源：`templates/onboarding/{frontend,backend,automation}`。`templates/scripts-quality/run.mjs` 与 schema 同包核验。
-- 文档目录旧 `automation/configure.mjs` 仅兼容转发；不得再次复制实现。文档配套文件是审阅用样例副本，维护时与包内交付源核对摘要。
+- 包内执行源：`lib/project-actions.js`负责Hook、报告及确认后的修复复扫；`lib/jenkins-integration.js`、`lib/jenkins-runtime.js`负责接线与执行。项目的`project-actions.mjs`只有固定版本加载逻辑。
+- 包内交付源：`templates/onboarding/{frontend,backend,automation}`。`templates/scripts-quality/run.mjs` 与 schema 同包核验；规范目录中的历史配套不作为新接入的复制源。
+- 接入只从当前固定包生成脚本与配置，不从其他文档目录复制样例实现。
 - 本模块测试覆盖真实 Git Hook 拒绝、前后端位置、旧 Hook 复用、幂等、漂移拒绝、完整包独立交付；不把隔离测试计为业务项目或远端验收。
 
 只读配置采集禁止pnpm隐式版本下载，兼容pnpm10/11；安装强制项目固定版本，版本不符在预览中阻断，由运维提供批准运行环境。registry scope与锁文件实际下载源均核验；项目内vendor tarball按字节摘要绑定，不把锁文件deprecation里的文档URL当下载源。
@@ -112,6 +120,28 @@ GitLab/Jenkins 权限、可信中央模板、候选/独立 Review、构建/部
 
 首次中央接线在助手中选择“6 生成同项目六分支中央接线”，使用 `templates/platform/branch-setup.json` 项目副本；默认保留验证/候选来源，生成六个固定目标分支的来源、独立scope、Review/签发和发布信任。`additionalCollectorConfigFiles` 是同项目批准的额外采集器；治理scope、必需作业和人员映射分别校验。候选上下文不能移植到最终分支；普通MR源分支不能冒充合并结果，动态MR来源仍需另行可信接线。
 
-Jenkins每条分支提供批准ref/jobPath/jobConfigHash，有上游作者关联还须给actorSourceRef。助手不创建作业、不改权限、不发送消息；已有台账或锁明确拒绝首次配置，不能通过删账重跑。运行中配置变更按受审计迁移处理。
+Jenkins每条分支提供批准ref/jobPath/jobConfigHash，有上游作者关联还须给actorSourceRef。本节`setup branches`只生成首次分支配置，不创建作业、不改权限、不发送消息；作业批量配置由fleet完成，通知由中央任务发送。已有台账或锁明确拒绝首次配置，不能通过删账重跑。运行中配置变更按受审计迁移处理。
+
+新模板把 `requireTechnicalManagerReview` 与技术经理人员标识同步（可用已登记账号，不强制工号）到治理、签发和发布信任；非作者经理确认，或经理为执行人时由已登记人员独立复核。确认人与执行人分别记录，群@不替代授权。UAT独立smoke成功后自动生成版本化HTML/JSON交付报告，记录固定Review/组合/真实验证及原件摘要；失败可单独续跑，篡改不可覆盖，不自动对客户发送。
+
+### 飞书里的人员与详情按钮
+
+普通提交的阻断通知 @提交人和技术经理，同一飞书人员只 @一次。技术经理本人提交时，仍保留本人署名，并同步 @李月；项目配置 `managerSubmissionNotify` 指向李月在 `people` 中的实名记录。经理本人提交即使没有阻断问题也同步她。这里配置的是通知对象，正式审核是否通过仍由真实审核记录决定；姓名和群消息不能代替审核或真实飞书 ID。
+
+群内按钮应直接打开**本次报告**，使用固定作业/构建编号，不能链接到会变化的 latest 报告。底部集中 @责任人，说明修复、自动复扫、回归和反馈要求；提交人/技术经理同排展示姓名，同一飞书人员只 @一次。
+
+新公共入口的CHECK在检查后的`finally`调用包内[报告发布脚本](../templates/ci/jenkins-quality-report.groovy)，不等待BUILD或部署；BUILD单独归档准入、构建结果与制品，不重复生成CHECK报告。旧发布模板的`post always`按各自契约保留。运维一次接好以下三项，检查任务自动归档、发布、验链接后再推送：
+
+| 接线项 | 配好后的结果 |
+|---|---|
+| 安装当前固定Gate，在项目登记配置`reportArchiveRoot`与`reportReaderCredentialId` | 包自动选择固定发布脚本并绑定变量，业务候选不能替换；不用逐Job拼装发布步骤 |
+| 预建工作区外的报告持久卷，启用 HTML Publisher | 包将登记目录绑定为`WL_QUALITY_REPORT_ARCHIVE_ROOT`；按项目、阶段、事件/SHA及内容摘要留存 HTML/JSON，复扫新增归档，历史报告不被覆盖 |
+| 只读凭据 `wl-quality-report-reader` 与报告任务读取权限 | 发布后回查固定 HTTPS URL、HTML 类型及文件摘要；登录页、403、旧报告或篡改均不发送详情按钮 |
+
+鉴权账号只用于查询，不作为所有构建的触发人。人工构建的实际触发人来自 Jenkins `UserIdCause`；提交作者、GitLab 合并申请作者和合并执行人分别关联本次 SHA 与真实记录。Git 作者姓名/邮箱只作为元数据，不能充当已认证责任身份；没有唯一身份时登记待核实，不能默认填鉴权账号。中央人员表再关联技术经理、飞书 ID；无需收集每位开发者的 Token。Jenkins配置批准的`actorSource`后，自动触发和手动重建都核验真实GitLab合并关联，点击构建的人单独保留在`triggerSource`；关联缺失时拒绝退回点击人。未配置上游关联的旧入口仍含触发人语义，不能作为源码作者的正式Review归属依据。
+
+运维还须保留报告所依附的 Jenkins 构建记录；`keepAll` 不能保住被整次删除的构建，持久卷备份也不会自动修复已删除构建的旧 URL。报告任务记录与大体积业务制品分别制定保留策略。服务账号能打开只证明服务端可读，仍须用普通群成员账号验收报告读取权限、失败报告、定位与历史链接。Jenkins 返回的 URL / `BUILD_URL` / `JENKINS_URL` 应与批准 HTTPS 入口一致；不把内网 IP 链接直接推到群里。
+
+仅归档产物不代表已经能在线浏览 HTML；GitLab 的 HTML 预览需启用 Pages 和访问控制。不要关闭全局 CSP 来解决样式或筛选问题，按 Jenkins 的受控资源域配置验收。发布失败保留原始检查结果和归档，登记执行异常，不能改成质量通过。
 
-新模板把 `requireTechnicalManagerReview` 与技术经理工号同步到治理、签发和发布信任；非作者经理确认，或经理为执行人时由已登记人员独立复核。确认人与执行人分别记录，群@不替代授权。UAT独立smoke成功后自动生成版本化HTML/JSON交付报告，记录固定Review/组合/真实验证及原件摘要；失败可单独续跑，篡改不可覆盖，不自动对客户发送。
+本机预览仅用于本机演示；正式群按钮须通过Jenkins固定报告链接和普通群成员权限验收。

package/docs/README.md

@@ -1,6 +1,6 @@
 # wl-skills-gate 技术手册索引
 
-当前源码版本 0.12.0；对照团队落地执行 V3.4。技术宣贯基线仍为 V3.1；团队具体操作单源见 [16 项目与运维入口](16-project-ci-integration.md)，本索引提供工具契约与参数参考。
+当前正式版本0.13.1。团队操作以交付包根目录主说明为准，见[16 项目与运维入口](16-project-ci-integration.md)；本索引提供工具契约与参数参考。
 
 授权声明见 [LICENSE](../LICENSE)；公开获取不授予使用、复制、修改或再分发授权，申请入口为 [仓库 Issues](https://github.com/ChenyCHENYU/wl-skills-gate/issues)。
 
@@ -20,17 +20,17 @@
 | [10 强制与权限](10-enforcement.md) | 1.2/12.6/B.4 | 防绕过、可信来源、密钥隔离与审计 |
 | [11 首轮评审修复](11-hardening-review.md) | 0.5.0 历史记录 | 修复项、验证结果、兼容变化和未验证项 |
 | [12 第二轮深入复核](12-closed-loop-review.md) | 0.5.1 与附录 C | 精准修复、覆盖与管理边界、隔离验证、下一步验收 |
-| [13 质量成本与隔离](13-quality-cost-and-isolation.md) | 当前 0.7.0 / BD 0.41.0 | 规则分级、共享报告转换、三档执行、Java profile 拆分、预警与执行边界 |
+| [13 质量成本与隔离](13-quality-cost-and-isolation.md) | 历史修订：0.7.0 / BD 0.41.0 | 规则分级、共享报告转换、三档执行、Java profile 拆分、预警与执行边界 |
 | [14 低 token 执行](14-low-token-execution.md) | 执行附录 E | 确定性扫描、摘要与按需分页、本轮 Java 共享生产、原生只读游标、离线成本统计和 AI 使用边界 |
 | [15 Java 原生报告分级与复核](15-java-report-triage.md) | Java scanner / 当前源码修订 | P3C与原引擎身份、成员指纹、Gate单源风险表、多模块sourceRoots、上下文复核和基线迁移 |
-| [16 项目、流水线与治理入口](16-project-ci-integration.md) | 执行附录 G / V3.4 | 三层文档导航、正式操作单源、精选检查定位、前后端/CI/平台/台账/消息资产与验收边界 |
+| [16 项目、流水线与治理入口](16-project-ci-integration.md) | 交付导航 | 完整／运维主说明、精选检查定位、前后端/CI/中央任务/台账/消息资产与验收边界 |
 | [17 统一接入](17-onboarding.md) | 项目接入 | Gate 包内入口、前后端识别、计划确认与固定资产 |
 | [18 可信 CI 采集](18-ci-source.md) | 运维事实 | 固定 API/Runner/作业、SHA/ref、必需检查与原始工件 |
 | [19 九维 Review](19-nine-dimension-review.md) | Review与授权 | 自动草稿、逐维证据、固定摘要、独立身份授权和签发 |
 
 ## 首期闭环与配套位置
 
-共享包承载检查事实和证据。中央模板/共享库承载流水线接线，平台受控作业承载权限。governance 提供签名 receipt、幂等中央串行台账/待发箱、主备认领/独立关闭、自然分钟 SLA 与预期运行对账；outbox/dispatch 默认不联网，dispatch 显式 --send 可推送飞书/企业微信群。配置/精确命令见 [平台模板](../templates/platform/README.md)。
+共享包承载检查事实和证据。Jenkins接线使用Gate安装的服务器公共入口与fleet维护任务，无需单独共享库仓库。受控作业隔离权限；governance提供签名receipt、幂等中央台账/待发箱、主备认领/独立关闭、自然分钟SLA与预期运行对账。底层outbox/dispatch默认不联网，dispatch显式`--send`才发送；原生中央任务的发送开关由其批准参数控制。配置见[中央执行模板](../templates/platform/README.md)。
 
 GitLab/Jenkins 只读 API 查询已由 collect-ci 提供；实际来源配置、身份认证/稳定查看入口、长期存储与调度、群权限按正式操作手册实接；高级日历/应用回调按需适配。D5 对账覆盖没有 job/取消/无工件等缺执行；D6 使用认证网页或经授权应用回写主台账，D7 按需求服务化。群接口接受不等于认领，扫描消失只进入待复验。