feat(cli): add global-adapters apply for source-local host refresh

Add R1a devcodex global-adapters apply so maintainers can refresh
user-level five-host adapters from the package root without pack or
publish. Route nextStep/PC5/V8/doctor/help/docs by source vs published
install path, ship new modules in package files, and keep bare update
workspace-only under GlobalOnly.

Author: rockyshi1993

README.md

@@ -308,20 +308,24 @@ Phase 1 采用“薄 Rule + `host-capability-routing` Skill + 三份 V1 契约/
 
 | 命令 | 语义 |
 |------|------|
-| `npm install -g devcodex` | 安装全局 CLI；包安装后的 `postinstall` 自动刷新全局宿主 adapter |
-| `npm update -g devcodex` | 由 npm 升级全局包；升级后的 `postinstall` 自动刷新全局宿主 adapter |
+| `devcodex global-adapters apply` | **源码维护者日常（R1a）**：从当前包根刷新用户级五宿主 adapter；支持 `--dry-run` / `--json`；不 pack、不 publish |
+| `npm install -g .` | **本地旁路（R1b）**：全局安装当前目录并走 postinstall 刷新 adapter |
+| `npm pack` + `npm install -g ./vextjs-devcodex-*.tgz` | **预发冒烟（R2）**：接近真实 tarball 安装面 |
+| `npm install -g devcodex` | **已发布（R3）**：安装全局 CLI；`postinstall` 自动刷新全局宿主 adapter |
+| `npm update -g devcodex` | **已发布（R3）**：升级全局包并 `postinstall` 刷新 adapter |
 | `npm install devcodex` | 仅安装到当前项目依赖；`postinstall` 不写宿主配置并提示必须使用 `-g` |
-| `devcodex update` | 只刷新当前 workspace 的 `.devcodex` 运行态，不升级全局 npm 包、不写宿主配置 |
+| `devcodex update` | **workspace only（R4）**：只刷新当前 `.devcodex` 运行态，不写用户级宿主配置 |
 
 `.devcodex` 仍采用 workspace-namespace；不会迁移到 npm global prefix。安装期自动适配默认 fail-soft，可用 `DEVCODEX_SKIP_POSTINSTALL=1` 显式跳过，CI、源码仓安装和传递依赖安装默认 no-op。当前阶段只验证本地 CLI / package lifecycle 语义，不验证 npm 包名 owner、registry、dist-tag 或版本唯一性；这些属于发布前验证。首批不新增 `devcodex global init`、`devcodex init --global` 或 `devcodex sync --global`，也不纳入 Enhanced RulePack、`rules.bin`、公开仓同步、反重包保护或 runtime start/stop/restart。
 
-在 DevCodex 源码仓内运行 `status` / `doctor` 时，CLI 只比较“当前源码候选”与用户级已安装 receipt，不把候选差异解释为已安装包故障。JSON 会返回 `payload.globalHostComparison.scope=source-candidate-vs-installed-receipts`、`installedHealthClaim=false` 和 `hostParity.tier=source-candidate-comparison`；此时 `hostParity.checks`、`failedChecks` 与 `repairSteps` 为空，原始候选差异仅保留在 `withheld*` 证据字段。要验证真实全局安装健康度，应先打包并全局安装候选，再从源码仓外运行 `devcodex status` / `doctor`。
+在 DevCodex 源码仓内运行 `status` / `doctor` 时，CLI 只比较“当前源码候选”与用户级已安装 receipt，不把候选差异解释为已安装包故障。JSON 会返回 `payload.globalHostComparison.scope=source-candidate-vs-installed-receipts`、`installedHealthClaim=false` 和 `hostParity.tier=source-candidate-comparison`；此时 `hostParity.checks`、`failedChecks` 与 `repairSteps` 为空，原始候选差异仅保留在 `withheld*` 证据字段。源码仓刷新用户级 adapter 优先 `devcodex global-adapters apply`；要验证「已安装包」健康度，也可 pack/tarball 全局安装后在源码仓外跑 `status` / `doctor`。
 
 | 命令 | 说明 |
 |------|------|
 | `devcodex init` | 初始化当前 workspace 的 `.devcodex`；fresh workspace 自动建立 `workspace-namespace` marker，不创建五宿主目录 |
 | `devcodex update` | 刷新当前 workspace 的 `.devcodex`；缺少 owner 时建立 namespace marker，不创建五宿主目录 |
-| `devcodex init/update --host <id>` 及 legacy aliases | 拒绝并返回 `CLI_HOST_CONFIG_GLOBAL_ONLY`；使用 `npm install -g devcodex` 或 `npm update -g devcodex` |
+| `devcodex global-adapters apply` | 从包根 apply 用户级全局 adapter（源码日常路径） |
+| `devcodex init/update --host <id>` 及 legacy aliases | 拒绝并返回 `CLI_HOST_CONFIG_GLOBAL_ONLY`；请用 `global-adapters apply` 或 npm `-g` 路径 |
 | `devcodex uninstall --host grok` | 首批禁用；不会自动删除用户级或工作区既有配置 |
 | `devcodex uninstall` | 首批禁用；与带宿主形式返回同一 GlobalOnly 结构化错误 |
 | `devcodex grok [Grok 参数]` | 使用用户级 Grok plugin/runtime 与全局 controlling kernel；从 cwd 发现 workspace `.devcodex` |

RULES.md

@@ -25,7 +25,7 @@ DevCodex 同时支持五宿主的用户级加载路径，规则语义保持一
 - **Hook-First**：VS Code / Claude Code / Codex Hooks 可用时，通过对应宿主 hooks 承载 bootstrap、危险操作护栏和结束前兜底
 - **Instruction-Fallback**：Hooks 不可用时，继续依赖 instructions / skills 承载软约束
 - **当前实现**：npm 全局安装/升级通过 `postinstall` 更新用户级稳定 runtime、共享 full fallback 与 active Skills；共享 `.agents` 由单一事务 Owner 写入。bare `init/update` 只管理 workspace `.devcodex`，fresh workspace 会建立 `workspace-namespace` marker
-- **全局唯一写入口**：`devcodex init --claude`、`devcodex init --codex` 及其他宿主 selector/alias 均返回 `CLI_HOST_CONFIG_GLOBAL_ONLY`；宿主 adapter 通过 `npm install -g devcodex` 或 `npm update -g devcodex` 管理
+- **全局唯一写入口**：`devcodex init --claude`、`devcodex init --codex` 及其他宿主 selector/alias 均返回 `CLI_HOST_CONFIG_GLOBAL_ONLY`。用户级宿主 adapter：源码仓优先 `devcodex global-adapters apply`（或 `npm install -g .` / pack+tarball）；已发布环境 `npm install -g` / `npm update -g`（postinstall）
 - **就绪分层**：receipt 与文件存在只表示 `configured`；`status` 验证 adapter/静态合同，`doctor` 再验证可用原生 CLI、Grok canonical 唯一 identity、inspect 发现面、已安装 Hook 合同与 MCP initialize。任一合同或原生探针失败时不得标记 `ready`。
 - **受管回执**：receipt 只绑定 DevCodex 管理的 instruction、hook、MCP 与 config segment；用户自有主题或其他宿主设置不构成 adapter 漂移，受管字段变化仍必须 fail closed 并由全局安装刷新。
 - **诊断作用域**：源码仓中的 `status/doctor` 只能形成 `source-candidate-vs-installed-receipts` 候选比较，必须声明 `installedHealthClaim=false`，并抑制已安装包的 `checks/failedChecks/repairSteps`；真实全局健康结论只能由打包并安装后的候选在源码仓外形成。

changelogs/TEMPLATE.md

@@ -88,7 +88,14 @@ npx @vextjs/devcodex status
 ## 📚 迁移指南（如有破坏性变更）
 
 ```bash
-npx @vextjs/devcodex update
+# 源码维护者：刷新用户级全局 adapter（不 pack / 不 publish）
+devcodex global-adapters apply
+# 预发冒烟：
+# npm pack && npm install -g ./vextjs-devcodex-<version>.tgz
+# 已发布用户：
+# npm update -g @vextjs/devcodex
+# workspace 运行态 only：
+# devcodex update
 ```
 
 ---

changelogs/unreleased.md

@@ -5,6 +5,7 @@
 
 ## 当前未发布实现候选
 
+- **GlobalOnly 全局 adapter 本地刷新 CLI（R1a）**：新增 `devcodex global-adapters apply [--dry-run] [--json]` 与 `npm run global-adapters:apply*`，从当前包根复用 `applyGlobalHostConfig` 刷新用户级五宿主 adapter（不 pack/不 publish）。nextStep/PC5/audit/V8/doctor/help/website intro 按源码 vs 已发布分流；次选 R1b `npm install -g .`、R2 pack+tarball、R3 `npm update -g`；bare `devcodex update` 仅 workspace。`package.json` files 已纳入 `global-adapters-cli` / guidance 模块，避免 pack 后 require 断裂。**Profile 01/02/04/05/06/07 已同步 R1a~R4**（PI-173）。任务：`bugs/GlobalOnly刷全局副本命令口径漂移修复`。
 - **文档站依赖审计加固**：Rspress 提升到 2.0.18，`brace-expansion` 提升到 5.0.8；`test:audit` 改为 fail-closed 结构化审计。当前唯一例外为仅影响 unstable RSC 的 `GHSA-qwww-vcr4-c8h2`，本站静态运行面禁止 RSC 标记，例外于 2026-08-15 到期；任何新 advisory、依赖链变化、RSC 使用或到期都会重新阻断。
 - **Grok 兼容导入去重**：Grok 原生会话兼容加载 `~/.claude/settings.json` 时，DevCodex Claude adapter 识别 Grok 的 camelCase payload 与 snake_case 事件并安全跳过重复 lifecycle；Grok 专用 plugin 保持唯一生命周期 owner，消除 `user_prompt_submit` / `stop` hook 报错和双重状态写入。
 - **五宿主全局 adapter 运行态修复**：`status`/`doctor` 从 receipt/files 假就绪升级为 `configured/adapterReady/contractStatus/nativeStatus/operationalState/ready/issues` 分层；五个可执行 adapter 均增加有界契约探针，只有原生 CLI 深探针通过才可标记 operational ready。doctor 增加原生版本与 Grok list/inspect、installed Hook contract、MCP initialize。Grok plugin source 改为用户级 runtime + cwd workspace 发现，同名受管 identity 经官方 CLI drain-all 后收敛到唯一 canonical；未知来源 mutation 前阻断，首次安装与多 identity 失败均保留/恢复原注册状态，受管恢复来源可继续收敛。Copilot CLI 按官方用户级目录部署 instructions、Hooks、MCP 与 Skills；Copilot IDE 仍保持独立 instruction-fallback ceiling。
@@ -24,7 +25,7 @@
 - Codex 宿主 MCP：`init/update --codex` 部署 `.claude/mcp/*` 并向 owner `.codex/config.toml` 幂等 merge `BEGIN DEVCODEX-MCP-MANAGED` 块（devcodex-memory + profile，INPUT_ROOT=owner 根）；保留用户其它 mcp_servers；CLI 行为测试与 README 矩阵同步。需求：`Codex宿主MCP配置与分发` CP1 已确认。
 - Codex MCP 复审跟进：`doctor` 纠正「不自动写 MCP」反事实文案；`codexConfigState.mcp` 探测 managed block + server 文件存在；website development 文档与 README 对齐；测试覆盖 config 备份与 doctor mcp.status=ok。
 - PF-175 / PI-155 **ArtifactPathColumnGate**：用户面交付项强制 `路径：` 列（默认 workspace-relative portable）；Rich 语义链接可与路径列并存且无冗余 `绝对路径：` 行；同步 `user-visible-output-contract`、`02-output-paths`、delivery-checklist prompt、`classifyArtifactPathColumnSample` 与 visible-output 测试。
-- 消费者同步：`01-common`、always-on `instructions.md`、`website/docs/specs/report-output-flow.md` 补路径列口径；ECR 后 `devcodex update` 同步部署副本。
+- 消费者同步：`01-common`、always-on `instructions.md`、`website/docs/specs/report-output-flow.md` 补路径列口径；ECR 后用户级全局 adapter 用 `devcodex global-adapters apply`（或 npm `-g` 路径）同步，workspace 运行态才用 bare `devcodex update`。
 - **R2 防复现（F-001~F-009）**：Codex config merge **fail-closed**（读失败/备份失败/非法 marker/identity 冲突不写）；原子 write+rename；doctor **分 table** 取 args（禁跨 table 假阳性）；host detect 仅 `.claude/mcp` 不算 Claude；codex-only descriptors 声明 shared-mcp-runtime + managed-segment-owner；`lifecycle-visible-reply` 生产调用 `classifyArtifactPathColumnSample`；Profile 01/02/07 同步。负例：`test:cli-behavior` / host-installation / visible-output。台账 PI-157 / PF-176 / PF-177 / VL-081。
 - **V93**：压缩 `index.js` 导出与注释冗余，模块行数回到预算内（≤460），以关闭 profile-deploy/core 红项。
 - **PF-186 / PI-164 FinalValidationSummary**：dev/fix/self-fix 完成态新增 `FinalValidationSummaryV1` 短矩阵与 `DevModeCompletionCheckDetailGate`，要求最终回复列出权威验证命令/exitCode、runId 或关键计数、WorkspaceSyncStatus、dirty boundary、release action boundary；声明 commit 时追加 post-commit replay。运行时负向探针覆盖“全绿/详见报告”、报告链接-only、命令无 exitCode、git status only、缺 workspace/dirty/release 边界。

index.js

@@ -391,6 +391,9 @@ const { cmdProbe, cmdTrace } = buildCliObservabilityCommands({
   fs, process, console, c, resolveProfileDir, inspectProfileState, detectHostPlatform, detectInstalledHostAssets
 })
 const { cmdSkill, cmdTask } = buildCliExecutionCommands({ process, console, c })
+const { cmdGlobalAdapters } = require('./scripts/lib/global-adapters-cli.js').buildHandler({
+  fs, path, process, console, c, packageRoot: PKG_ROOT, packageJson: require('./package.json')
+})
 function cmdGrok(argv) {
   try {
     const result = launchGrok(argv, { cwd: process.cwd() })
@@ -404,7 +407,8 @@ function cmdGrok(argv) {
 }
 
 const cliCommandRegistry = createCliCommandRegistry({
-  cmdInitWorkspaceRuntime, cmdInitHost, cmdUninstallHost, cmdGrok, cmdStatus, cmdProfileInit, cmdDoctor, cmdProbe, cmdTrace, cmdSkill, cmdTask, cmdHelp
+  cmdInitWorkspaceRuntime, cmdInitHost, cmdUninstallHost, cmdGrok, cmdStatus, cmdProfileInit, cmdDoctor,
+  cmdProbe, cmdTrace, cmdSkill, cmdTask, cmdGlobalAdapters, cmdHelp
 })
 
 if (require.main === module) {
@@ -415,7 +419,7 @@ if (require.main === module) {
 module.exports = {
   walkDir, cmdInitWorkspaceRuntime, cmdInitHost,
   cmdUninstallHost, cmdGrok, cmdStatus, cmdHelp, cmdProfileInit, cmdDoctor, cmdProbe, cmdTrace,
-  cmdSkill, cmdTask, isSourceRepo, findLayoutInfo, inferProjectFromCwd, resolveActiveRuntimeRoot,
+  cmdSkill, cmdTask, cmdGlobalAdapters, isSourceRepo, findLayoutInfo, inferProjectFromCwd, resolveActiveRuntimeRoot,
   resolveHostAdapterScope, resolveGitignoreRoot, ensureWorkspaceNamespaceLayout, ensureRuntimeDirs, SOURCES, CLAUDE_SOURCES,
   CLAUDE_MCP_RUNTIME_SCRIPT_DEPS, CODEX_SOURCES, CLAUDE_HOOK_COMMAND, CLAUDE_MCP_JSON,
   CODEX_HOOK_COMMAND, buildDeploymentDescriptors, beginManagedDeployment, finishManagedDeployment,

instructions.md

@@ -764,4 +764,4 @@ DevCodexVisibleEnvelopeV1 · entry-check · [状态] · [semanticDigest]
 
 ---
 
-*本文件由 DevCodex 管理，请勿手动修改。升级请运行 `devcodex update`（Copilot + Claude Code + Codex）或 `devcodex update --claude` / `devcodex update --codex`（单宿主）。*
+*本文件由 DevCodex 管理，请勿手动修改。源码仓刷新用户级全局 adapter：`devcodex global-adapters apply`（或 `npm install -g .` / pack+tarball）；已发布环境：`npm update -g devcodex`。workspace `.devcodex` 仅用 bare `devcodex update`（不含 `--host`）。*

instructions/17-compliance.instructions.md

@@ -66,15 +66,17 @@ version: 1.15.3
 
 ### PC5 部署体状态（v1.11.0+，全模式基础项）
 
-> 检测条件：当 cwd 是 plugin 源仓库（含 `package.json` 且 `name` 含 `devcodex`），且 cwd 父链上存在 `.github/`、`.claude/`、`AGENTS.md`、`.agents/` 或 `.codex/` 部署体。
+> 检测条件（GlobalOnly）：
+> - **用户级全局 adapter**：`devcodex doctor` / receipt 与源码候选比对（configured / adapterReady / STALE）
+> - **legacy 父链表面**（可选诊断）：cwd 是 plugin 源仓库且父链上仍存在 `.github/`、`.claude/`、`AGENTS.md`、`.agents/` 或 `.codex/` 时，可扫描但不作为普通 workspace 安装目标
 >
 > 触发动作：
-> - 比对源仓库关键文件（instructions/skills/prompts/agents/hooks/入口副本）与父级部署体的 mtime
-> - 落后 → ⚠️ 标记，建议运行 `npx devcodex update`（按宿主需要追加 `--claude` / `--codex`）
+> - 用户级 adapter 相对源码候选落后 / STALE → ⚠️ 标记；源码仓优先运行 **`devcodex global-adapters apply`**（或次选 `npm install -g .` / `npm pack` + tarball）；已发布环境用 `npm update -g devcodex`
+> - bare `devcodex update` **只刷新 workspace `.devcodex`**，不能替代全局 adapter 刷新；`update --claude/--codex/--host` 仍 fail closed（`CLI_HOST_CONFIG_GLOBAL_ONLY`）
 > - 同步 → ✅
-> - 无父级部署体 → N/A
+> - 无用户级 receipt 且无 legacy 父链表面 → N/A 或按 doctor 缺失项提示
 >
-> 与 `scripts/validate.js` §V8 共享算法；PC5 是运行时即时检测，V8 是 CI 静态校验。
+> 与 `scripts/validate.js` §V8 / doctor global-host 检查同源；PC5 是运行时即时检测，V8 是 CI 静态校验。
 
 ### PC6 工作区一致性（v1.9.4+，全模式基础项）
 
@@ -158,7 +160,7 @@ version: 1.15.3
 | SC1 | 报告验证列完整（合理性 + 可实施性 + 收益 + 验证状态 + 影响范围五项） | 全工作流 |
 | SC2 | 代码已诊断（无未处理 error） | dev/fix 🔴 |
 | SC3 | 修复已全局扫描（同类错误模式全局+数据联动+grep零残留） | fix 🔴 |
-| SC4 | 关联文件已同步（含 profile 中定义的 dev 模式专属同步命令，如 `devcodex update`）| dev/fix/self-fix 🔴 |
+| SC4 | 关联文件已同步（workspace 运行态可用 bare `devcodex update`；用户级全局 adapter 用 `devcodex global-adapters apply` 或 npm `-g` 路径）| dev/fix/self-fix 🔴 |
 | SC5 | 后续建议与推荐结论已输出；报告含多个建议/路径时必须有 `推荐结论` / `推荐方案` 且 **唯一主动作**；禁止完成态 free-text「A 或 B」同级推荐；无待跟进时显式标注“推荐：无后续动作” | 全工作流 |
 | SC6 | Agent SUMMARY 已更新（写入动作已发生） | 全工作流 🔴 |
 | SC7 | 全局 SUMMARY 关键决策已追加 | 有关键决策时 🔴 |

instructions/tenants/README.md

@@ -44,12 +44,18 @@ applyTo: "**"
 ## 激活与部署
 
 ```powershell
+# workspace 运行态（.devcodex）可带 tenant 过滤 instructions 投影到包内 managed set
 devcodex init --tenant example-tenant
-devcodex update --claude --tenant example-tenant
+devcodex update --tenant example-tenant
+
+# 用户级全局 adapter（GlobalOnly）：不要用 update --claude/--host
+devcodex global-adapters apply
+# 或：npm install -g . / npm pack && npm install -g ./vextjs-devcodex-*.tgz
 ```
 
 - 不传 `--tenant`：Copilot/Claude managed set 排除整个 `instructions/tenants/`。
 - 传入已登记 ID：只复制对应子目录，不复制 tenant 总 README 或其他租户。
+- `update --claude` / `--host` 在 GlobalOnly 下 fail closed；全局宿主配置不走 workspace host selector。
 - Codex 当前不消费 `instructions/` 子目录；选择 tenant 不得被表述为 Codex runtime 已注入。
 
 ## 示例租户

package.json

@@ -8,6 +8,9 @@
   },
   "scripts": {
     "postinstall": "node scripts/postinstall.js",
+    "global-adapters:apply": "node index.js global-adapters apply",
+    "global-adapters:apply:dry-run": "node index.js global-adapters apply --dry-run",
+    "test:global-adapters-cli": "node scripts/test-global-adapters-cli.js",
     "test": "node scripts/run-validation.js --route full",
     "test:fast": "node scripts/run-validation.js --route fast",
     "test:full": "node scripts/run-validation.js --route full",
@@ -242,6 +245,9 @@
     "scripts/lib/profile-bootstrap-utils.js",
     "scripts/lib/cli-install-commands.js",
     "scripts/lib/cli-maintenance-commands.js",
+    "scripts/lib/global-adapter-refresh-guidance.js",
+    "scripts/lib/global-adapters-cli.js",
+    "scripts/test-global-adapters-cli.js",
     "scripts/lib/host-parity-scorecard.js",
     "scripts/lib/parity-unaligned-ledger.js",
     "scripts/lib/parity-upgrade-decision.js",

scripts/lib/cli-command-registry.js

@@ -3,7 +3,11 @@
 const { HOST_ALIASES, HOST_IDS } = require('./host-surface-descriptors')
 
 function createCliCommandRegistry(commands) {
-  const required = ['cmdInitWorkspaceRuntime', 'cmdInitHost', 'cmdUninstallHost', 'cmdGrok', 'cmdStatus', 'cmdProfileInit', 'cmdDoctor', 'cmdProbe', 'cmdTrace', 'cmdSkill', 'cmdTask', 'cmdHelp']
+  const required = [
+    'cmdInitWorkspaceRuntime', 'cmdInitHost', 'cmdUninstallHost', 'cmdGrok', 'cmdStatus',
+    'cmdProfileInit', 'cmdDoctor', 'cmdProbe', 'cmdTrace', 'cmdSkill', 'cmdTask',
+    'cmdGlobalAdapters', 'cmdHelp'
+  ]
   for (const name of required) {
     if (typeof commands[name] !== 'function') throw new TypeError(`missing CLI command handler: ${name}`)
   }
@@ -120,6 +124,10 @@ function runCliCommand({ cmd, argv, registry, runMigrateLayout, process, c, cons
     return 'migrate-layout'
   }
   if (cmd === 'grok') { registry.cmdGrok(argv); return 'grok' }
+  if (cmd === 'global-adapters') {
+    registry.cmdGlobalAdapters(argv)
+    return 'global-adapters'
+  }
   if (cmd === 'status') { registry.cmdStatus(argv); return 'status' }
   if (cmd === 'doctor') { registry.cmdDoctor(argv); return 'doctor' }
   if (cmd === 'probe') { registry.cmdProbe(argv); return 'probe' }