docs: classify architecture invariants by enforcement mechanism (#9152)

[yiliang114]

What this PR does

Adds docs/design/9152-architecture-invariant-classification.md — a canonical record classifying every architectural invariant in the repository by its enforcement mechanism: which invariants are enforced mechanically (custom ESLint rules, source-level boundary tests, drift-detection tests, tsconfig.json strict mode, package.json engines field), which are left to review, and which are not worth enforcing. It covers every convention asserted in AGENTS.md (ESM, strict mode, Prettier, no any, kebab-case filenames, collocated tests, Conventional Commits, Node ≥22, core module two-tier gate) and every invariant from open architecture issues (#8084, #9145, #9146, #9151, #4063). It also records the drift-guard decision: do not extract a reusable framework from check-voice-guard-sync.js — the two existing drift guards (cross-package-contracts.test.js from #9151 and approval-mode-drift.test.ts from #9145) share a pattern but not enough structure to justify a shared abstraction, so the copy-the-structure policy is documented instead, with an explicit trigger (a fourth case) for revisiting it.

Why it's needed

Issue #9152 asks for a policy decision so that a new invariant encounters an existing answer instead of being handled case by case. The repository already enforces invariants in four places, each invented independently; this PR writes down the classification so the next invariant lands in the right category by default.

Reviewer Test Plan

How to verify

Static documentation only — no code, build, or test changes. Cross-reference each guard named in the document against the current main branch state and open PR status; confirm the classification categories (mechanical vs review vs not worth enforcing) match the actual enforcement mechanism for each listed invariant.

Evidence (Before & After)

N/A (documentation-only change)

Tested on

OS	Status
🍏 macOS	⚠️
🪟 Windows	⚠️
🐧 Linux	✅

Environment (optional)

N/A — documentation only, verified against main branch sources and open issue/PR state.

Risk & Scope

• Main risk or tradeoff: the classification is a policy document; where it disagrees with a future maintainer ruling, the ruling wins and the doc should be updated.
• Not validated / out of scope: no mechanical enforcement is added or changed; the open actions table only tracks existing issues/PRs.
• Breaking changes / migration notes: none — docs-only.

Linked Issues

Closes #9152

Related (tracked, not closed): #8084, #9145, #9146, #9151, #4063

中文说明

这个 PR 做了什么

新增 docs/design/9152-architecture-invariant-classification.md——一份权威记录，把仓库里每条架构不变量按其执行机制分类：哪些由机械手段强制执行（自定义 ESLint 规则、源码级边界测试、漂移检测测试、tsconfig.json strict 模式、package.json engines 字段），哪些交给 review 把关，哪些不值得强制。它覆盖 AGENTS.md 中断言的所有约定（ESM、strict 模式、Prettier、禁用 any、kebab-case 文件名、测试就近放置、Conventional Commits、Node ≥22、core 模块两层门禁），以及所有开放架构 issue（#8084、#9145、#9146、#9151、#4063）中的不变量。同时记录了 drift-guard 决策：不从 check-voice-guard-sync.js 抽取可复用框架——现有两个 drift guard（#9151 的 cross-package-contracts.test.js 和 #9145 的 approval-mode-drift.test.ts）有共同模式，但结构上不足以支撑共享抽象，因此改为记录「复制现有结构」的策略，并给出明确的重新评估触发条件（出现第四个案例）。

为什么需要

Issue #9152 要求一个策略决策：让新出现的不变量直接对号入座，而不是逐案处理。仓库已经在四个地方各自独立地强制执行不变量；本 PR 把分类写下来，让下一条不变量默认落到正确的类别里。

Reviewer 测试计划

如何验证

纯静态文档——没有代码、构建或测试改动。将文档中列出的每个 guard 与当前 main 分支状态及开放 PR 状态交叉核对；确认分类类别（机械强制 / review 把关 / 不值得强制）与每条不变量的实际执行机制一致。

证据（Before & After）

N/A（纯文档改动）

测试环境

OS	状态
🍏 macOS	⚠️
🪟 Windows	⚠️
🐧 Linux	✅

环境（可选）

N/A——纯文档，基于 main 分支源码与 issue/PR 状态验证。

风险与范围

• 主要风险或权衡：分类是策略文档；若与后续 maintainer 裁定冲突，以裁定为准并更新文档。
• 未验证 / 超出范围：不新增或修改任何机械强制手段；开放动作表仅跟踪现有 issue/PR。
• 破坏性变更 / 迁移说明：无——纯文档。

关联 Issue

Closes #9152

相关（仅跟踪，不关闭）：#8084、#9145、#9146、#9151、#4063

[qwen-code-ci-bot]

✅ Qwen Triage finished — view run. See the stage comments in this thread for the result.

✅ Qwen Triage 已完成 —— 查看运行。结果见本线程中的各阶段评论。

[qwen-code-ci-bot]

@yiliang114 The PR body doesn't follow the repository's pull request template — none of the required sections (What this PR does, Why it's needed, Reviewer Test Plan, Risk & Scope, Linked Issues) are present, and the bilingual Chinese <details> section is missing too. The substance is largely already written (Motivation, Changes, Drift-guard decision, Verification, Closes #9152), so this should be a reformat rather than new work: please restructure the body along .github/pull_request_template.md. For a docs-only change, Evidence (Before & After) can be N/A and the Tested-on table is a one-liner.

This is a formatting gate, not a judgement on the content — the review stops here and picks back up once the body follows the template. Re-running @qwen-code /triage after the update will continue it.

中文说明

@yiliang114 PR 正文没有使用仓库的 pull request 模板——必需章节（What this PR does、Why it's needed、Reviewer Test Plan、Risk & Scope、Linked Issues）均缺失，双语中文 <details> 部分也不存在。内容本身基本已经写好（Motivation、Changes、Drift-guard decision、Verification、Closes #9152），所以这应该只是一次重排，而不是补写新内容：请按 .github/pull_request_template.md 重组正文。纯文档改动的 Evidence (Before & After) 可以写 N/A，Tested-on 表格一行即可。

这是格式门槛，不是对内容的否定——审查在此停下，正文符合模板后继续。更新后 re-run @qwen-code /triage 即可恢复审查。

— Qwen Code · qwen3.8-max

[qwen-code-ci-bot]

📄 Docs-only change — the automatic review ran at --effort medium (verified findings, no reverse audit; medium posts no inline comments). Outcome:

Review complete: pr-9689 — Request changes, not posted (2 Critical, 6 Suggestion)

Reviewed head: 951b4b9733fed1671be3e5b3c0a9994a04569dc5. Full report in the workflow run. For a full high-effort review with inline comments, comment @qwen-code /review.

中文说明

📄 纯文档变更 —— 自动评审以 --effort medium 运行（发现已验证、无反向审计；medium 不发布行内评论），结果见上方引用行。评审的 head：951b4b9733fed1671be3e5b3c0a9994a04569dc5。完整报告见 workflow 运行；如需带行内评论的完整高强度（high-effort）评审，请评论 @qwen-code /review。

[yiliang114]

@qwen-code /triage

[qwen-code-ci-bot]

Sandboxed verification: ⚠️ not run — n/a - workflow run

This PR changes documentation/assets only — there is no code to execute, so a sandboxed verification has nothing to verify.

中文 — 判定：⚠️ 未运行 · 不适用

该 PR 仅改动文档/静态资源，没有可执行的代码，沙箱验证没有验证对象。

— Qwen Code · sandboxed verification

[qwen-code-ci-bot]

Round-6 re-run — new commit a5670f39 landed since the last pass, addressing both round-5 findings. Gate still passes, unchanged:

• Template: complete — all required sections plus the bilingual <details> are present.
• Problem: real. Architectural invariants are enforced ad hoc: four mechanical guards exist, everything agreed since lives in prose #9152 is open and asks for exactly this record; the refactor(cli): remove ACP integration dependencies on serve internals #8084 invariant being agreed, implemented, then silently reintroduced is the observed failure behind it.
• Direction: aligned — this is the policy answer the issue requested. Docs-only, no code paths touched.
• Size: N/A (single doc file, +316/-0, no core paths).
• Approach: scope is right — one record, one classification per invariant, gap tracking, and the drift-guard decision. The new commit carries exactly the two fixes it claims plus Prettier markdown normalization; I diffed both versions to confirm nothing else moved.
• Risk: no elevated risk signals (docs/design only, no high-risk paths).

Moving on to verifying the fixes. 🔍

中文说明

第六轮 re-run——自上轮以来新增提交 a5670f39，处理了第五轮的两个发现。门禁结论依旧不变：

• 模板： 完整——所有必需章节及双语 <details> 均在。
• 问题： 真实存在。Architectural invariants are enforced ad hoc: four mechanical guards exist, everything agreed since lives in prose #9152 仍然开放，要求的正是这份记录；refactor(cli): remove ACP integration dependencies on serve internals #8084 的不变量被达成一致、实现、又被悄悄重新引入，是其背后的已观测失败。
• 方向： 对齐——这正是 issue 要求的政策答案。纯文档，不触及代码路径。
• 规模： 不适用（单个文档文件，+316/-0，不涉及核心路径）。
• 方案： 范围合理——一份记录、每条不变量一个分类、缺口跟踪，外加 drift-guard 决策。新提交恰好只含其声称的两处修复加 Prettier markdown 规范化；我对比了前后两个版本，确认没有其他改动。
• 风险： 无升级风险信号（仅 docs/design，无高风险路径）。

继续验证这两处修复。🔍

— Qwen Code · qwen3.8-max

_{Reviewed at a5670f397763ca287351c27e68d74290ecb710fb · re-run with @qwen-code /triage}

[qwen-code-ci-bot]

Code review

Round 6 — new head a5670f39 since round 5, so this pass reviews the delta rather than re-covering the unchanged text (which rounds 4–5 verified claim-by-claim). I diffed the document at 951b4b97 against a5670f39 and read the new wording against the primary sources:

The blocking #9145 clause is fixed, exactly as prescribed. The sentence no longer attributes any desktop drift to the issue. It now reads: "the issue identifies drift in the Python and Java SDKs, which PR #9003 (in progress) addresses. The remaining item worth naming is desktop's cyclablePermissionModes — an intentionally different domain…" I checked this against #9145 itself: the issue body's confirmed-drift table does name the Python (sdk-python/.../types.py, missing auto) and Java (PermissionMode.java, missing auto) copies, and the body contains zero desktop or cyclablePermissionModes mentions. #9003's body confirms it fixes both SDKs in one pass. The paragraph's self-contradiction is gone — desktop is now presented as a domain the drift test intentionally does not (and should not) cover, which matches reality: desktop's cyclablePermissionModes is allow-all/safe/ask/auto-edit in packages/desktop/apps/electron/resources/config-defaults.json, disjoint from core's domain.

The line-count nit is fixed too. "each 40-60 lines" → "114 and 44 lines of table-driven test code respectively" — re-verified against main: scripts/tests/cross-package-contracts.test.js is 114 lines, packages/sdk-typescript/test/unit/approval-mode-drift.test.ts is 44.

The rest of the commit is Prettier normalization, as claimed. The full diff between the two versions contains only: table column alignment (classification scheme + summary tables), blank lines inserted before three bullet lists, and *pattern* → _pattern_ emphasis markers. No other semantic changes anywhere, including after the Open actions heading.

Fresh spot checks this pass (worktree at main, live API state — not taken from round 5's notes): the drift test has zero desktop/cyclablePermissionModes references ✓; no-core-root-barrel-import.js absent from main with #8139 and #9635 both open ✓; engines >=22.0.0 ✓; tsconfig.json carries strict, noImplicitAny, strictNullChecks, noUnusedLocals, verbatimModuleSyntax ✓; lint-staged runs prettier --write with a .husky/pre-commit hook ✓.

No new findings. The unchanged remainder stands on rounds 4–5's verification, which this round's diff confirms is untouched.

Test evidence

Docs-only change; CI on a5670f39 has settled — both pull_request workflow runs (Qwen Code CI, Security Checks) completed green, and everything else is green or skipped by design under the docs-only profile. No failures. The only in-flight run is the bot's own pull_request_target review job, which is not the PR's CI.

Check	Conclusion
Qwen Code CI (pull_request run)	✅ success
Security Checks (pull_request run)	✅ success
Test (ubuntu-latest, Node 22.x)	✅ success
Desktop Shell (ubuntu-22.04 / windows-2022)	✅ success
Secret scan (TruffleHog)	✅ success
Dependency CVE audit	✅ success
Test (macos/windows), Integration Tests (CLI), web-shell E2E Smoke, Coverage	⏭️ skipped (docs-only profile)

Real-scenario testing: N/A — documentation-only change, nothing user-visible to drive.

中文说明

第六轮——head 自第五轮起更新为 a5670f39，本轮审查增量，而非重复覆盖未变动的文本（那部分已在第四、五轮逐条核验）。我对比了 951b4b97 与 a5670f39 两个版本的文档，并对照一手来源审读了新措辞：

阻断性的 #9145 从句已按处方修复。 该句不再把任何 desktop 漂移归于该 issue，现在写作"该 issue 指出了 Python 与 Java SDK 的漂移，PR #9003（进行中）正在处理。剩下值得点名的是 desktop 的 cyclablePermissionModes——一个有意不同的域……"。我对照 #9145 本身核实：issue 正文的确认漂移表确实点名了 Python（types.py 缺 auto）与 Java（PermissionMode.java 缺 auto）两份拷贝，且正文没有任何 desktop 或 cyclablePermissionModes 的提及；#9003 的正文确认它一并修复两个 SDK。段落的自相矛盾已消除——desktop 现在被表述为漂移测试有意不覆盖（也不应覆盖）的域，与事实一致：config-defaults.json 中 desktop 的 cyclablePermissionModes 为 allow-all/safe/ask/auto-edit，与 core 域不相交。

行数小问题也已修复。 "各 40-60 行" → "分别为 114 与 44 行"——对照 main 复核：cross-package-contracts.test.js 114 行、approval-mode-drift.test.ts 44 行。

提交其余部分确为 Prettier 规范化。 两个版本的完整 diff 仅含：表格列对齐、三处列表前补空行、*pattern* → _pattern_ 强调符；包括 Open actions 一节在内没有任何其他语义改动。

本轮新做的抽查（worktree 在 main、API 实时状态——未沿用第五轮结论）：漂移测试零处 desktop/cyclablePermissionModes 引用 ✓；no-core-root-barrel-import.js 不在 main、#8139/#9635 均开放 ✓；engines >=22.0.0 ✓；tsconfig 五个严格标志 ✓；lint-staged 运行 prettier --write 且有 .husky/pre-commit ✓。

无新发现。未变动部分以第四、五轮的核验为准，本轮 diff 确认其原封未动。

测试证据：纯文档改动，a5670f39 的 CI 已落定——两个 pull_request 工作流（Qwen Code CI、Security Checks）均为绿，其余非绿即按文档画像设计跳过，无失败；唯一在跑的是机器人自己的 pull_request_target 审查任务，不属于 PR 自身 CI。真实场景测试：N/A——纯文档，无用户可见行为可驱动。

— Qwen Code · qwen3.8-max

_{Reviewed at a5670f397763ca287351c27e68d74290ecb710fb · re-run with @qwen-code /triage}

[qwen-code-ci-bot]

Confidence: 5/5 — the one blocking clause is fixed and verified against the primary source, the nit is fixed too, and nothing else moved.

Stepping back: five rounds in, this document had earned every approval except one sentence — the #9145 attribution. @yiliang114 fixed exactly that sentence (and the line-count nit), and this pass I checked the fix against the issue itself rather than the closeout note: #9145's body identifies Python and Java drift and never touches desktop, which is precisely what the reworded paragraph now says. The version diff also confirms the commit carries nothing besides the two fixes and Prettier normalization.

What I'm approving: a single 316-line design document that classifies the repo's invariants by enforcement mechanism, tracks the open gaps honestly (❌/⚠️ rows included, not papered over), and records the drift-guard "copy the structure" decision with a concrete revisit trigger. That is what #9152 asked for — no more, no less. If I'm maintaining this in six months, the summary table plus the open-actions list is exactly the shape I'd want. CI on a5670f39 is green for everything that runs under the docs-only profile.

The two standing request-changes reviews are superseded by this approval. Approving now, pinned to the reviewed commit. ✅

中文说明

置信度：5/5 —— 唯一的阻断从句已修复并经一手来源核实，行数小问题也已修复，别无其他改动。

退一步看：五轮下来，这份文档除了那一句 #9145 归属之外已配得上任何批准。作者精确地修复了该句（连带行数小问题），本轮我直接对照 issue 本身而非其总结评论核验：#9145 正文指出的是 Python 与 Java 的漂移、完全不涉及 desktop——改写后的段落所说的正是这一点。版本 diff 同时确认该提交除两处修复与 Prettier 规范化外别无其他内容。

我批准的是这样一份 316 行的设计文档：按执行机制给仓库不变量分类，诚实跟踪开放缺口（❌/⚠️ 行原样保留、不加粉饰），并记录了 drift-guard"复制现有结构"的决策与具体的重新评估触发条件。这正是 #9152 要求的——不多不少。若六个月后由我维护，摘要表加开放动作清单也正是我想要的形态。a5670f39 上文档画像内运行的 CI 全部为绿。

两条在案的 request-changes 审查由本次批准取代。现在批准，钉在所审提交上。✅

— Qwen Code · qwen3.8-max

_{Reviewed at a5670f397763ca287351c27e68d74290ecb710fb · re-run with @qwen-code /triage}

[qwen-code-ci-bot]

Two factual errors block this as a canonical record, @yiliang114 — full detail in my stage-2 comment above:

1. The lane4-rebase branch does not exist in this repository (404). The no-core-root-barrel-import.js rule lives in open PRs #8139 (lane3-core-root-barrel) and #9635 (codex/pr-9152-root-barrel-cleanup) — point the #4063-item-5 section and open action 2 at the PR(s) instead.
2. approval-mode-drift.test.ts does not "explicitly exclude" desktop's cyclablePermissionModes — it never mentions desktop; it simply asserts SDK ↔ core sequence equality. Reword to "does not cover desktop" (the conclusion "no further guard needed" can stay if that's the intended call).

While you're in there: #9152's own table lists scripts/check-desktop-isolation.js as one of the four existing mechanical guards, and the two daemon-route review invariants from AGENTS.md's Code Review section — none of the three are classified here despite the "every invariant asserted in AGENTS.md or an open architecture issue" claim.

Everything else I verified holds up (guard configs, issue/PR statuses, the drift-guard decision), CI is green on the reviewed commit, and the fixes are small — expecting this to land quickly after. 🙏

[yiliang114]

Closeout for the CHANGES_REQUESTED review — all findings addressed in 951b4b9. Every corrected claim was re-verified against origin/main or live GitHub state before writing; all review claims checked out.

Blocking

1. lane4-rebase → the PRs that actually carry the rule. Reworded the refactor: core + cli 架构 Review — 12 项结构性问题清单 #4063-item-5 section, summary-table row, and open action 2 to point at open PRs refactor(core): enforce internal root-barrel boundary #8139 / refactor(core): remove root barrel self-imports and enforce the boundary #9635. Verified: branches API returns 404 for lane4-rebase (branch and file-at-ref); lane3-core-root-barrel and codex/pr-9152-root-barrel-cleanup exist and both contain eslint-rules/no-core-root-barrel-import.js (contents API at each ref); the file is absent from origin/main; refactor(core): enforce internal root-barrel boundary #8139 and refactor(core): remove root barrel self-imports and enforce the boundary #9635 are both open.
2. Approval-mode drift test "explicitly excludes" → "does not cover". Reworded the The approval-mode value domain is hand-copied into 20 files across 3 languages; two copies are already wrong #9145 section to say the test asserts DAEMON_APPROVAL_MODES is sequence-equal to core's APPROVAL_MODES and never mentions desktop; the "no further guard needed for desktop" conclusion stands. Verified: read packages/sdk-typescript/test/unit/approval-mode-drift.test.ts on origin/main — single toEqual assertion, no desktop/cyclablePermissionModes reference.

Coverage gap — added all three missing items in the document's existing style:

3. scripts/check-desktop-isolation.js: new ### #9152: the excluded desktop workspace stays excluded entry + summary row, classified Mechanically enforced / no gap. Verified: script exists on origin/main (read it — fails if desktop workspaces re-enter the root npm workspace set, lockfile, or root node_modules with desktop-only deps) and CI runs it via npm run check:desktop-isolation (Check desktop workspace isolation step in .github/workflows/ci.yml).
4. Two AGENTS.md Code Review prose invariants: new items 13–14 ("daemon routes classified by ownership scope", "workspace-scoped routes must not fall back to the primary runtime") + two summary rows, both classified Review-only. Verified: both bullets exist verbatim in AGENTS.md's ## Code Review section on origin/main (which the /review skill loads into every review agent).

Minor nits

5. camelCase allowlist now attributed to eslint.legacy-filenames.mjs, imported by eslint.config.js — verified eslint.config.js line 18 imports legacyFilenames from that file on origin/main.
6. Prettier CI wording corrected to node scripts/lint.js --prettier — verified the Run Prettier step in .github/workflows/ci.yml on origin/main (npm run format is the local write-mode command).
7. Added the staleness clause to the voice-guard paragraph: check-voice-guard-sync.js is slated for deletion with the Electron tree in feat(desktop): remove the Electron package after OpenWork fork; keep the Tauri upgrade bridge #9085 — verified Architectural invariants are enforced ad hoc: four mechanical guards exist, everything agreed since lives in prose #9152's body states exactly that and feat(desktop): remove the Electron package after OpenWork fork; keep the Tauri upgrade bridge #9085 is still open (script still present on main).

[yiliang114]

@qwen-code /triage

[qwen-code-ci-bot]

Sandboxed verification: ⚠️ not run — n/a - workflow run

This PR changes documentation/assets only — there is no code to execute, so a sandboxed verification has nothing to verify.

中文 — 判定：⚠️ 未运行 · 不适用

该 PR 仅改动文档/静态资源，没有可执行的代码，沙箱验证没有验证对象。

— Qwen Code · sandboxed verification

[qwen-code-ci-bot]

Triage re-run completed without a new review.

⚠️ The bot has neither a verdict nor a deferral on 951b4b9733fed1671be3e5b3c0a9994a04569dc5 — no APPROVED, CHANGES_REQUESTED, or COMMENTED review of its own. A DISMISSED one does not count: dismiss_stale_reviews voids the bot's approval on every push, which is exactly when a fresh one is needed. If this re-run was meant to review or approve, it did not, and an approval left by another account is a separate vote that does not count as the bot's own.

⚠️ 机器人在 951b4b9733fed1671be3e5b3c0a9994a04569dc5 上既没有裁决也没有 defer —— 没有属于它自己的 APPROVED、CHANGES_REQUESTED 或 COMMENTED 评审。DISMISSED 不算：dismiss_stale_reviews 会在每次推送时作废机器人的批准，而那恰恰是需要一次新批准的时刻。如果这次重跑本应评审或批准，那么它没有做到；而其他账号留下的批准是另一张票，不能算作机器人自己的。

The stage comments above were updated with the latest result. View workflow run.

上方各阶段评论已更新为最新结果。查看工作流运行。

[yiliang114]

@qwen-code /triage

[qwen-code-ci-bot]

Sandboxed verification: ⚠️ not run — n/a - workflow run

This PR changes documentation/assets only — there is no code to execute, so a sandboxed verification has nothing to verify.

中文 — 判定：⚠️ 未运行 · 不适用

该 PR 仅改动文档/静态资源，没有可执行的代码，沙箱验证没有验证对象。

— Qwen Code · sandboxed verification

[qwen-code-ci-bot]

Triage re-run completed without a new review.

⚠️ The bot has neither a verdict nor a deferral on 951b4b9733fed1671be3e5b3c0a9994a04569dc5 — no APPROVED, CHANGES_REQUESTED, or COMMENTED review of its own. A DISMISSED one does not count: dismiss_stale_reviews voids the bot's approval on every push, which is exactly when a fresh one is needed. If this re-run was meant to review or approve, it did not, and an approval left by another account is a separate vote that does not count as the bot's own.

⚠️ 机器人在 951b4b9733fed1671be3e5b3c0a9994a04569dc5 上既没有裁决也没有 defer —— 没有属于它自己的 APPROVED、CHANGES_REQUESTED 或 COMMENTED 评审。DISMISSED 不算：dismiss_stale_reviews 会在每次推送时作废机器人的批准，而那恰恰是需要一次新批准的时刻。如果这次重跑本应评审或批准，那么它没有做到；而其他账号留下的批准是另一张票，不能算作机器人自己的。

The stage comments above were updated with the latest result. View workflow run.

上方各阶段评论已更新为最新结果。查看工作流运行。

[qwen-code-review-bot]

⚠️ Failed to process this request. Please re-mention the bot to retry.

[chiga0]

No blocking findings. The previous CHANGES_REQUESTED reviews (both on 06be3c5f) are addressed in the current head.

Tier: Scan — docs-only, one new markdown file, no source changes.

CI: Classify PR / Dependency CVE audit / Secret scan / Desktop Shell / Test (ubuntu, 22s path-filter only) — all green. E2E Smoke / coverage / platform matrix SKIPPED correctly (no source change).

Factual accuracy cross-check (inverted brief):

• PR refactor(cli): keep acp-integration off serve internals (#8084) #9144 (acp-integration off serve/) → OPEN ✅
• PR refactor(core): enforce internal root-barrel boundary #8139 branch → lane3-core-root-barrel ✅ (old review cited non-existent lane4-rebase — corrected in current head)
• PR refactor(core): remove root barrel self-imports and enforce the boundary #9635 branch → codex/pr-9152-root-barrel-cleanup ✅
• PR fix(sdk): support "auto" permission mode #9003 (Python/Java SDK drift) → OPEN ✅
• PR refactor: centralize cross-package contracts #9497 (cross-package-contracts.test.js) → MERGED ✅
• approval-mode-drift desktop wording → "Desktop is simply not covered by the drift test … never mentions desktop" ✅ (old "explicitly exclude" phrasing corrected)
• scripts/check-desktop-isolation.js section → present under §Architectural invariants are enforced ad hoc: four mechanical guards exist, everything agreed since lives in prose #9152 ✅
• Daemon-route invariants (§13, §14) and both summary-table rows → present ✅

Not covered: ESLint config and tsconfig files not read in full — spot-checked via PR states and branch names only.

Reviewed with AI assistance.

[qwen-code-review-bot]

Review summary

The previous review findings are addressed in 951b4b9, but I found two remaining documentation blockers:

1. The claimed coverage is still incomplete. The introduction says this is the canonical classification for “every invariant asserted in AGENTS.md,” but the document omits the normative Web Shell UI rules, including shared primitive reuse, React 18/19 forwardRef compatibility, CSS isolation, semantic tokens, and portal-root usage. It also omits several Code Review invariants while classifying two others from that same section. Either classify these rules or narrow the universal coverage claim and define the intended boundary explicitly.

2. Node >=22 is not mechanically enforced under this document’s definition. The document defines mechanical enforcement as a guard that fails the build, lint, or test suite, but the repository only declares engines.node; .npmrc does not enable engine-strict, and CI explicitly selects Node 22. An unsupported local Node version therefore produces an npm warning rather than a failing guard. This should be classified as partial/review-only, or backed by a check that actually fails on unsupported versions.

[yiliang114]

Closeout for the round-5 findings:

Changed (a5670f3):

1. The approval-mode value domain is hand-copied into 20 files across 3 languages; two copies are already wrong #9145 attribution: removed the claim that The approval-mode value domain is hand-copied into 20 files across 3 languages; two copies are already wrong #9145 identifies drift in desktop's cyclablePermissionModes — the issue's confirmed-drift table covers the Python/Java SDKs (now the only attributed drift, addressed by fix(sdk): support "auto" permission mode #9003), and desktop is now presented as an intentionally different domain the drift test does not cover and should not, which removes the self-contradiction in the paragraph.
2. Drift-guard sizes: "each 40-60 lines" → "114 and 44 lines respectively" — verified against main: scripts/tests/cross-package-contracts.test.js is 114 lines, packages/sdk-typescript/test/unit/approval-mode-drift.test.ts is 44.

The remainder of the commit's diff is Prettier markdown normalization applied by the repo's pre-commit hook (table alignment, *pattern* → _pattern_, blank lines before lists) — no semantic changes.

Verified: both corrected claims against origin/main. Docs-only change; no code, build, or test impact.

Pending: nothing — awaiting the automated re-check.

[yiliang114]

@qwen-code /triage

[qwen-code-ci-bot]

Sandboxed verification: ⚠️ not run — n/a - workflow run

This PR changes documentation/assets only — there is no code to execute, so a sandboxed verification has nothing to verify.

中文 — 判定：⚠️ 未运行 · 不适用

该 PR 仅改动文档/静态资源，没有可执行的代码，沙箱验证没有验证对象。

— Qwen Code · sandboxed verification

[yiliang114]

@qwen-code-review-bot review it and approve if no blockers

fixed

[qwen-code-review-bot]

⚠️ Failed to process this request. Please re-mention the bot to retry.

[qwen-code-ci-bot]

LGTM, looks ready to ship. ✅

[qwen-code-review-bot]

I can’t approve this yet. Two blockers remain in the canonical classification:

• The document claims to cover “every invariant asserted in AGENTS.md,” but it omits the normative Web Shell UI invariants: shared primitive reuse, React 18/19 forwardRef compatibility, semantic tokens/CSS isolation, and useWebShellPortalRoot(). Please classify them or narrow the coverage claim.
• Node >=22 is not mechanically enforced under the document’s definition. package.json#engines only warns without engine-strict, while CI selecting Node 22 does not reject unsupported local runtimes. Please mark this as a gap/partial enforcement or add an actual failing guard.

The docs-only scope is otherwise cohesive, and all required checks are green.

[yiliang114]

Both blockers addressed in 82869c0:

1. Web Shell UI conventions are now classified (new section 15): shared-primitive reuse, React 18/19 forwardRef compatibility, semantic-token/CSS isolation, and useWebShellPortalRoot() are all review-only — verified no lint rule or test enforces them on main, so reviewer judgment against packages/web-shell/README.md is the honest classification. The coverage claim now holds.
2. Node >=22 reclassified to Mechanical (partial) with an explicit gap: engines without engine-strict only warns, and CI selecting Node 22 does not reject unsupported local runtimes. Summary table updated to match (warn-only guard, "local runtime not rejected" gap); the row also names the two ways to make it mechanical (engine-strict=true or a failing preinstall check).

Docs-only; both claims verified against origin/main (AGENTS.md Web Shell section, package.json + .npmrc).

[yiliang114]

@qwen-code-review-bot review it and approve if no blockers

[qwen-code-review-bot]

⚠️ Failed to process this request. Please re-mention the bot to retry.

[qwen-code-review-bot]

One blocker remains before approval: the new Web Shell section says AGENTS.md asserts four normative rules, but it omits several requirements from that section:

• Run shadcn from packages/web-shell, review the generated diff, and keep generated components internal unless a public API is required.
• Add regression tests for ref-sensitive component paths.
• Use unprefixed Tailwind classes.
• Preserve existing data-web-shell-* attributes and public --web-shell-* CSS variables.

Since this document claims canonical coverage of every AGENTS.md invariant, please either classify these requirements as review-only too or remove the exhaustive “four normative rules” claim and explicitly cover the remaining rules by reference.

The Node >=22 classification is now accurate, and the current checks are green.

[yiliang114]

Addressed in c6c3f59: the Web Shell section no longer claims a count. It now classifies the entire AGENTS.md Web Shell UI development section as review-only and explicitly covers every requirement you listed — the shadcn workflow (run from packages/web-shell, review the generated diff, no overwrite of global CSS/semantic tokens/CSS scoping/portal-root integration, generated components stay internal unless a public API is required), the regression-test requirement for ref-sensitive paths, unprefixed Tailwind classes with the build-scoped CSS isolation, and preservation of data-web-shell-* attributes and --web-shell-* CSS variables — deferring the full convention list to the AGENTS.md section and packages/web-shell/README.md by reference.

[yiliang114]

@qwen-code-review-bot review it and approve if no blockers

[qwen-code-review-bot]

⚠️ Failed to process this request. Please re-mention the bot to retry.

[qwen-code-review-bot]

LGTM — no blockers on the current head. The Web Shell conventions are now comprehensively classified without the incorrect count claim, the Node >=22 enforcement gap is accurately documented, and all required checks are green.

[qwen-code-review-bot]

LGTM. The new commits address the two blockers from the earlier review:

1. Web Shell UI conventions are now classified (shared primitives, forwardRef, semantic tokens, portal root)
2. Node engines reclassified to reflect the partial guard gap

Docs-only, well-structured, CI green.

[chiga0]

No blocking findings. Re-review of head c6c3f59 (prior review on 951b4b9 was dismissed after new commits).

Tier: Scan — docs-only, single markdown file, no source changes. CI all green.

New content vs. previous head — verified clean:

1. §15 Web Shell UI conventions (new section): classified Review-only with accurate rationale — no lint rule can detect a missing forwardRef, an overwritten CSS scoping, or a raw portal container; enforcement is via reviewer judgment against AGENTS.md and packages/web-shell/README.md. Summary table row added. ✅

2. Node ≥22 reclassified to "partial": Previous head said "Mechanically enforced" (no qualifier). New text correctly notes that "engines" without engine-strict in .npmrc only produces an npm warning — gap explicitly documented with the fix path. ✅

Factual accuracy (carried forward from prior round, no regressions):

• PR #9144 OPEN, PR #8139 (lane3-core-root-barrel) OPEN, PR #9635 OPEN, PR #9003 OPEN, PR #9497 MERGED — all still correct as of this review.

Reviewed with AI assistance.

[qwen-code-ci-bot]

Released in v0.22.0.