lime-quality-workflow

# Lime 工程质量

先读取 `internal/aiprompts/quality-workflow.md`（仓库事实源）。
如果需要快速找入口，再看 `internal/aiprompts/README.md`。

如果任务涉及：

- Electron IPC / App Server / legacy desktop facade / Bridge / mock / 前端 API 网关：再读 `internal/aiprompts/commands.md`
- 新旧并存、兼容层收口、旧入口回流：再读 `internal/aiprompts/governance.md`
- GUI 续测、页面交互验证：再读 `internal/aiprompts/playwright-e2e.md`

如果当前任务本身是在更新工程质量规则，先改仓库里的 `internal/aiprompts/quality-workflow.md`，再视需要同步本 skill 的参考文件。

## Fast Path

用户问“结论 / 复核 / 是否能删 / 是否 dead”时，先用 `3-8` 行给结论和关键证据；不要自动升级成 `verify:local`、`test:contracts`、GUI smoke 或全量质量矩阵。只有用户要求继续实现、修文档、补守卫、提交前验证，或改动已经真实触达 GUI / 命令 / bridge / 配置边界时，才进入完整质量工作流。

目录级旧实现若已脱离构建 / workspace manifest、当前工作树已物理删除或 staged delete、已有 current owner 承接，且边界守卫能防回流，可直接按目录级 `dead / deleted / forbidden-to-restore` 判定；不要求逐文件证明业务语义无价值。`internal/exec-plans/**`、旧路线图和 git history 里的旧路径默认是历史 evidence，不是当前质量缺口。

## 何时使用

当任务涉及以下任一问题时，使用本 skill：

- 不确定这次改动最少该跑哪些校验
- 改了 GUI 壳、DevBridge、Workspace、前端主路径
- 改了 Electron IPC、App Server JSON-RPC、legacy desktop facade、Bridge、mock、`safeInvoke` / `invoke`
- 改了配置结构、版本文件、依赖或发布相关边界
- 需要判断“代码通过检查”是否已经等于“可以交付”

## Codex 工作流

### 0. 路线图任务先校准目标

如果用户明确要求对齐路线图主线，先在脑内完成这三个判断，再决定跑什么校验：

1. 本轮改动对应路线图哪一节
2. 它推进的是主链，还是只是从属清理
3. 本轮最低门槛校验是否能证明这一步真的在向目标收敛

如果答案只是“代码没报错”，但无法证明主线前进了，就要先纠偏，再谈校验。

如果当前改动只是让已经过时、且明确无需兼容的旧实现继续通过校验，不要把这轮验证当成有效进展；应先回到主线，删除或下线旧实现后再验证 current 路径。

校验前同时检查新增命名：新程序、目录、crate/package、命令、API 网关、类型、模块和脚本默认不得添加 `Lime` / `lime_` / `lime-` 品牌前缀；除非属于历史兼容、对外品牌标识或外部生态固定名，并已在计划中说明。

如果新增的是 AI Agent / runtime / host integration / 跨 App 复用能力，质量检查还必须确认它走 App Server JSON-RPC current 主链；Electron 只能作为 Desktop Host bridge；`agent_runtime_*` 只能作为 retired guard / 历史 evidence，已删除 runtime 不能恢复为兼容 facade 或新业务逻辑事实源。

质量检查还必须确认生产路径没有 mock fallback。`safeInvoke` / `invoke`、Electron Host、App Server sidecar、GUI smoke 和业务 E2E 不能回退 `mockPriorityCommands`、`defaultMocks`、`invokeMockOnly`、renderer mock fallback 或 mock backend；这些只允许测试夹具显式使用。

如果本轮涉及 Agent Runtime / Claw chat 主路径、历史恢复、流式事件、工具终态、消息列表完成态、代码产物工作台或 Plugin task read model，进入 GUI smoke / Playwright 前先跑 `npm run smoke:agent-runtime-current-fixture`。该入口必须保持非 live Provider、非 App Server mock backend、非 renderer mock fallback，只作为 current fixture 回归门槛，不替代真实 Electron / Playwright 闭环。修 streaming 卡住、无法停止、输入框不可用、用户消息 / assistant 输出不可见时，terminal 回归必须覆盖 App Server current `turn.completed` 投影后的 `turn_completed`，不能靠固定 timeout / grace timer 合成 `final_done`。若问题直接涉及历史详情 hydrate、最近对话恢复或归档 / 反归档后的 read model 读取，聚合 guard 通过后再显式跑 `npm run smoke:agent-session-history-electron-fixture`；该入口启动真实 Electron，但使用 `APP_SERVER_BACKEND_MODE=unavailable`，不调用模型后端。若问题直接涉及代码产物、artifact snapshot、从历史打开工作台或工作台面板渲染，聚合 guard 通过后再显式跑 `npm run smoke:code-artifact-workbench-electron-fixture`；该入口启动真实 Electron 并使用 external fixture backend，不调用正式模型。若问题直接涉及 Claw 输入框不可见、用户输入不显示、assistant 输出卡住、自然语言新闻请求或 `agentSession/turn/start` GUI 链路，聚合 guard 通过后再显式跑 `npm run smoke:claw-chat-current-fixture`；该入口启动真实 Electron 但仍使用 external fixture backend，不调用正式模型，且应覆盖 `message.delta + turn.completed` 单终态完成态，不要求 `turn.final_done`。

如果涉及 Electron packaging / installer / signing / notarization / updater metadata，质量检查必须确认 current 事实源是 `forge.config.mjs`、`electron-forge package`、`electron-forge make` 与 Forge 官方 maker；旧 builder 配置 / CLI、自定义 Windows installer maker 与旧 YAML / blockmap updater metadata 按 `dead` 处理，不得继续作为文档、CI、质量任务、i18n evidence 或守卫输入。运行时更新以 `electron/updateHost.ts` + Electron 内置 `autoUpdater` 为 current；Windows installer 必须走 Forge Squirrel。

如果涉及新增脚本或 `scripts/` 目录治理，质量检查必须确认 `scripts/` 根目录和一级领域目录没有继续膨胀。新增可执行脚本默认进入已有 `scripts/<domain>/`、`scripts/lib/` 或所属 package；根目录或新领域目录例外必须同步 `scripts/README.md`、`scripts/script-root-governance-baseline.json` 和执行计划。最低校验包含 `npm run governance:scripts`。

如果本轮要继续前端全量 Vitest，先检查 `.lime/test/vitest-smart-last-run.json`。已有失败、中断、running 或 pending 批次时，默认用 `npm run test:resume`，或用 `npm test -- --from-batch <N>` / `npm test -- --only-batch <N>` 精确补批次；不要无理由从第 1 批重跑。局部源码改动优先用 `npm run test:related -- <files>` 或 `npm run test:changed -- <ref>` 缩小反馈环，再按发布 / GUI 风险决定是否扩大验证。CI 横向压缩前端全量时可用 Vitest `--shard=<index>/<count>` 做分片；本地失败续跑仍以 `.lime/test/` 状态为准。

### 1. 先判断改动类型

先把当前改动归到最接近的一类：

- 普通前端改动
- Electron IPC / App Server / legacy desktop facade / Bridge / mock 改动
- GUI 壳 / Workspace / 页面主路径改动
- 配置结构改动
- 版本相关改动
- Rust 模块改动
- 需要真实交互验证的 GUI 改动

如果改动同时落在多类，按最高风险边界组合校验，不要只跑最轻的一层。

### 2. 先跑最贴边界的最低门槛

默认参考仓库里的最低门槛矩阵：

- 普通前端改动：`npm run verify:local`
- Electron IPC / App Server / legacy desktop facade / Bridge / mock 改动：`npm run verify:local` + `npm run test:contracts`
- GUI 壳 / Workspace / 页面主路径改动：`npm run verify:local` + `npm run verify:gui-smoke`
- Agent Runtime / Claw chat 主路径改动：先跑 `npm run smoke:agent-runtime-current-fixture`，再按 GUI / bridge 风险补 `verify:gui-smoke`、`test:contracts` 或 Playwright
- 配置结构改动：`npm run verify:local`
- 版本相关改动：`npm run verify:app-version`
- Rust 模块改动：先跑受影响 crate / 模块定向测试，再决定是否全量 `cargo test`
- 真实交互验证：先跑 `npm run verify:gui-smoke`，再进入 Playwright MCP

### 3. GUI 产品不要只看“代码通过”

如果改动影响 GUI 壳、Bridge、Workspace、主页面路径，不要把以下结果当成交付结论：

- `lint` 通过
- `typecheck` 通过
- 前端单测通过
- Rust 单测通过

至少还要确认：

- `DevBridge` 已就绪
- 默认 workspace 准备态可用
- 最小 GUI smoke 已跑通或明确说明为什么当前环境不能跑

### 4. 边界类改动必须成组检查

如果改动涉及命令、桥接、配置、版本或依赖，至少检查这些成组事项有没有同步：

- 命令边界：前端调用、Electron host / preload、App Server protocol / client、legacy Rust 注册、治理目录册、mock 集合
- 配置结构：schema、校验器、消费者、文档
- 版本相关：`package.json`、Electron 配置、`lime-rs/Cargo.toml`、App Server manifest
- 依赖相关：`package-lock.json`、`lime-rs/Cargo.lock`

Electron packaging / release 相关改动还必须成组检查：`forge.config.mjs`、`electron/forge/*`、`package.json` / `package-lock.json`、release workflows、`scripts/run-electron-package-dir.mjs`、`scripts/stage-electron-release-assets.mjs`、`scripts/verify-electron-package-resources.mjs`、entrypoint/docs guards、contract guard 和 `internal/roadmap/appserver/release-updater.md`。

脚本目录治理相关改动还必须成组检查：`scripts/README.md`、`scripts/script-root-governance-baseline.json`、`scripts/check-scripts-governance.mjs`、`scripts/lib/scripts-governance-core.mjs` 与 `package.json#scripts`，并运行