diff --git a/design/engineering/architecture/architecture.md b/design/engineering/architecture/architecture.md index e044f528..7b71b09c 100644 --- a/design/engineering/architecture/architecture.md +++ b/design/engineering/architecture/architecture.md @@ -2,11 +2,11 @@ ## 文档状态 -- 版本：1.14 -- 最近更新：2026-10-26（改动域判据由路径前缀改为文件性质——`game/` 内 `.md` 归文档域） +- 版本：1.15 +- 最近更新：2026-10-26（通信形态选型理由、效果引擎定位、架构原则 9 停点机制补文＋已落定未决项、过时陈述与冻结计数清扫） - 引擎：Godot 4.7.2-stable（GDScript 单语言；2026-09-07 锁定） - 评审模式：solo（`review-mode.txt`，2026-09-12 用户拍板——TD/LP 门禁按 solo 跳过，用户授权架构产出自主推进、迭代期回调） -- 覆盖 GDD：现行全集——`design/gdd/` 顶层 00–08 共 9 件 + `systems/` 五域 25 件（排雷循环 4 / 战斗循环 5 / 冒险循环 5 / 跨局循环 5 / 表现与支撑 6）+ `ux/` 8 件；原英文命名 12 份系统 GDD 已全部迁入中文域目录，原「未设计」预留（A5 扫雷秘宝 / C1–C4 / B5 / D3–D6）均已立项成文 +- 覆盖 GDD：现行全集（根索引＝`design/gdd/02-系统清单.md`，文档树构成以根索引为准） - 事实源地位：本文是架构事实的唯一来源——分层/所有权/数据流/API 边界/测试与质量域均以本文为准；历史决策沿革查 git commit log，不另设决策文档体系 - 实现实证：`game/`（2026-09-10 起开发，**现为完整游戏开发版本，已非垂直切片**；测试层级＝冒烟/单元/集成/系统四级＋UI 探针与渲染 golden（2026-10-22 用户裁，测试术语与层级重构批），闸机按改动域分跑在役）——本文档的分层/所有权/数据流均经实现验证，非纯纸面设计 - 技术总监签核：2026-09-12 — 有条件通过（原条件「决策记录须于正式工程骨架前定稿」已满足：骨架已成、沿革在 git 历史可查；`.claude/docs/director-gates.md` 缺失已登记技术债） @@ -16,13 +16,9 @@ ## 引擎知识缺口摘要 -- **风险等级：MEDIUM**（2026-09-12 `/setup-engine refresh` 后由 HIGH 降级）。4.5→4.7 官方迁移指南已逐条核实并入 `design/engineering/engine-reference/godot/breaking-changes.md` 与 `deprecated-apis.md`；**结论：无一条破坏 GDD 已锁架构契约**（autoload 体系 / .tres 单一事实源 / Callable 信号 / int64 二补数 / headless SceneTree 协议均不受影响）。 +- 引擎事实现行事实源＝`design/engineering/engine-reference/godot/`（VERSION / breaking-changes / deprecated-apis / current-best-practices 四件）——迁移核实结论、语义变化与编码注意一律查那里，本文不重复。 +- 渲染器与窗口基座＝gl_compatibility + 1280×800（2026-09-12 裁）；UI/渲染域为引擎风险集中地，采纳引擎增量前对照 engine-reference 核实。 - 写码纪律不变：不确定的 API 一律查 `docs.godotengine.org/en/4.7/` 核实后再用；4.8（dev 阶段）稳定版发布后跑 `/setup-engine refresh`。 -- 三类必须入编码纪律的引擎事实（详见 `design/engineering/engine-reference/godot/current-best-practices.md`）： - 1. **GDScript 4.7 两条语义变化**：打包数组元素赋值不再触发属性 setter；类型化返回的方法覆盖必须显式 `return`。 - 2. **新项目默认值已变**：stretch mode `canvas_items` / aspect `expand`（4.7）；Windows 渲染驱动 D3D12（4.6，仅 Forward+ 线）——创建 project.godot 后逐项核对。 - 3. `Resource.duplicate(true)` 深复制不再覆盖外部子资源——D2 表资源复制语义注意。 -- 残余风险敞口：modules/ 分域参考未建（按实现期需要建，非阻塞）；UI/渲染域（D1/B5）为 MEDIUM 风险集中地——渲染器与窗口基座已定（gl_compatibility + 1280×800，2026-09-12），采纳引擎增量前对照文档核实。 --- @@ -77,7 +73,6 @@ | D3 存档序列化 | 基础层 | Alpha | ✅ | LOW | | D6 设置/本地化 | 基础层 | 完整愿景 | ✅ | LOW | -**MVP 关键路径**（实现已验证）：D2 → A3/A4/B3 → A1 → A2 → B2/B4 → B1 → D1-lite。 **依赖分层与唯一回边**：A2 只外发三事件（cell_revealed / flag_judged / round_end），B4/B1 订阅后回调——A2 不依赖任何下游（TD-SYSTEM-BOUNDARY 裁决，全项目唯一允许回边）。 --- @@ -91,11 +86,11 @@ | 模块 | 独占职责 | 对外暴露 | 消费依赖 | 引擎 API | |---|---|---|---|---| | **ConfigDB**（autoload，D2） | 全部玩法数值表（`data/tables/*.tres` + `data/schemas/*.gd`）；SCHEMA_VERSION；加载/校验/override/诊断状态机 | 类型化属性读取；`load_tables(root, collect_only)`；`resolve()`（R1 floor）；debug override；`set_reload_gate()`；诊断收集器 | 无（基础层顶点） | Resource/.tres 加载、autoload 生命周期——LOW | -| **RngService**（autoload，D2） | master_seed、各流 scope 计数器（封闭流：board_gen / reward_roll；增流走 P1 评审） | `set_master_seed()`（唯一调用方 C2）；`open_stream(stream)` 有状态门面；`derive_at(stream, scope)` 纯函数；只读计数器 | ConfigDB（无） | 无——纯逻辑 | +| **RngService**（autoload，D2） | master_seed、各流 scope 计数器（封闭流词表现值以 `RngServiceCore.PURPOSE_TAGS` 为准；增流走 P1 评审） | `set_master_seed()`（唯一调用方 C2）；`open_stream(stream)` 有状态门面；`derive_at(stream, scope)` 纯函数；只读计数器 | ConfigDB（无） | 无——纯逻辑 | | **action_economy**（A3） | AP/RAP 账本、last_round_end、轮次相位机 {Idle, Active, Waiting}、结束仲裁 | 意图与通知布尔面：notify_round_start / request_dig / request_stop / request_refresh / notify_settlement_done / notify_combat_end；预授权通道：grant_reserve_ap / finish_round_stop；ap/rap/phase 只读 | ConfigDB（ActionEconomyTable）；effect_engine（事件发射 dispatch——基础层内同层引用）；B1 回发 next_round_mode/battle_over | 无 | | **variation 定义**（A4） | VariationTable schema（现行 6 行：六 region——贫矿脉 global 行 2026-10-16 用户令屏蔽删行，global 型机制代码保留）与 F1 候选池门控谓词 | `variant_pool(level_index, board_type, node_type="")`（门控三维：unlock+board_types+节点身份——global 行仅 boss/elite 入池，缺省跳过零扰动）；`global_variant_row(level_index, board_type, node_type)`（全局型单行决议访问器） | ConfigDB（VariationTable） | 无 | | **status_container**（B3） | 状态实例容器（战斗域生命周期、跨轮跨图延续） | 5 API：notify_battle_start / apply_effect / query_active / decay_round / notify_battle_end | ConfigDB（StatusEffectTable） | 无（RefCounted） | -| **effect_engine**（内容数据驱动扩展批 iter17 建域） | 零运行时可变状态的系统（见「架构原则」条 8）：事件/事实/效果类型/算子四词表封闭（迭代 21 T3 扩签：EVENTS 18→19 +seal_missed 标错判定、FACTS +battle_index 关卡域战斗序）+ 树规则合成订阅六键（posture 每关首轮窗/sense 两组限次 counter 闸·adv_ 前缀走冒险桶跨战斗持久） | rebuild（每战重建订阅表）/`dispatch(ctx, event, payload, facts)`/`validate_trigger_row` + 静态计数口 `counter`·`counter_add`·`counter_spend`·`bucket_of`·`counter_id_legal`（计数器读写只经 EffectContext 引用束，无导出/灌入接口） | ConfigDB（feats/treasure 行集）、EffectContext（四桶引用由宿主持有：round/battle 桶归编排器、level 桶归关卡域、adventure 桶归 RunLedger） | 无（零随机全确定） | +| **effect_engine**（内容数据驱动扩展批 iter17 建域） | 零运行时可变状态的系统（见「架构原则」条 8）：全同步解释器——事件由宿主在明确代码点位显式调 dispatch 进件，命中序＝装载声明序（feats→treasure→树规则）写死保种子复放，不是事件总线/事件循环；事件/事实/效果类型/算子四词表封闭 + 树规则合成订阅六键（posture 每关首轮窗/sense 两组限次 counter 闸·adv_ 前缀走冒险桶跨战斗持久） | rebuild（每战重建订阅表）/`dispatch(ctx, event, payload, facts)`/`validate_trigger_row` + 静态计数口 `counter`·`counter_add`·`counter_spend`·`bucket_of`·`counter_id_legal`（计数器读写只经 EffectContext 引用束，无导出/灌入接口） | ConfigDB（feats/treasure 行集）、EffectContext（四桶引用由宿主持有：round/battle 桶归编排器、level 桶归关卡域、adventure 桶归 RunLedger） | 无（零随机全确定） | | **save_system**（D3，Alpha；iter27 已升格 autoload「SaveManager」） | 存档格式与版本比较 | （契约规范源：`../../gdd/systems/表现与支撑/存档序列化.md`——契约锚：SCHEMA_VERSION + master_seed + 各流 scope 计数器快照，须在无正在执行中的 open_stream 实例时切出） | ConfigDB、RngService 只读计数器 | FileAccess——LOW | | **settings/localization**（D6，愿景） | 设置项、翻译数据 | （契约规范源：`../../gdd/systems/表现与支撑/设置与本地化.md`） | ConfigDB | 无 | @@ -161,9 +156,9 @@ ### 视觉层装配合同 -- **树序 = 登记序 = z 序**，同源派生；层序唯一事实源 = `main.gd` 的 `LAYER_CONTRACT` 常量表（现行 18 项，kind 五类：shell=屏壳〔成员随壳不占独立树位〕／modal=模态层〔入登记册，tags 随登记〕／state=全屏态／node=非视觉节点／float=不注册 ModalStack 的最顶浮层〔任何 UI 打开都不遮挡它〕）。 +- **树序 = 登记序 = z 序**，同源派生；层序唯一事实源 = `main.gd` 的 `LAYER_CONTRACT` 常量表（kind 五类：shell=屏壳〔成员随壳不占独立树位〕／modal=模态层〔入登记册，tags 随登记〕／state=全屏态／node=非视觉节点／float=不注册 ModalStack 的最顶浮层〔任何 UI 打开都不遮挡它〕）。 - 全仓唯一落位口 = `_apply_layer_contract()`（装配尾统一排序+登记）；散落 `move_child` 由冒烟 V1d 源码断言判红；**改层序只改合同表**。 -- 具体层清单不复制进本文（双写失同步禁令）——查现行 18 项直接读 `main.gd`。 +- 具体层清单不复制进本文（双写失同步禁令）——查现行层项直接读 `main.gd`。 ### 会话生命周期（RunScope） @@ -194,7 +189,7 @@ ## 测试与质量域 -> 定位：本节为测试域（本地闸、探针、静态扫描等横切关注点）的**事实源**。仓库无远端、无 CI——本地闸是唯一验收门禁，判定严密性即全仓质量下限。 +> 定位：本节为测试域（本地闸、探针、静态扫描等横切关注点）的**事实源**。仓库无远端、无 CI——本地闸是唯一验收门禁，判定严密性即全仓质量下限。第三方测试框架（gdUnit4）经 2026-09-12 评估不引入，现行测试载体＝本节自制闸体系。 ### 模块归属 @@ -226,7 +221,7 @@ | **git pre-commit 钩子** | `tools/hooks/pre-commit`（版本化本体，`core.hooksPath` 挂载；在位性由 run_all_gates.sh 跑批自检——失位即红） | 直改车道闸机检：staged 不含代码面的提交，提交点现场跑 `run_all_gates.sh --docs`（秒级文本扫描），绿落地红拦；staged 含代码面时主工作区＝拦（代码面唯一合法路径＝worktree 批合回）、任务 worktree＝跳过（归批末闸＋合回闸，不打扰迭代批中间提交） | staged 文件性质＋主区/worktree 判定（git-dir 与 common-dir 同一＝主区） | | **worktree-guard**（ZCode PreToolUse） | `.zcode/hooks/worktree-guard.sh`（本机件，不入 git） | agent 侧车道纪律：主工作区代码面的 Edit/Write 与 staged 含代码面的 commit 拦截；`git commit --no-verify` 拦截（该旗标仅属用户）；合回闸回执六况校验 | 路径性质＋分支名＋回执 JSON＋git 图 | -取舍依据：失败代价不对称——docs 红是死链/术语/格式，下次任何跑批对基线比对必暴露、秒级修复，故文档面轻执法（commit 点闸、无回执流程）；代码面红是运行时行为坏，保留「worktree＋批末域闸＋回执硬绑定」全套。git 层钩子对一切提交者生效（含用户手工提交，紧急出口 `--no-verify`）；ZCode 层只约束 agent。 +取舍依据：失败代价不对称——docs 红是死链/术语/格式，下次任何跑批对基线比对必暴露、秒级修复，故文档面轻执法（commit 点闸、无回执流程）；代码面红是运行时行为坏，保留「worktree＋批末域闸＋回执硬绑定」全套。git 层钩子对一切提交者生效（含用户手工提交，紧急出口 `--no-verify`）；ZCode 层只约束 agent。子代理覆盖面（2026-10-26 冷启动评估实测）：子代理的工具调用不经过 ZCode 层守卫（代码面 Edit 未被拦、`--no-verify` 探针未被拦）——ZCode 层实际只覆盖主会话工具调用，git 层因此是唯一覆盖一切提交者的执法层；残余暴露面＝蓄意 `--no-verify`（pre-commit 族钩子被该旗标整族跳过，git 层无法自防），属故意越权而非遗忘型失误，与防遗忘的设计目标正交。 ### 三条判定硬闸现行状态 @@ -311,21 +306,20 @@ B1 ──install_board / retire_board──▶ A2 B1 ──generate(L,D)─ D1 ◀──呈现数据源：A2 事件流 / B1 步骤流 / A3 ap-rap / ConfigDB display_name ``` -- **事件载体（已定）**：组合根直连信号接线 + B1 Waiting 相位触发（不依赖事件到达序）；autoload 全局事件总线已否决（2026-09-12，沿革见 git 历史）——单线程回合制沿用组合根直连（KISS）。 +- **事件载体（已定）**：组合根直连信号接线 + B1 Waiting 相位触发（不依赖事件到达序）；autoload 全局事件总线已否决（2026-09-12，沿革见 git 历史）——单线程回合制沿用组合根直连（KISS）。选型理由＝可回放（架构原则 3）：同步直连让调用顺序显式可见，「同种子逐位相同」才可断言；Godot 信号本身就是同步函数派发，全库不存在事件循环。事件驱动形态服务的是并发/IO 场景对外部不确定时序的反应性，与本作「顺序确定」的需求相反。 - 事件规范序：A2 发射序 = 触发格 BFS、8 邻行主序；事件序契约 `flag_judged` < `round_end` 全路径统一。 - **呈现层订阅禁令（切片缺陷②教训固化）**：呈现层永不直接订阅 排雷玩法／行动经济 的事件流，只订 战斗结算 步骤流与 `level_runner`——核心事件形态变化不得直接冲击界面。 -### 3. 存档/读档路径（MVP 无存档；契约已锁） +### 3. 存档/读档路径 -- MVP 无元进度持久化（C4/D3 归 Alpha）。**已锁契约**：续玩/复盘快照 = master_seed + 各流 scope 计数器 + 意图序列 + 窗口选择序列；快照切出须发生在无正在执行中的 `open_stream` 实例时（scope 事件边界外——B1 编排保证：切点 = board install 边界）。 -- 可回放性已实证：切片冒烟同种子双跑步骤流逐行相同（B1 AC-33 前身）。 -- D3 Alpha 期按此契约设计格式；SCHEMA_VERSION 高版本拒读。 +- 存档系统已实装：格式、三槽位、断点域与迁移链的现行契约以 `design/gdd/systems/表现与支撑/存档序列化.md`（owner）为准。 +- RNG 快照契约（现行仍成立）：断点续玩回填 = master_seed + 各流 scope 计数器；快照切出须发生在无正在执行中的 open_stream 实例时（scope 事件边界外——B1 编排保证：切点 = board install 边界）；SCHEMA_VERSION 高版本拒读。 ### 4. 打包与字体（CJK 随包发行） CJK 字体随包发行并设为 theme 默认字体——运行时默认字体无中文字形。此项是 HUD框架 正式化的硬性前置，同时进导出 checklist 核对项。 -### 4. 初始化顺序 +### 5. 初始化顺序 ``` 进程启动 @@ -380,6 +374,7 @@ CJK 字体随包发行并设为 theme 默认字体——运行时默认字体无 6. **依赖单向 + 组合根模式**——层间单向依赖、唯一回边 = A2 事件订阅面；核心写调用唯一发生在组合根；禁上帝对象（切片 1100 行 main.gd 反面案例 → 9 单元拆分）。 7. **呈现层契约成文**——面向呈现的信号载荷必须有成文 schema；模态覆盖层必须有"打开时遮挡物隐藏"场景级断言；场景级 UI 探针测试为标配（切片缺陷 ①②④⑤ 教训沉淀）。 8. **系统无状态**——效果引擎这类系统零运行时可变状态：数据由宿主对象持有并随宿主生灭，状态按参数传入系统，系统只做判定（立项判据=2026-10-19 用户会话裁定；落地=迭代 32 卡②，2026-10-21 用户裁写入）。系统实例不持计数器——计数器住桶（round/battle/level/adventure 四桶，EffectContext 引用束），桶住宿主。 +9. **停点权威在核心层**——玩家决策停点（选路、三选一、商店、恢复这类）的推进守卫住核心层状态机：停点未兑付，推进口一律拒绝（零自动推进契约）；呈现层模态只做开合与输入锁——阻塞是两层结构，核心守卫为权威、模态为体验；停点态是核心状态、随断点序列化，headless 跑批与真实局同一套规则，中断续玩恢复到同一停点。 --- @@ -387,9 +382,6 @@ CJK 字体随包发行并设为 theme 默认字体——运行时默认字体无 | ID | Summary | Priority | Resolution Path | |----|---------|----------|-----------------| -| QQ-01 | 渲染器选择（Forward+ vs gl_compatibility）与项目窗口基线 | High | **已落定**（2026-09-12）：gl_compatibility + 1280×800 基座（canvas_items + expand）；沿革见 git 历史 | -| QQ-02 | 事件总线载体与 A2 事件捕获测试 API | High | **已落定**（2026-09-12）：组合根直连 signal + Waiting 相位触发；autoload 全局总线否决 | -| QQ-03 | gdUnit4 是否引入并迁移冒烟用例 | Medium | **已落定**：deferred（现行双载体承载；D2 OQ1 关闭） | | QQ-04 | 轮内刷新数值连锁（清图支配性条款⑤ / 真人刷图行为获取期望）重算 | Medium | playtest 实测 | | QQ-05 | 战斗末可选类"j==0 补发 1 件"兜底是否采纳（切片遗留待办） | Medium | playtest + B4 GDD 修订批 | | QQ-06 | 可选类退出格子池后 buff 频率被动上升（44%→59%）的难度对冲杠杆（敌 HP / 权重 / 幅度） | High | C3 调参 + 切片数据复测 | diff --git a/design/engineering/doc-conventions.md b/design/engineering/doc-conventions.md index cb333f1a..1689565f 100644 --- a/design/engineering/doc-conventions.md +++ b/design/engineering/doc-conventions.md @@ -69,6 +69,7 @@ | 正文只写现行规则 | 禁删除线、"（作废）"、"（日期+拍板）"式注记；审计信息入对应文档附录 | | 正文单点维护 | 一条规则句只写在定义它的那份文档（owner 文档）；其他文档要引用时写指针或语义概括，禁复制色值、尺寸、路径等可核对的具体值——上一句管不住数值之外的双写，本句补上。豁免面 = 执行侧文件必须带字面值才能工作时（生图提示词里的十六进制色、脚本参数），转写不算双写，但该文件头部必须写明"冲突时以 owner 文档为准" | | 禁写变更记录 | 文档与代码文件内一律禁设「版本历史／修订记录／变更记录／修改记录／更新记录／更新日志」节或表格，禁逐版本叙述「改了哪些条款」；沿革与改动明细只进 git commit log。版本号可作为文档现行身份标记出现在文首状态行与正文引用中，但不得再挂变更表 || 后置 ≠ 删除 | P1/P2 后置内容逐条列出；复活后置项 = 修订文档，禁静默加回 | +| 活体清单不冻结计数 | 对会生长的清单（文档树构成、UI 层项、RNG 流词表等）不写死计数与枚举——写指针到 owner（根索引/常量表/实现文件），现状值由 owner 承载；历史计数只进 git 提交信息 | **数值纪律**：正文定规则、取值域、单位；平衡值进 `data/tables/`，provisional 必须标注；已锁数值事实源 = `game/data/tables/*.tres`（现行值）与 owner 文档正文（规则、取值域、单位）。 diff --git a/reports/工程改动报告-车道铁律-2026-10-26.md b/reports/工程改动报告-车道铁律-2026-10-26.md new file mode 100644 index 00000000..d43a9079 --- /dev/null +++ b/reports/工程改动报告-车道铁律-2026-10-26.md @@ -0,0 +1,45 @@ +# 工程改动报告——车道铁律换代（worktree 收窄＋直改闸） + +2026-10-26 · 本批=工程改动＋文档设计改动混合批，用户逐点裁决后发令执行 · 按旧流程 worktree 落地合回（e2cc26ec），合回后新规即时生效 + +## 改了什么 + +**规则换代**：2026-09-19 立的「一切改动走独立 worktree」铁律，改为**车道铁律**——判据与改动域划分同一（文件性质）：代码面（`game/` 下非 `.md` 行为载体）唯一强制 worktree；其余一切面（含 `game/` 内 `.md`）主工作区直改＋直提，验收＝commit 点 git pre-commit 钩子现场跑 `--docs`（秒级），绿落地红拦，无回执流程。动机：文档维护类小改动高频，全套 worktree 仪式成本远超改动本身；机检强度不降级——绑定点从 merge 挪到 commit，验的就是提交字节。 + +**落地件**（worktree 批 lane-reform-20261026，6 文件）： + +| 件 | 内容 | +|---|---| +| `tools/hooks/pre-commit`（新增，版本化） | 直改闸：staged 判代码面（game/ 非非 md）；非代码面→现场跑 `run_all_gates.sh --docs`；代码面→主区拦／worktree 跳过；两段拒绝文案（新增红／闸自身故障） | +| `.gitattributes`（新增） | `tools/hooks/* text eol=lf`——autocrlf=true 下检出转 CRLF 会毁 bash 钩子 | +| `tools/run_all_gates.sh` | 开工自检：`core.hooksPath` 失位且默认钩子位无 pre-commit→红＋自愈命令（防换机/重克隆后静默免验） | +| `AGENTS.md` | 红线第一条换代＋验收段/四类段/导航表/Layout 五处同步 | +| `design/engineering/process-conventions.md` | §1 整节改写（两车道＋执法分层）＋§2/§3 四处扫尾 | +| `design/engineering/architecture/architecture.md` | 测试与质量域新增「车道分层执法」登记（两层职责表＋不对称取舍依据） | + +**本机件**（`.zcode/`，不入 git，主区直改）：`worktree-guard.sh` 车道化收窄（Edit/Write 只拦代码面；commit 只拦 staged 含代码面＋`-a` 形态查工作区；新增 `--no-verify`/`-n` agent 禁用拦截；合回闸零改——推域判据已被同日另批改为文件性质，天然一致）＋四技能（doc-design/iter-plan/asset-ingest/batch-closure）车道条款与收尾闸口径 11 处。`core.hooksPath=tools/hooks` 已配置（worktree 共享）。 + +## 验证结果（七条全过，撤销对应改动均可复现变红） + +| # | 测试 | 结果 | +|---|---|---| +| V1 | 临时分支造红（新根文件绊熵增闸）→commit | 钩子跑闸→红项可见→文案 A 逐字→提交中止，分支尖未动 | +| V2 | 本报告直提 master | 走真实直改车道（见下「评估」） | +| V3 | 主区 Edit `game/core/damage_math.gd` | 守卫拦，文案正确，文件零改动 | +| V4a | bash 改 game 文件→stage→单独 commit | ZCode 层按 staged 路径拦 | +| V4b | `add&&commit` 单命令链（ZCode 层看不到 stage） | git 层接住：`[直改闸] 主工作区禁止直提代码面`，master 零位移 | +| V5 | `git commit --no-verify` | ZCode 层拦（agent 禁用该旗标） | +| V6 | 临时 worktree 双提交 | docs 提交 7.3s 过闸落地（冷检出钩子执行正常＝LF 钉死生效）；game 提交跳闸秒落 | +| V7 | 带代码面的分支无回执 merge 进 master | 合回闸六况照常拦＋按域指引（回归确认零改） | + +## 评估（真实任务） + +1. **重量减轻（已测）**：本报告＝新规后第一个真实直改提交——动作数 2（写文件→add+commit，闸自动），对照旧流程 8 动作（建 worktree→搬运→改→跑闸→冻结件核→并 master→merge→删区）。 +2. **冷启动 AI 检验（已完成——2026-10-26 用户裁以子代理代行，提示词仿当日真实批令口吻）**：全过——零 worktree、零游戏测试、零手动跑闸（闸全部由 commit 点钩子自动跑，共 3 次 2 绿 1 红）、造红被拦后读日志定位红因→清理→无扩大测试。附带真发现：代码面两处陈旧 `design/research` 注释指针（shop.tres:98、tile_palette.gd:11，见核查记录）留待工程车道。**架构发现**：子代理工具调用不经过 ZCode 守卫层（代码面 Edit 未拦、`--no-verify` 未拦）——git 层是唯一全提交者执法层，正常提交路径全被拦；残余暴露面＝蓄意 `--no-verify`，已在 architecture.md 车道节登记。 +3. **game/ 车道零扰回归（待下一迭代批）**：定义入库提交约 +6s（预期）、代码提交零打扰、合回闸行为不变，记入该批实现报告。 + +## 边界与遗留 + +- 合并前已在途的旧 worktree（camp-art-doc ×2、camp-prompts-doc、iter37-plan、mutation-purge、quotaface）检出无钩子文件——git 对缺位钩子静默跳过，零打扰；其下次并入 master 后自然纳入执法。 +- 守卫 `--no-verify`/`-n` 判定是词法匹配（与既有词法判同精度级），消息值误报理论存在；git 层直改闸为最终兜底。 +- 主区 `game/tests/.gates/receipt.json` 现为 V1 测试残留（红回执，gitignored），下次任何跑批覆写，无影响。 diff --git a/reports/车道核查-退役路径引用-2026-10-26.md b/reports/车道核查-退役路径引用-2026-10-26.md new file mode 100644 index 00000000..a7cbb11a --- /dev/null +++ b/reports/车道核查-退役路径引用-2026-10-26.md @@ -0,0 +1,5 @@ +# 车道核查：退役路径 design/research/ 的活引用（2026-10-26） + +- 查了什么：全仓 md（链接与正文指针）＋非 md 载体，关键词 `design/research`；`design/` 下已无该目录。 +- 命中什么：md 四处（三份文件）——AGENTS.md 两处、doc-conventions.md §11 一处、道具退役素材库.md 头注一处，均为「已退役」声明或历史迁出注记，非活引用，未动。非 md 四处——`tools/repo_structure_audit.py` 退役清单与 `tools/doc_ref_audit.py` 件头注（执法件自身，非活引用）；另有 `game/data/tables/shop.tres` 与 `game/presentation/views/tile_palette.gd` 各一处注释仍把 `design/research/...md` 当权威出处指向，目标文件已不在（`reports/` 无同名件），属代码面陈旧指针，本次不动，留待工程改动车道处理。 +- 改没改：现行文档零活引用，本核查零修改；本文为唯一产出。