@givolt/i3-composer-agent 2.3.1 → 2.3.3

package/skills/i3-ui-prototype/references/workflow-contract.md

@@ -8,12 +8,70 @@
 默认使用简体中文解释、追问及生成报告；用户明确要求其他语言时可切换。原方法正文、引用、阈值和审批条件完整保留。代码标识、路径、命令、工具参数、JSON 键/枚举与原文引用保持原样。
 <!-- i3:zh-guide:end -->
 
-create 读取业务上下文、检测默认专业增强模式、展示四类模板的可用状态并记录选择，然后初始化和适配原型。企业后台当前可用；AI 工作台、数字孪生大屏和移动端尚待建设，不能自动替换为其他模板。兼容旧版三套模板仅供已有项目继续使用。脚本返回 needs-design-provider 时不得冒充创建成功；允许先完成需求和模板比较，等待安装或用户选择 template。已有原型的 expertMode 作为迭代默认值。
+## 公共前置与副作用
 
-revise 必须指定未使用的新版本；改变全局导航、token、组件行为或业务状态时解释影响并形成新的评审候选。inspect 可写检查报告但不修改页面或冻结基线。confirm-baseline 必须有用户对具体内容的明确认可和完整必需证据。
+主会话通过自然语言、命令、元技能或直接 Skill 使用同一顺序：识别操作及限制，读取实际文件和清单，恢复固定输入／版本／交接，确认实际工具，确定单一修改负责人，再进入对应运行层。入口仅发现工作 Skill，不强制分派角色，不绕回命令或元技能。按操作需要复用 frontend、框架官方、UIUX 和 browser 技能，各工程技能保留原有方法。
 
-verification 使用 not-run、partial、passed、failed、blocked；review 使用 pending-review、changes-requested、approved。expert 使用 pending、used、skipped、missing、unusable、no-match。它们分别表示检查、用户认可及专业能力使用；不相互推断。
+| 操作 | 允许范围 |
+| --- | --- |
+| analyze | 只读文件和已核对的只读查询，分析留在会话 |
+| create | 在授权项目内准备未存在的用户模板副本、同步索引、创建新实例并实现 |
+| revise | 基于实际文件及固定合同形成新候选，保留手改和旧基线 |
+| inspect | 检查当前实例；用户明确只读时不保存报告或运行状态 |
+| confirm-baseline | 用户认可具体版本且验收匹配后，保存不可覆盖的快照 |
 
-原型可从草拟需求开始。需求确认、原型认可、正式规格批准和生产授权各自保存。返回 scope、revision、mode、verification、review、openQuestions 和下一项必要动作，避免笼统地报告全部完成。
+明确“不改代码／不写文件”优先于默认 create。analyze 不创建目录、安装升级、写 provider 结果、初始化运行记录或改变状态；约束包括检查器、官方 Skill、UIUX 和浏览器助手的下游行为。用户要求保存分析文档时只写指定输出。只读期间不得为了记录执行模式而落盘。
+
+analyze 返回需求／通用能力覆盖、模板与框架选型、验收计划和未决项，信息足够后停止探索并回传。已有来源的固定 profile／component-map／acceptance 可支持选型，不等于逐组件逐 Prop 实施核验；只对影响选型的具体疑点定向查本地 API。完整目标版本包／源码验证留 create，不遍历 starter、node_modules、整套 CLI 帮助或组件清单来证明分析；必要定向读取仍可进行。未知点保留 openItems，不把 UIUX 准入、逐条采纳、构建或浏览器当分析前置，不把计划写成已验证结果。
+
+能力覆盖包含绑定参数，不能只按 Table／pagination 等名称匹配。PRD 要求可调页大小而当前绑定 `fixedPageSize: 10` 时，报告部分覆盖、明确在可写阶段需显式适配；固定值不是默认值，不能借已有通用分页能力宣称全部满足。分析完整交付可 status=complete，但覆盖检查与 openItems 如实保留冲突；仅分析未完成才 partial／blocked。只读期间不改需求、绑定或固定输入，后续计划不记为已实现或已验收。
+
+先按实际 `--host`、`--scope` 只读检测宿主基址 `tools/i3-prototype/` 下的工具，保留旧项目 `.prototype-tools` 检测；或使用宿主已经明确给出的绝对入口，核对固定版本后直接调用；不要反复扫描 node_modules。analyze 不运行 npm exec／npx 或任何会自动安装／补缓存的命令；缺工具报告未决项，改用现有只读资料。可写模式同样使用准备好的本地固定 CLI，只有工具准备另有授权时才在明确工具目录安装；该授权不包含业务文件、已安装 SDK、宿主设置或未选择的全局目录。项目构建依赖的 --install 是另一项写操作，不能借用查询工具授权。
+
+create／revise 的项目写入范围不包含用户级长期记忆或宿主 auto-memory；未经用户明确要求，不创建或更新这些文件。纯文件续接依靠实例合同与交接；测试启动时核对宿主记忆开关和工具写入范围，不将 no-session-persistence 视为禁止 auto-memory，不更改全局偏好。
+
+执行阶段保持一个源码／合同修改负责人；另有授权的协作按实际工具和执行记录留证，不冒认其他执行者的工作。连续性来自文件。写入前核对预期 revision／candidateDigest，遇到并发变化停止该次写入并重读，不覆盖较新候选。
+
+## 原生组件 v2
+
+已有实例优先用 native-pilot.cjs state 一次恢复合同、身份、设计／构建／QA及精确 commands，不遍历依赖或反复读控制器实现。真实查询与人工设计取舍完成后，本轮 CodeBuddy 原生流程依次为 build→宿主实际加载 i3-browser-testing-with-devtools Skill→Chrome DevTools MCP 按能力执行并取得实际观测→新业务场景实测及 record-run（旧设备合同另用 browser 专项回归）→state→finalize→独立最终回复。Skill 的 DOM／计算样式、截图、console、network、a11y 与 performance 观测不能只列计划或挂名；缺任一必需工具／执行时整链不 complete。analyze 只提出这份验收计划，不启动检查。
+
+browser 是历史设备合同的 Playwright 专项工具，自行管理服务，不替代上述 Skill 或 MCP。实际 DevTools 检查后用 record-devtools-review --report 登记独立 qa/devtools-review.json；新 create 的固定 acceptance.browserReview 要求当前报告，state 列缺项，finalize 拒绝缺失／过期／证据变化。脚本只核结构、文件和当前身份，不证明真实调用，仍输出 invocationVerified=false。主会话另核原始宿主 stream、实际观测及同一 candidate／build，交付前核对当前 state／delivery，再以自然语言给出结果和证据位置。详细证据合同见 interaction-acceptance。旧 v1 和无 browserReview 的已有 v2 保留原验收，新要求仅进入新实例或显式接受变更的输入；其他宿主的等效工具结果单列，不冒充这条指定链。
+
+create 使用完整 enterprise-admin 内容模板、实际 scope.pages／regions 和 vue-antdv-next 框架，使用 native-pilot.cjs。用户 HTML 工作副本升级不覆盖。创建前检查标识、绑定和索引一致，固定本次范围、模板、能力、框架及必需场景。PRD 可简短，但明确／假设／待确认／范围外须有来源。
+
+目标目录须留给原子 create：provider 先 probe，初始化后才在实例 qa 下保存查询和设计证据。初始化前需要保存的官方／UIUX 查询使用独立准备目录，不能预先创建 prototypes/<id>/qa。没有 prototype.json 的已有目录先核对来源，不能调用 revise 冒充实例。只有确认整个目录均由本次准备操作产生，才可整体移走，确保目标不存在后重试；只移文件留下空目录仍会失败。含用户或未知文件时保留并报告冲突。
+
+required 不可任意 N/A；检查器按已声明业务区域重算必需集合，实际页面与区域的对应由前端／浏览器复核。缺失语义、参数或范围仍待处理，不能为通过删能力。新流程的分页与四主题默认及 scope 格式见 [content-template.md](content-template.md)。初始化状态为 needs-adaptation，主会话继续实现实际业务；完成后标 adapted，才进入当前候选验收。旧设备列表的固定容量、可选主题和验收数量仍按旧 inputs，不追溯追加要求。
+
+revise 使用 `native-pilot.cjs revise <root> --revision <new> --expected-revision <current> --expected-digest <currentDigest>`，保留实际源码而非重复制 starter。模板或框架升级是显式输入变更，旧实例继续检查固定输入。手改后旧证据失效；新交互补映射，删除必需功能产生缺口。
+
+确需更改固定输入时，由当前修改负责人先整理 inputs 中完整新快照、能力／范围／场景及 requirements-map，再使用同一 revise 命令加 `--accept-inputs`。该选项在锁和预期版本保护下完整校验新合同，成功才接受新 inputDigest 和版本并清除旧验证状态；失败不推进版本。它不自动下载或套用新模板、框架，不补造需求映射。普通 revise 遇到输入变化会拒绝，避免新版本带着旧摘要。
+
+inspect、manifest、build 按 v2 合同执行；不得让 legacy 写接口接管。首次可写构建使用 `build <root> --install` 安装固定锁依赖，后续 build 复用依赖。preview 输出 URL 并持续服务，--build-id 可选择固定构建。浏览器证据导入后 `inspect <root> --acceptance` 检查覆盖与身份。
+
+持续写任务可 `claim <root> --owner <owner> --expected-revision <revision> --expected-digest <digest>`；revise 传同一 owner，编辑结束 `release <root> --owner <owner>` 后再验收／确认。临时修改由脚本 claim／release。锁不进入候选身份，丢失 Agent 不自动清除别人仍持有的修改权。
+
+compare-baseline 只比较当前候选与已保存基线；confirm-baseline --confirmation 接收具体版本的人类确认，再核对当前验收并保存不可覆盖快照。证据不齐保留待确认候选，不手工构造批准状态。
+
+## Legacy HTML
+
+legacy create 读取业务上下文、检测专业模式、展示四类模板可用状态并记录选择，再初始化和适配。企业后台可用；AI 工作台、数字孪生大屏和移动端 planned，不能替换生成。旧三套模板供历史实例。needs-design-provider 不等于成功；可先比较需求和模板，按已有授权修复或等待明确选择 template。已有 expertMode 作为迭代默认。
+
+legacy revise 指定未使用版本，改变导航、token、组件行为或业务状态时解释影响。inspect 写报告服从本次范围，不改页面或冻结。确认须有具体版本的用户认可和完整必需证据。旧实例不补写 v2 metadata，不改原摘要及已冻结历史。
+
+## 状态与交付
+
+verification 使用 not-run、partial、passed、failed、blocked；review 使用 pending-review、changes-requested、approved。expert 使用 pending、used、reviewed、skipped、missing、unusable、no-match。它们分别表示检查、用户认可及专业能力使用；不相互推断。
+
+专业查询成功、建议处理、采用和效果验证独立保存。有依据的零采用可完成复核，冻结不自动改 used。template 明确跳过专业查询但不降低功能验收。provider 不可用报告具体原因，不静默切模式。
+
+原型可从草拟需求开始。需求确认、原型认可、正式规格批准和生产授权分别保存。返回 operation、scope、revision、executionMode、mode、verification、review、openQuestions 和下一项必要动作；说明结构、真实宿主、浏览器和人类确认各自结果。
+
+各入口在工具之后用自然语言交付实际范围、身份、证据、缺项和下一步，不强制父子 JSON、标记或结构校验。validate-result.cjs 可作特定维护工具，不是普通原型入口前置。业务、当前 state/delivery、真实 QA 分别核对，不能由结构结果推断。analyze 留在会话、不写收据；参数冲突以部分覆盖和未决项说明，不把分析完成等同覆盖通过。
 
 企业后台默认 purpose=business-prototype，完整参考副本的 business.status=needs-adaptation；必须完成实际业务适配才能验收。用户明确评审 EASEL 模板本身时，使用 purpose=template-review，并将 reference-demo 范围写进交接。模板认可不等于任何新业务的需求或原型认可。
+
+## 项目共享与宿主缓存
+
+默认业务写入集中于 prototypes：准备区 .preparation/<id>、共享 index.json 和本次实例。安装与分析不提前生成这些资料；原型流程不在根目录散落准备目录、工具或浏览器 CLI 输出。工具与缓存使用实际宿主基址，global 缓存按规范化项目身份隔离；正式需求、交接与 QA 归实例。旧路径不因升级自动迁移。目录、scope.moduleIds 与 appliesTo 的唯一来源、冲突及迁移规则见 [project-layout.md](project-layout.md)。

package/skills/i3-ui-prototype/scripts/adapters/easel-html.cjs

@@ -8,7 +8,7 @@ module.exports = {
     kind: 'easel-html', identityFields: ['purpose', 'business', 'runtime'],
     requiredFiles: ['app/app.js', 'app/enterprise-bootstrap.mjs', 'app/routes.json', 'app/runtime/dom.js', 'app/styles/tokens.css', 'design-system/source.json'],
     excludedBrowserPrefixes: ['app/tools/', 'app/tests/', 'app/qa/'],
-    protectedFiles: ['app/tokens.css', 'app/styles.css', 'app/index.html', 'app/domain.mjs', 'requirements-map.json', 'app/app.js', 'app/routes.json', 'app/config.json', 'app/enterprise-bootstrap.mjs', 'app/usability.css'],
+    protectedFiles: ['app/tokens.css', 'app/styles.css', 'app/index.html', 'app/domain.mjs', 'requirements-map.json', 'app/app.js', 'app/routes.json', 'app/config.json', 'app/enterprise-bootstrap.mjs', 'app/usability.css', 'app/offline.js'],
     protectedDirectories: ['design-system/', 'app/styles/', 'app/runtime/', 'app/src/'],
   },
   fingerprintInputs(context) {

package/skills/i3-ui-prototype/scripts/browser-workspace.cjs

@@ -0,0 +1,72 @@
+'use strict';
+const { fs, path, crypto, hash, assert, json, id, inside, write } = require('./native-files.cjs');
+const { spawnSync } = require('node:child_process');
+const { resolveLocations } = require('./prototype-locations.cjs');
+function location(options) {
+  id(options.runId);
+  const context = resolveLocations(options);
+  return { context, directory: inside(context.cacheDirectory, `playwright/${options.runId}`) };
+}
+function prepare(options = {}) {
+  const { context, directory } = location(options), configFile = inside(directory, 'cli.config.json');
+  const config = { outputDir: directory, outputMode: 'file' };
+  if (fs.existsSync(configFile)) assert.deepEqual(json(configFile), config, 'Existing browser output config differs; preserve it and use another run ID');
+  else write(directory, 'cli.config.json', config);
+  return { status: 'prepared', directory, configFile, host: context.host, scope: context.scope, projectKey: context.projectKey,
+    environment: { PLAYWRIGHT_MCP_OUTPUT_DIR: directory, PLAYWRIGHT_MCP_CONFIG: configFile } };
+}
+function runCli(options = {}) {
+  assert.ok(typeof options.cli === 'string' && path.isAbsolute(options.cli), '--cli requires an existing absolute Playwright CLI Node entry');
+  const entry = fs.realpathSync(options.cli); assert.ok(fs.statSync(entry).isFile(), 'CLI entry must be a file');
+  assert.ok(Array.isArray(options.command) && options.command.length && options.command.every(value => typeof value === 'string'), 'Provide CLI arguments after --');
+  assert.ok(!options.command.some(value => value === '--config' || value.startsWith('--config=')), 'Output config is managed by this wrapper');
+  const command = options.command.find(value => !value.startsWith('-'));
+  assert.ok(!['install', 'install-browser', 'close-all', 'kill-all'].includes(command), 'Installation and all-session commands are not prototype browser operations');
+  const output = prepare(options);
+  const result = spawnSync(process.execPath, [entry, '--config', output.configFile, ...options.command], {
+    cwd: output.directory, env: { ...process.env, ...(options.env || {}), ...output.environment }, encoding: 'utf8', timeout: 60000, maxBuffer: 16 * 1024 * 1024 });
+  const call = `cli-${crypto.randomUUID()}`;
+  write(output.directory, `${call}.stdout.log`, result.stdout || ''); write(output.directory, `${call}.stderr.log`, result.stderr || result.error?.message || '');
+  return { ...output, status: result.status === 0 && !result.error ? 'executed' : 'failed', exitCode: result.status,
+    stdout: result.stdout || '', stderr: result.stderr || result.error?.message || '', verification: 'not-assessed' };
+}
+function archive(options = {}) {
+  const { context, directory: source } = location(options);
+  assert.ok(fs.existsSync(source), 'Browser cache does not exist');
+  const files = Array.isArray(options.files) ? options.files : typeof options.files === 'string' ? options.files.split(',') : [];
+  assert.ok(files.length && new Set(files).size === files.length, 'Explicit unique output files are required');
+  const selected = files.map(file => {
+    assert.ok(!['archive.json', 'cli.config.json'].includes(file), 'Reserved browser output filename');
+    const from = inside(source, file); assert.ok(fs.statSync(from).isFile(), 'Only regular output files can be archived');
+    return { file, from, digest: hash(fs.readFileSync(from)) };
+  });
+  const prototype = require('./project-registry.cjs').paths(context.project, options.id).directory;
+  assert.ok(prototype && fs.existsSync(prototype), 'Prototype must already exist');
+  const ownerFile = inside(prototype, '.prototype-write.lock');
+  if (fs.existsSync(ownerFile)) assert.equal(json(ownerFile).owner, options.owner, 'Prototype has another active writer');
+  const native = require('./native-pilot-lib.cjs'), candidate = native.manifest(prototype);
+  const parent = inside(prototype, `qa/runs/${options.runId}`), destination = inside(parent, 'tool-output');
+  assert.ok(!fs.existsSync(destination), 'Archived output already exists; preserve it');
+  fs.mkdirSync(parent, { recursive: true });
+  const lockFile = inside(parent, '.tool-output.lock'), lock = fs.openSync(lockFile, 'wx');
+  let stage;
+  try {
+    stage = fs.mkdtempSync(path.join(parent, '.archive-'));
+    for (const item of selected) {
+      const target = inside(stage, item.file); fs.mkdirSync(path.dirname(target), { recursive: true });
+      fs.copyFileSync(item.from, target, fs.constants.COPYFILE_EXCL);
+      assert.equal(hash(fs.readFileSync(target)), item.digest, 'Output changed while archiving');
+      assert.equal(hash(fs.readFileSync(item.from)), item.digest, 'Source output changed while archiving');
+    }
+    write(stage, 'archive.json', { schemaVersion: 1, host: context.host, scope: context.scope, projectKey: context.projectKey, runId: options.runId,
+      candidateDigest: candidate.digest, revision: candidate.revision, files: Object.fromEntries(selected.map(item => [item.file, item.digest])), verification: 'not-assessed' });
+    assert.equal(native.manifest(prototype).digest, candidate.digest, 'Candidate changed while archiving');
+    assert.ok(!fs.existsSync(destination), 'Archived output appeared while copying');
+    fs.renameSync(stage, destination);
+    return { status: 'archived', directory: destination, files, verification: 'not-assessed' };
+  } finally {
+    if (stage && fs.existsSync(stage)) fs.rmSync(stage, { recursive: true, force: true });
+    fs.closeSync(lock); fs.unlinkSync(lockFile);
+  }
+}
+module.exports = { prepare, runCli, archive };

package/skills/i3-ui-prototype/scripts/codebuddy-context.cjs

@@ -0,0 +1,75 @@
+'use strict';
+const fs=require('node:fs'),path=require('node:path'),os=require('node:os'),assert=require('node:assert/strict');
+const R=require('./codebuddy-registration.cjs'),E=require('./execution-evidence.cjs');
+const FILES=['execution-policy.cjs','execution-evidence.cjs','codebuddy-ide-source.cjs','execution-gates.cjs','execution-assertions.cjs','execution-runtime.cjs','codebuddy-context.cjs','codebuddy-registration.cjs','codebuddy-hook.cjs','prototype-hooks.cjs','hosts/codebuddy.cjs','native-pilot.cjs','native-pilot-lib.cjs','native-delivery.cjs','native-devtools.cjs','native-files.cjs','native-build.cjs'];
+const read=file=>R.fileIO.read(file);
+function scriptsForEntry(scriptPath) {
+ if(path.basename(scriptPath)!=='i3-prototype.cjs')return path.dirname(path.dirname(scriptPath));
+ const root=path.resolve(path.dirname(scriptPath),'..');
+ const candidates=[root,path.dirname(root)].flatMap(directory=>['i3-ui-prototype',['ui','prototype'].join('-')].map(id=>path.join(directory,'skills',id,'scripts')));
+ const scripts=candidates.find(dir=>fs.existsSync(path.join(dir,'hosts/codebuddy.cjs')));assert.ok(scripts,'Unified Hook entry has no prototype Skill');return path.resolve(scripts);
+}
+function bundle(scriptPath) {
+ const scripts=scriptsForEntry(scriptPath);
+ const files=FILES.map(file=>[file,E.sha(fs.readFileSync(path.join(scripts,file)))]);
+ files.push(['profile',E.sha(fs.readFileSync(path.join(scripts,'../assets/hosts/codebuddy/profile.json')))]);
+ if(path.basename(scriptPath)==='i3-prototype.cjs') {
+  files.push(['unified-entry',E.sha(fs.readFileSync(scriptPath))]);
+  files.push(['unified-manager',E.sha(fs.readFileSync(path.join(path.dirname(scriptPath),'manage.cjs')))]);
+ }
+ return E.sha(JSON.stringify(files));
+}
+function registration(base) {
+ const raw=read(path.join(base,'state/i3-prototype/installation.json'));if(!raw)return null;
+ const record=JSON.parse(raw);assert.equal(record.owner,R.OWNER,'Unknown Hook ownership');assert.equal(record.schemaVersion,1,'Unsupported Hook ownership');assert.equal(record.base,base,'Hook base differs');
+ const settingsText=read(path.join(base,'settings.json')),settings=R.config(settingsText);
+ for(const event of R.EVENTS)assert.equal((settings.hooks?.[event]||[]).filter(group=>JSON.stringify(group)===JSON.stringify(record.groups[event])).length,1,'Registered Hook was removed, duplicated, or edited');
+ assert.equal(bundle(record.scriptPath),record.scriptDigest,'Audit adapter bytes changed; refresh owned registration');
+ assert.ok(fs.existsSync(record.nodePath),'Registered Node executable is missing');
+ return {...record,settingsDigest:E.sha(settingsText),registrationDigest:E.sha(JSON.stringify(record))};
+}
+function globalBase({home=os.homedir(),env=process.env}={}) {
+ const configured=env.CODEBUDDY_CONFIG_DIR?.trim();
+ if(!configured)return path.join(home,'.codebuddy');
+ assert.ok(path.isAbsolute(configured)&&!/[\x00\r\n]/.test(configured),'CODEBUDDY_CONFIG_DIR must be an absolute safe directory');
+ return path.normalize(configured);
+}
+function select({project,product,home=os.homedir(),env=process.env,readText=read,loadRegistration=registration}) {
+ const projectBase=path.join(project,'.codebuddy'),userBase=globalBase({home,env});
+ const projectText=readText(path.join(projectBase,'settings.json')),localText=readText(path.join(projectBase,'settings.local.json'));
+ if(localText){const local=R.config(localText);assert.ok(!local.hooks&&!local.disableAllHooks&&!local.allowManagedHooksOnly,'Local Hook overrides are not supported by this profile');}
+ const projectSettings=R.config(projectText);assert.ok(!projectSettings.disableAllHooks&&!projectSettings.allowManagedHooksOnly,'Project Hook policy prevents automatic auditing');
+ const globalText=readText(path.join(userBase,'settings.json')),globalSettings=R.config(globalText);assert.ok(!globalSettings.disableAllHooks&&!globalSettings.allowManagedHooksOnly,'Global Hook policy prevents automatic auditing');
+ // IDE documents project settings as an override. Do not silently fall back through a shadowing file.
+ const bases=product==='ide'&&projectText!==null?[projectBase]:[projectBase,userBase];
+ for(const base of [...new Set(bases)]) {
+  const record=loadRegistration(base);if(!record)continue;
+  assert.equal(record.product,product,'Conflicting CodeBuddy product profiles');return record;
+ }
+ return null;
+}
+function projectKey(project){return `${path.basename(project).replace(/[^a-zA-Z0-9_-]/g,'-').slice(0,32)||'project'}-${E.sha(project).slice(0,16)}`;}
+function sessionDirectory(record,project,sessionId) {
+ assert.ok(typeof sessionId==='string'&&sessionId,'Native session ID required');
+ return path.join(record.base,'state/i3-prototype',projectKey(project),E.sha(sessionId).slice(0,24));
+}
+function source(payload,record,project) {
+ assert.ok(typeof payload.transcript_path==='string'&&typeof payload.session_id==='string','Native transcript and session fields required');
+ const roots=record.transcriptRoots||[],mode=record.transcriptMode||(roots.length?'manual':'auto');
+ const value=E.readSource(payload.transcript_path,roots,{mode,project});
+ assert.ok(value.prompts.length,'Original user task is absent from native transcript');
+ assert.ok(value.calls.every(call=>call.sessionId===payload.session_id),'Native session identity missing or mismatched');
+ assert.ok(value.prompts.every(prompt=>!prompt.sessionId||prompt.sessionId===payload.session_id),'Native prompt session differs');
+ return value;
+}
+function readOnly(prompt) {
+ if(/不(?:要)?(?:改代码|修改(?:任何)?代码|实施|生成原型)|\b(?:analysis only|do not (?:edit|modify|implement))\b/i.test(prompt))return true;
+ if(/(?:只|仅).{0,6}(?:分析|讨论|梳理|检查|解释)/.test(prompt))return true;
+ if(/先.{0,4}(?:分析|讨论|梳理|检查|解释)/.test(prompt)&&!/(?:然后|再|后).{0,8}(?:实现|实施|修改|继续)/.test(prompt))return true;
+ return /^\s*(?:请|先)?(?:暂停|停止|取消)(?:[，。！\s]|(?:这|当前|实施|工作|修改|生成))|^\s*(?:stop|cancel|pause)\b/i.test(prompt);
+}
+function prefix(file,bytes,digest) {
+ assert.ok(Number.isSafeInteger(bytes)&&bytes>0&&bytes<=64*1024*1024,'Invalid source cursor');
+ const raw=E.cursorBytes(file);assert.ok(raw.length>=bytes,'Native transcript was truncated');assert.equal(E.sha(raw.subarray(0,bytes)),digest,'Native transcript prefix changed');
+}
+module.exports={read,scriptsForEntry,bundle,registration,globalBase,select,projectKey,sessionDirectory,source,readOnly,prefix};

package/skills/i3-ui-prototype/scripts/codebuddy-hook.cjs

@@ -0,0 +1,157 @@
+'use strict';
+const fs=require('node:fs'),path=require('node:path'),crypto=require('node:crypto'),assert=require('node:assert/strict');
+const F=require('./native-files.cjs'),C=require('./codebuddy-context.cjs'),E=require('./execution-evidence.cjs'),P=require('./execution-policy.cjs'),G=require('./execution-gates.cjs');
+const X=require('./execution-runtime.cjs');
+function tokens(command) {
+ if(typeof command!=='string'||/[\x00\r\n]|\$\(|`/.test(command))return null;
+ const values=[];let value='',quote=null,started=false;
+ for(let i=0;i<command.length;i++) {const c=command[i];if(quote){if(c===quote){quote=null;started=true;}else if(c==='\\'&&quote==='"'&&i+1<command.length)value+=command[++i];else value+=c;}
+ else if(c==='"'||c==="'"){quote=c;started=true;}else if(c==='\\'&&i+1<command.length){value+=command[++i];started=true;}else if(/\s/.test(c)){if(started){values.push(value);value='';started=false;}}else if(/[;&|<>]/.test(c))return null;else {value+=c;started=true;}}
+ if(quote)return null;if(started)values.push(value);return values;
+}
+function nativeCommand(tool,input,cwd) {
+ if(!['Bash','execute_command','run_terminal_command'].includes(tool))return null;
+ const argv=tokens(input?.command);if(!argv)return null;const index=argv.findIndex(arg=>path.basename(arg)==='native-pilot.cjs');if(index<1)return null;
+ const operation=argv[index+1],root=argv[index+2]&&!argv[index+2].startsWith('--')?path.resolve(cwd,argv[index+2]):null;
+ return {operation,root,argv};
+}
+function eventCall(payload,source) {
+ const canonical=value=>Array.isArray(value)?value.map(canonical):value&&typeof value==='object'?Object.fromEntries(Object.keys(value).sort().map(k=>[k,canonical(value[k])])):value;
+ const partial=(before,after)=>typeof before==='string'?typeof after==='string'&&after.startsWith(before):Array.isArray(before)?Array.isArray(after)&&before.length<=after.length&&before.every((value,i)=>partial(value,after[i])):before&&typeof before==='object'?after&&typeof after==='object'&&Object.keys(before).every(key=>Object.hasOwn(after,key)&&partial(before[key],after[key])):before===after;
+ const matches=source.calls.filter(call=>{
+  if(call.name!==payload.tool_name||call.requestLine<source.prompts.at(-1).line||payload.tool_use_id&&call.toolCallId!==payload.tool_use_id)return false;
+  if(source.format==='codebuddy-ide-index-v1'&&payload.generation_id&&call.nativeRequestId!==payload.generation_id)return false;
+  if(JSON.stringify(canonical(call.input))===JSON.stringify(canonical(payload.tool_input||{})))return true;
+  // IDE 4.12 streams incomplete args to disk before PreToolUse. Correlate its
+  // actual callback with one pending native call in the exact generation. The
+  // pending call remains unsuccessful until a native result is persisted.
+  return source.format==='codebuddy-ide-index-v1'&&payload.client==='CodeBuddyIDE'&&typeof payload.generation_id==='string'&&call.nativeRequestId===payload.generation_id&&!call.resultLine&&partial(call.input,payload.tool_input||{});
+ });
+ const current=payload.hook_event_name==='PreToolUse'?matches.filter(call=>!call.resultLine):matches;
+ assert.equal(current.length,1,'Native Hook event does not uniquely match the current transcript request');return current[0];
+}
+function eventSource(payload,record,project,{readSource=C.source,pause=milliseconds=>Atomics.wait(new Int32Array(new SharedArrayBuffer(4)),0,0,milliseconds)}={}) {
+ const toolEvent=['PreToolUse','PostToolUse'].includes(payload.hook_event_name);
+ // IDE can persist the current call only AFTER returning from both Hooks. Its
+ // current native prompt/generation still binds the callback. Never synthesize
+ // a successful call; A checks the persisted request/result at a later stage.
+ const attempts=toolEvent&&record.product==='ide'&&payload.client==='CodeBuddyIDE'?8:1;
+ for(let attempt=1;attempt<=attempts;attempt++) {
+  try {
+   const source=readSource(payload,record,project);
+   let nativeRequestStatus='not-tool-event';
+   if(toolEvent) {
+    if(source.format==='codebuddy-ide-index-v1'&&record.product==='ide'&&payload.client==='CodeBuddyIDE') {
+     const latest=source.prompts.at(-1);
+     assert.ok(typeof payload.generation_id==='string'&&latest?.nativeRequestId===payload.generation_id,'IDE callback differs from the current native task generation');
+     const pending=source.calls.filter(call=>!call.resultLine&&call.requestLine>latest.line&&call.nativeRequestId===payload.generation_id&&call.name===payload.tool_name);
+     if(pending.length) {eventCall(payload,source);nativeRequestStatus='pending-native-request';}
+     else nativeRequestStatus='deferred-until-native-persistence';
+    }else {eventCall(payload,source);nativeRequestStatus='matched-native-request';}
+   }
+   return {...source,nativeReadAttempts:attempt,nativeRequestStatus};
+  }catch(error){if(attempt===attempts)throw error;pause(100);}
+ }
+}
+function decision({event,source,binding,tool,input,directory,cwd,deliveryCurrent,stopHookActive=false}) {
+ if(C.readOnly(source.prompts.at(-1)?.text||''))return {continue:true,reason:'latest-user-read-only'};
+ if(event==='PreToolUse'&&G.uiWrite({name:tool,input:input||{},cwd},directory)) {
+  const front=E.loaded(source.calls,'frontend').filter(c=>c.sessionId===binding?.sessionId&&c.requestLine>source.contextLine&&(source.stableThroughLine===undefined||c.resultLine<=source.stableThroughLine));
+  if(!binding||binding.entryLine!==source.prompts.at(-1)?.line||binding.contextLine!==source.contextLine||!front.length)return {deny:true,reason:'Run execution-begin for the current task and load the frontend engineering Skill successfully in this session/context before writing prototype UI. Reading SKILL.md is insufficient.'};
+ }
+ const final=source.latestAssistant||'',claim=/(?:已完成|已经完成|全部通过|可以交付|\b(?:completed|ready for review|all checks passed)\b)/i.test(final)&&!/(?:未完成|尚未|待验证|阻塞|等待|进度|blocked|awaiting|not complete|in progress)/i.test(final);
+ if(event==='Stop'&&binding&&!deliveryCurrent&&!stopHookActive&&claim)return {feedback:true,reason:'This prototype run has no current verified receipt. Run execution-check and resolve the missing evidence, or report blocked / awaiting-input / progress without claiming completion.'};
+ return {continue:true};
+}
+function prototypeForWrite(project,tool,input) {
+ if(!['Write','Edit','MultiEdit','write_to_file','replace_in_file'].includes(tool))return null;
+ const file=input?.file_path||input?.filePath||input?.path||input?.TargetFile;if(typeof file!=='string')return null;
+ let current=path.dirname(path.resolve(project,file));const prototypes=path.join(project,'prototypes');
+ while(current.startsWith(prototypes+path.sep)){if(fs.existsSync(path.join(current,'prototype.json')))return fs.realpathSync(current);current=path.dirname(current);}return null;
+}
+function safeProject(payload,options={},env=process.env,real=file=>fs.realpathSync(file),callbackCwd=process.cwd(),workspace=E.ideWorkspace) {
+ const ideRoot=options.product==='ide'&&payload.client==='CodeBuddyIDE'&&payload.cwd==='/';
+ const root=options.scope==='project'?path.dirname(options.base):ideRoot?workspace(payload.transcript_path,payload.session_id):env.CODEBUDDY_PROJECT_DIR||env.CLAUDE_PROJECT_DIR||payload.cwd||(payload.hook_event_name==='SessionStart'?callbackCwd:null);assert.ok(root&&path.isAbsolute(root),'Native project directory required');
+ const project=real(root);
+ // IDE 4.12.2 reports '/' for absolute-path tools. Use the project registration
+ // or session-bound native workspace above; reject all other outside cwd.
+ if(payload.cwd&&!ideRoot){const relative=path.relative(project,real(payload.cwd));assert.ok(relative!=='..'&&!relative.startsWith('..'+path.sep)&&!path.isAbsolute(relative),'Hook cwd is outside project');}return project;
+}
+function saveIndex(directory,index) {
+ for(const entry of Object.values(index.bindings))F.write(path.dirname(directory),`runs/${entry.runId}/binding.json`,entry);
+ F.write(directory,'session.json',index);
+}
+function toolCwd(payload,record,project) {
+ return record.product==='ide'&&payload.client==='CodeBuddyIDE'&&payload.cwd==='/'?project:payload.cwd||project;
+}
+function handle(payload,options) {
+ assert.equal(payload.hook_event_name,options.event,'Hook event mismatch');
+ const project=safeProject(payload,options),record=C.select({project,product:options.product});
+ if(!record||record.base!==options.base)return {continue:true};
+ const cwd=toolCwd(payload,record,project);
+ // SessionStart and analysis do not create persistent per-project/session state.
+ if(['SessionStart','UserPromptSubmit'].includes(options.event))return {continue:true};
+ let source;
+ try {
+  source=eventSource(payload,record,project);
+ }catch(error){
+  const target=options.event==='PreToolUse'?prototypeForWrite(project,payload.tool_name,payload.tool_input):null;
+  if(target&&X.policy(target)&&G.uiWrite({name:payload.tool_name,input:payload.tool_input,cwd},target))return {deny:true,reason:`Native evidence unavailable for strict prototype UI write: ${error.message}`};
+  throw error;
+ }
+ const latest=source.prompts.at(-1);
+ if(C.readOnly(latest.text)) {
+  const native=nativeCommand(payload.tool_name,payload.tool_input,cwd),root=native?.root||prototypeForWrite(project,payload.tool_name,payload.tool_input);
+  if(options.event==='PreToolUse'&&(native&&['create','execution-begin','build','revise','replan','record-run','record-devtools-review','finalize'].includes(native.operation)||root&&X.policy(root)&&G.uiWrite({name:payload.tool_name,input:payload.tool_input,cwd},root)))return {deny:true,reason:'The latest user request is read-only or stopped; no prototype mutation is authorized.'};
+  return {continue:true};
+ }
+ const stateDirectory=C.sessionDirectory(record,project,payload.session_id),file=path.join(stateDirectory,'session.json');
+ const index=JSON.parse(C.read(file)||'{"schemaVersion":1,"bindings":{}}');assert.equal(index.schemaVersion,1,'Unsupported audit session state');
+ const command=nativeCommand(payload.tool_name,payload.tool_input,cwd);
+ if(options.event==='PreToolUse'&&command?.operation==='create'&&!command.argv.includes('--execution-policy')&&(E.loaded(source.calls,'prototype').some(c=>c.requestLine>source.contextLine)||/^\s*\/i3-prototype\b/.test(latest.text)))return {deny:true,reason:'New CodeBuddy prototypes require --host codebuddy --execution-policy codebuddy-ab-v1 and fixed --execution-assertions. Existing artifacts keep their original contracts.'};
+ const directory=command?.root||prototypeForWrite(project,payload.tool_name,payload.tool_input);
+ const existing=directory?index.bindings[directory]:null;
+ if(options.event==='PreToolUse'&&command?.operation==='execution-begin') {
+  assert.ok(directory&&directory.startsWith(path.join(project,'prototypes')+path.sep),'Prototype must be in this project');
+  const fixed=X.policy(directory);assert.ok(fixed,'Existing prototype retains its original contract; do not rewrite it implicitly');
+  const loaded=E.loaded(source.calls,'prototype').some(c=>c.requestLine>source.contextLine);
+  assert.ok(loaded||/^\s*\/i3-prototype\b/.test(latest.text),'Native prototype Skill or actual shortcut entry required');
+  const meta=F.json(path.join(directory,'prototype.json')),lib=require('./native-pilot-lib.cjs'),current=lib.manifest(directory);
+  const runId=existing&&existing.entryLine===latest.line&&existing.inputDigest===current.inputDigest&&existing.contextLine===source.contextLine?existing.runId:crypto.randomUUID();
+  index.bindings[directory]={schemaVersion:1,runId,sessionId:payload.session_id,project,projectKey:C.projectKey(project),directory,instanceId:meta.instanceId,policyDigest:fixed.digest,inputDigest:current.inputDigest,entryLine:latest.line,promptDigest:latest.digest,contextLine:source.contextLine,
+   operation:meta.revision==='r001'?'create':'revise',product:record.product,productVersion:record.productVersion,scope:record.scope,registrationDigest:record.registrationDigest,settingsDigest:record.settingsDigest,source:{path:source.path,bytes:source.bytes,digest:source.digest},lastHook:{event:options.event,at:new Date().toISOString(),nativeReadAttempts:source.nativeReadAttempts,nativeRequestStatus:source.nativeRequestStatus}};
+  const lock=path.join(stateDirectory,'.audit.lock');fs.mkdirSync(stateDirectory,{recursive:true});
+  try{fs.mkdirSync(lock);}catch{throw new Error('Concurrent audit callback; retry execution-begin');}
+  try {
+   const fresh=JSON.parse(C.read(file)||'{"schemaVersion":1,"bindings":{}}');fresh.bindings[directory]=index.bindings[directory];
+   saveIndex(stateDirectory,fresh);
+   F.write(directory,'qa/execution-context.json',{schemaVersion:1,runId,sessionId:payload.session_id,project,base:record.base,product:record.product});
+  }finally{fs.rmdirSync(lock);}
+  return {continue:true};
+ }
+ if(directory&&fs.existsSync(path.join(directory,'prototype.json'))&&X.policy(directory)) {
+  const answer=decision({event:options.event,source,binding:existing,tool:payload.tool_name,input:payload.tool_input,directory,cwd});if(answer.deny)return answer;
+  if(options.event==='PreToolUse'&&command&&['build','record-run','record-devtools-review','finalize'].includes(command.operation)&&!existing)return {deny:true,reason:'Begin this strict prototype run with execution-begin before implementation or delivery.'};
+ }
+ if(!Object.keys(index.bindings).length)return {continue:true};
+ const lock=path.join(stateDirectory,'.audit.lock');fs.mkdirSync(stateDirectory,{recursive:true});
+ try{fs.mkdirSync(lock);}catch(error){if(error.code==='EEXIST')throw new Error('Concurrent audit callback; no success evidence recorded. Retry the stage.');throw error;}
+ try {
+  const fresh=JSON.parse(C.read(file));let changed=false;
+  for(const entry of Object.values(fresh.bindings)) {
+   if(entry.entryLine!==latest.line)continue;
+   const eventKey=E.sha(JSON.stringify([options.event,payload.tool_use_id||null,payload.tool_name||null,payload.tool_input||null,source.digest]));
+   if(entry.lastEventKey===eventKey)continue;
+   entry.source={path:source.path,bytes:source.bytes,digest:source.digest};entry.lastEventKey=eventKey;entry.lastHook={event:options.event,at:new Date().toISOString(),nativeReadAttempts:source.nativeReadAttempts,nativeRequestStatus:source.nativeRequestStatus};changed=true;
+   if(options.event==='Stop') {
+    const lib=require('./native-pilot-lib.cjs'),state=lib.state(entry.directory);
+    const complete=state.execution.status==='passed'&&state.delivery?.status==='current'&&state.delivery.result.runId===entry.runId;
+    const feedback=decision({event:'Stop',source,binding:entry,directory:entry.directory,deliveryCurrent:complete,stopHookActive:payload.stop_hook_active||entry.stopFeedbackPrompt===latest.digest});
+    if(feedback.feedback){entry.stopFeedbackPrompt=latest.digest;saveIndex(stateDirectory,fresh);return feedback;}
+   }
+  }
+  if(changed)saveIndex(stateDirectory,fresh);
+ }finally{fs.rmdirSync(lock);}
+ return {continue:true};
+}
+module.exports={tokens,nativeCommand,eventCall,eventSource,decision,safeProject,toolCwd,handle};

package/skills/i3-ui-prototype/scripts/codebuddy-ide-source.cjs

@@ -0,0 +1,69 @@
+'use strict';
+// Observed CodeBuddy IDE history format: Hook-provided index.json and only the
+// UUID message files explicitly referenced by that index. No directory scan.
+const fs=require('node:fs'),path=require('node:path'),assert=require('node:assert/strict');
+const ID=/^[a-f0-9]{32}$/;
+const aliases={use_skill:'Skill',execute_command:'Bash',write_to_file:'Write',read_file:'Read',replace_in_file:'Edit'};
+function read(file) {
+ assert.equal(path.basename(file),'index.json','Expected native IDE index');
+ const directory=path.dirname(file),sessionId=path.basename(directory);
+ assert.match(sessionId,ID,'Invalid IDE session directory');
+ let total=0;
+ const load=target=>{
+  const stat=fs.lstatSync(target);assert.ok(stat.isFile()&&!stat.isSymbolicLink(),'Invalid IDE history file');
+  total+=stat.size;assert.ok(total<=64*1024*1024,'IDE history exceeds size limit');
+  return JSON.parse(fs.readFileSync(target,'utf8'));
+ };
+ const index=load(file);assert.ok(Array.isArray(index.messages)&&Array.isArray(index.requests),'Unsupported IDE index');
+ assert.ok(index.messages.length<=10000&&index.requests.length<=10000,'IDE history index exceeds limit');
+ const folder=path.join(directory,'messages');assert.ok(fs.lstatSync(folder).isDirectory()&&!fs.lstatSync(folder).isSymbolicLink(),'Invalid IDE message directory');
+ const requestIds=new Map(),seen=new Set(),events=[];let latestAssistant='',workspace;
+ for(const request of index.requests){
+  assert.match(request.id,ID,'Invalid IDE request ID');assert.ok(Array.isArray(request.messages),'Invalid IDE request messages');
+  for(const id of request.messages){assert.match(id,ID,'Invalid IDE message reference');assert.ok(!requestIds.has(id),'Duplicate IDE message request');requestIds.set(id,request.id);}
+ }
+ for(const item of index.messages){
+  assert.match(item.id,ID,'Invalid IDE message ID');assert.ok(!seen.has(item.id),'Duplicate IDE message ID');seen.add(item.id);
+  const row=load(path.join(folder,item.id+'.json'));
+  assert.equal(row.id,item.id,'IDE message identity differs');assert.equal(row.role,item.role,'IDE message role differs');
+  const message=JSON.parse(row.message),extra=JSON.parse(row.extra||'{}');
+  assert.equal(message.role,row.role,'IDE serialized message role differs');
+  assert.ok(requestIds.has(item.id),'Unbound IDE message');
+  // The index is the primary request membership. During execution the SDK can
+  // write message content before its duplicate extra.requestId metadata.
+  const requestId=requestIds.get(item.id);
+  if(extra.requestId!==undefined)assert.equal(extra.requestId,requestId,'IDE request identity differs');
+  assert.ok(Array.isArray(message.content),'Invalid IDE message content');
+  const base={sessionId,nativeMessageId:item.id,nativeRequestId:requestId};
+  if(row.role==='user'&&!extra.isHelperMessage){
+   const hostText=message.content[0]?.type==='text'?message.content[0].text:'';
+   const context=typeof hostText==='string'?hostText.match(/^<user_info>\s*([\s\S]*?)<\/user_info>/):null;
+   const nativeFolder=context?.[1].match(/^Workspace Folder:\s*(\/[^\r\n]+)$/m)?.[1]?.trim();
+   if(nativeFolder){
+    assert.ok(path.isAbsolute(nativeFolder)&&!/[\x00\r\n]/.test(nativeFolder),'Invalid native IDE workspace');
+    if(workspace)assert.equal(workspace,nativeFolder,'Native IDE workspace changed within one session');
+    workspace=nativeFolder;
+   }
+   assert.ok(Array.isArray(extra.sourceContentBlocks),'Original IDE user task is missing');
+   const text=extra.sourceContentBlocks.filter(b=>b.type==='text'&&typeof b.text==='string').map(b=>b.text).join('\n');
+   if(text.trim())events.push({...base,type:'user',message:{content:[{type:'text',text}]}});
+  }else if(row.role==='assistant'){
+   const text=message.content.filter(b=>b.type==='text').map(b=>b.text||'').join('\n');
+   if(text)latestAssistant=text;
+   for(const block of message.content.filter(b=>b.type==='tool-call')){
+    assert.ok(block.args&&typeof block.args==='object'&&!Array.isArray(block.args),'Invalid IDE tool arguments');
+    events.push({...base,type:'assistant',message:{content:[{type:'tool_use',id:block.toolCallId,name:aliases[block.toolName]||block.toolName,input:block.args}]}});
+   }
+  }else if(row.role==='tool'){
+   for(const block of message.content.filter(b=>b.type==='tool-result')){
+    const result=block.result,success=!block.isError&&result?.success===true&&result.status==='success';
+    events.push({...base,type:'user',message:{content:[{type:'tool_result',tool_use_id:block.toolCallId,
+     tool_name:aliases[block.toolName]||block.toolName,content:result,is_error:!success}]}});
+   }
+  }
+ }
+ // Only stable prompt/call/result facts form the prefix cursor. Streaming text,
+ // reasoning, request state and mutable toolStatus do not invalidate old facts.
+ return {text:events.map(row=>JSON.stringify(row)).join('\n')+'\n',latestAssistant,workspace,format:'codebuddy-ide-index-v1'};
+}
+module.exports={read};

package/skills/i3-ui-prototype/scripts/codebuddy-registration.cjs

@@ -0,0 +1,123 @@
+'use strict';
+// Pure configuration planning. This module does not install or activate a host.
+const assert = require('node:assert/strict');
+const path = require('node:path');
+const fs = require('node:fs');
+const crypto = require('node:crypto');
+const { digest } = require('./execution-policy.cjs');
+const OWNER = 'i3-prototype-codebuddy-v1';
+const EVENTS = ['SessionStart', 'UserPromptSubmit', 'PreToolUse', 'PostToolUse', 'Stop'];
+function quote(value) {
+  assert.ok(typeof value === 'string' && !/[\x00\r\n]/.test(value), 'Unsafe Hook argument');
+  return "'" + value.replaceAll("'", "'\\''") + "'";
+}
+function config(text) {
+  if (text === null) return {};
+  let value; try { value = JSON.parse(text); } catch { throw new Error('Settings must be valid JSON; preserve the original file'); }
+  assert.ok(value && !Array.isArray(value) && typeof value === 'object', 'Settings must be a JSON object');
+  assert.ok(!value.hooks || (typeof value.hooks === 'object' && !Array.isArray(value.hooks)), 'Invalid hooks configuration');
+  for (const groups of Object.values(value.hooks || {})) {
+    assert.ok(Array.isArray(groups), 'Hook groups must be arrays');
+    for (const group of groups) assert.ok(group && Array.isArray(group.hooks), 'Invalid Hook group');
+  }
+  return value;
+}
+function ownedMarker(group) { return group.hooks.some(hook => typeof hook.command === 'string' && hook.command.includes(OWNER)); }
+function plan(options) {
+  const { action = 'keep', scope, product, base, project, nodePath, scriptPath, scriptDigest, currentText = null, record = null,
+    transcriptRoots = record?.transcriptRoots || [], transcriptMode = record?.transcriptMode || (transcriptRoots.length ? 'manual' : 'auto'), productVersion = record?.productVersion || 'unreported' } = options;
+  assert.ok(['keep', 'enable', 'disable'].includes(action), 'Invalid Hook action');
+  assert.ok(['project', 'global'].includes(scope), 'Invalid installation scope');
+  assert.ok(['ide', 'cli'].includes(product), 'Specify CodeBuddy product ide or cli');
+  for (const item of [base, project, nodePath, scriptPath]) assert.ok(typeof item === 'string' && path.isAbsolute(item) && !/[\x00\r\n]/.test(item), 'Absolute safe registration paths required');
+  if (process.platform === 'win32') throw new Error('CodeBuddy A+B Windows Hook quoting is not yet verified');
+  const before = config(currentText), after = structuredClone(before), activeRecord = record && record.owner === OWNER ? record : null;
+  if (record) {
+    assert.ok(activeRecord && activeRecord.schemaVersion === 1, 'Unknown registration ownership');
+    assert.equal(activeRecord.scope, scope, 'Registration scope changed');
+    assert.equal(activeRecord.product, product, 'Disable the previous product profile before changing it');
+    assert.equal(activeRecord.base, base, 'Registration base changed');
+  }
+  const found = {};
+  for (const [event, groups] of Object.entries(after.hooks || {})) {
+    for (const group of groups.filter(ownedMarker)) {
+      assert.ok(activeRecord?.groups[event], 'Hook ownership is missing; do not adopt an unknown command');
+      assert.deepEqual(group, activeRecord.groups[event], 'Owned Hook was modified; preserve the user changes');
+      assert.ok(!found[event], 'Duplicate owned Hook registration'); found[event] = group;
+    }
+  }
+  if (activeRecord) for (const event of Object.keys(activeRecord.groups)) assert.ok(found[event], 'Owned Hook registration changed or is missing');
+  const unchanged = action === 'keep' && !activeRecord;
+  let recordAfter = null;
+  if (!unchanged) {
+    after.hooks ||= {};
+    for (const event of Object.keys(found)) after.hooks[event] = after.hooks[event].filter(group => group !== found[event]);
+    if (action !== 'disable') {
+      assert.match(scriptDigest || '', /^[a-f0-9]{64}$/, 'Hook script digest required');
+      const groups = {};
+      for (const event of EVENTS) {
+        const argv = [nodePath, scriptPath, '--registration', OWNER, '--base', base, '--scope', scope, '--product', product, '--event', event];
+        const group = { ...(event.endsWith('ToolUse') ? { matcher: '' } : {}), hooks: [{ type: 'command', command: argv.map(quote).join(' '), timeout: 10 }] };
+        groups[event] = group; (after.hooks[event] ||= []).push(group);
+      }
+      assert.ok(Array.isArray(transcriptRoots)&&transcriptRoots.every(root=>typeof root==='string'&&path.isAbsolute(root)&&!/[\x00\r\n]/.test(root)),'Absolute native transcript roots required');
+      assert.ok(['auto','manual'].includes(transcriptMode),'Invalid native transcript mode');
+      assert.ok(transcriptMode==='manual'?transcriptRoots.length>0:transcriptRoots.length===0,'Manual transcript mode requires roots; auto uses only the native callback file');
+      recordAfter = { schemaVersion: 1, owner: OWNER, scope, product, base, scriptPath, scriptDigest, nodePath, groups, transcriptMode, transcriptRoots, productVersion };
+    }
+  }
+  const afterText = unchanged ? currentText : JSON.stringify(after, null, 2) + '\n';
+  return { action, scope, product, base, project, settingsPath: path.join(base, 'settings.json'),
+    recordPath: path.join(base, 'state/i3-prototype/installation.json'), beforeDigest: digest(currentText), beforeRecordDigest: digest(record), afterText, recordAfter,
+    summary: { status: unchanged || action === 'disable' ? 'not-enabled' : product === 'cli' ? 'pending-host-review' : 'registered',
+      ...(recordAfter?{transcript:{mode:transcriptMode,status:'awaiting-native-event',invocationVerified:false}}:{}),
+      scope, product, settingsPath: path.join(base, 'settings.json'), events: recordAfter ? EVENTS : [], changed: afterText !== currentText || digest(recordAfter)!==digest(record),
+      next: product === 'cli' && recordAfter ? 'Review the external settings change in CodeBuddy /hooks; then start a new session.' : 'Actual Hook invocation must be checked in the host; registration is not activation.' } };
+}
+function safePath(file) {
+  let current = path.parse(path.resolve(file)).root;
+  for (const part of path.resolve(file).slice(current.length).split(path.sep)) {
+    current = path.join(current, part);
+    if (fs.existsSync(current)) assert.ok(!fs.lstatSync(current).isSymbolicLink(), 'Hook settings symlink refused');
+  }
+}
+const fileIO = {
+  lock(file) {safePath(file);fs.mkdirSync(path.dirname(file),{recursive:true});const lock=file+'.i3-prototype.lock';try{fs.mkdirSync(lock);}catch{throw new Error('Hook configuration is being updated; retry without overwriting the other change');}return ()=>fs.rmdirSync(lock);},
+  read(file) {
+    safePath(file); if (!fs.existsSync(file)) return null;
+    assert.ok(fs.statSync(file).isFile() && fs.statSync(file).size <= 4 * 1024 * 1024, 'Invalid or oversized Hook configuration');
+    return fs.readFileSync(file, 'utf8');
+  },
+  write(file, text, expected) {
+    assert.equal(digest(this.read(file)), expected, 'Hook configuration changed concurrently');
+    if (text === null) { if (fs.existsSync(file)) fs.unlinkSync(file); return; }
+    fs.mkdirSync(path.dirname(file), { recursive: true }); safePath(file);
+    const staging = file + '.' + crypto.randomUUID() + '.new';
+    try {
+      fs.writeFileSync(staging, text, { flag: 'wx', mode: fs.existsSync(file) ? fs.statSync(file).mode & 0o777 : 0o600 });
+      assert.equal(digest(this.read(file)), expected, 'Hook configuration changed before publication');
+      fs.renameSync(staging, file);
+    } finally { if (fs.existsSync(staging)) fs.unlinkSync(staging); }
+  },
+};
+function apply(change, io = fileIO) {
+  const unlock=io.lock?io.lock(change.settingsPath):()=>{};
+  try {return applyLocked(change,io);}finally{unlock();}
+}
+function applyLocked(change, io) {
+  const before = io.read(change.settingsPath), recordBefore = io.read(change.recordPath);
+  assert.equal(digest(before), change.beforeDigest, 'Hook configuration changed after preview');
+  assert.equal(digest(recordBefore === null ? null : JSON.parse(recordBefore)), change.beforeRecordDigest, 'Hook ownership changed after preview');
+  const recordAfter = change.recordAfter ? JSON.stringify(change.recordAfter, null, 2) + '\n' : null;
+  if (change.afterText === before && recordAfter === recordBefore) return change.summary;
+  let settingsWritten = false;
+  try {
+    if (change.afterText !== before) { io.write(change.settingsPath, change.afterText, digest(before)); settingsWritten = true; }
+    if (recordAfter !== recordBefore) io.write(change.recordPath, recordAfter, digest(recordBefore));
+  } catch (error) {
+    if (settingsWritten && io.read(change.settingsPath) === change.afterText) io.write(change.settingsPath, before, digest(change.afterText));
+    throw error;
+  }
+  return change.summary;
+}
+module.exports = { OWNER, EVENTS, quote, config, plan, apply, fileIO };