文档(代拍板追认单退役): 取消批后追认环节——独立产出物 iter<N>-代拍板-<日期>.md 废止,超白名单/超卡片明列范围事项改记实现报告「实现决定记录」节(逐条记决了什么/为什么/代价/撤销方式,全按卡执行只写一行零拍板)——2026-10-28 用户裁:追认环节自设立起未被逐条行使、实现面全权委托,备案记录并档实现报告;三道前置闸不动(卡片代拍板白名单预授权/实现段零裁断/验收有效性事件当场停机呈报);修订面=process-conventions(五段表完成人闸+§2零裁断段+§3第11条产出物)+doc-conventions §11载体表+AGENTS.md reports行+reports/README产出物表+repo_structure_audit头注,iter/req-card/batch-closure三技能随批直写(.zcode不入git);登记与完成同会话坍缩故条目免落(待办清单正被iter40收尾会话编辑,避抢写;现存两份代拍板单已由该会话按退役判据暂存删除,不追溯)

This commit is contained in:
DKChan committed 2026-10-28 05:31:04 +08:00
1 parent 3e9a675bad
commit dd99884e12
5 files changed
+7 -8

No files matched your search

+1 -1
View File
@@ -33,7 +33,7 @@
- `game/assets/art/` — 已验收终稿(入包被游戏加载);`game/probe/` — 场景探针的场景与宿主+探针共用面(probe_gate/render_gate 在闸+人工取证探针);`game/sim/` — 测量/诊断/模拟驱动件(autoplay 策略、MC 批量、数值验证采集端);`game/` — 游戏工程本体(代码 + tests/ 冒烟/单元/集成/系统测试面)
- `sim-data/` — 机器读数据产物;数据件不入 git(入库例外 = README+analyze.py+growth_model.py);MC 锚与读数常驻留盘,无数值调整禁重跑
- `tools/` — python 工具脚本(含 `hooks/`=版本化 git 钩子,经 `core.hooksPath` 挂载);`archive/` — 批次完结归档 zip(gitignored)
- `reports/` — 过程件容器:**需求卡片**(写卡段产出,实现批的输入合同)+迭代批产出物(实现报告/代拍板追认单/GDD 反哺点清单)+设计讨论段过程稿(提案/审计/需求澄清/评估);**实现批唯一可写目录**,中间文档唯一容器(`design/research/` 已退役),不是事实源(细则见 `reports/README.md`)
- `reports/` — 过程件容器:**需求卡片**(写卡段产出,实现批的输入合同)+迭代批产出物(实现报告/GDD 反哺点清单)+设计讨论段过程稿(提案/审计/需求澄清/评估);**实现批唯一可写目录**,中间文档唯一容器(`design/research/` 已退役),不是事实源(细则见 `reports/README.md`)
- 根目录:`README.md`(纯指路牌:设计/流程/当前位/待办四个链接,零规则重述)、`roadmap.md`(里程碑+迭代总表六列+顶部「当前位」节=现在做什么)、`待办清单.md`(流水线唯一登记处,条目级待办与状态)、`体验验证清单.md`(需真人试玩才能下结论的验证项)、`stage.txt`/`review-mode.txt`(运行开关)、`playnote.md`(用户本人试玩随手记,只由用户增删,不属任何文档族);仓库根禁止再设会话状态文件(细则见 doc-conventions 第 10 节)
## 规范导航(定方案前先查表——确认写什么内容之前读规则,不是动手前才读)
+1 -1
View File
@@ -123,7 +123,7 @@
| 出口清理项 | 每迭代出口检查单必含:本迭代中间产物逐份核对(结论已吸收、未决已迁移)后删除 |
| 暂存地非档案库 | 中间文档唯一暂存地=`reports/`(需求卡片+迭代产出物+调研/审计/提案/需求澄清过程稿)。**`design/research/` 已退役(2026-10-21 用户裁)**:`design/` 全目录只放持久化设计文档与规范,过程件一律不进,禁止再在 `design/` 下另设过程件目录(熵增闸退役路径清单已收 `design/research`,目录再现即判红)。禁止文件在自身页眉自称「常驻/已追认/不受吸收即死约束」之类的豁免——豁免只写进规约正文,本条就是不给;确实要长期留用的退役内容走 `design/content-archive/`(活文档身份,落内文件头部写明所属线)。跨会话交接文件(会话提示/handoff/任务书/试运行报告)禁止入库——给另一个会话的开工输入在会话里交付即可(与仓库根禁设会话状态文件同族判据,见第 10 节)。根目录 `playnote.md`=用户本人试玩随手记,只由用户本人增删,不属于任何文档族、不受吸收即死管辖,不进 §11 任何一格。图像载体不进 `design/` 各子目录、也不进 `reports/`——图一律留 `artwork/`(2026-09-27 用户裁「审图只看一处」),结论写进待办清单或需求卡片后图像即弃;`.html`/`.json` 这类报告渲染件允许作为报告的一种(2026-10-21 用户裁);只有需要机器逐像素比对的基线图长期入库,落 `game/tests/golden/` |
| 落档必写接收方 | 新报告落档时头部必须写明接收方——`待办清单.md` 第几条,或哪张需求卡片。写不出接收方的不落文件,内容在会话里交付即可 |
| 迭代实现报告 | 实现批收口的迭代级报告(各卡状态/代拍板追认单/GDD 反哺点清单),属中间文档,**落 `reports/` 不落 `design/`**(实现批禁写 `design/`,`reports/` 是其唯一可写目录):反哺点裁决落文吸收后按「证据只留最新」退役 |
| 迭代实现报告 | 实现批收口的迭代级报告(各卡状态/实现决定记录/GDD 反哺点清单),属中间文档,**落 `reports/` 不落 `design/`**(实现批禁写 `design/`,`reports/` 是其唯一可写目录):反哺点裁决落文吸收后按「证据只留最新」退役 |
| 证据只留最新 | 测试证据只保留最新一次迭代或最新一轮同类审计版本;新证据落位后同批删上一份;待人清单过人闸后同规退役 |
**删除方式**:按 `design/engineering/concept-conventions.md` 第 2 节删除概念 SOP 口径——先查引用面(grep 文件名于阻塞域),改写或删除指路句,再删文件,收尾跑死链检查全绿。执行入口=项目技能 batch-closure(批后收尾与中间文档退役)。
+3 -3
View File
@@ -24,9 +24,9 @@
| 二·文档设计/美术设计 | doc-design(文档线,兼任反哺点写入)/asset-ingest(美术录入;样张素材由用户主导产出) | GDD 文档或 art-bible/过审样张素材 | 用户提起或从待办清单取出;会话内进行、用户主导、禁无监管自跑;经用户点头确认心智一致才许写入文档;完成判据=待裁点清零,带未裁点的是讨论稿;设计线闭合凭据记入待办清单实况清单(文档线=文档路径+版本号,美术线=art-bible 条款版本);缺哪条线写在缺口属性,闭合与否写在状态段 |
| 三·写需求卡片 | req-card | 需求卡片 | 设计线闭合后用户发令;新玩法/新系统/新内容必须有设计定稿前置,例外=需求性工程条目(缺陷修复/重构等改游戏行为)凭实况里的证据指认跳过设计线;配套维护类(工程债/测试基建/工具维护,不动游戏行为)=工程改动直改类,不走本段,登记后「待执行」由用户发令直改;卡片必经 grilling 多轮复核、零待裁点才成立;写完在待办清单状态记「已写卡」,卡片路径记入实况清单(防遗忘) |
| 四·迭代编排 | iter-plan | roadmap 迭代行 | 编排四查:①每卡卡片文件存在 ②每卡设计闭合凭据齐(或需求性工程条目的证据指认)③估时与冻结线——所选卡估时按区间**中值**求和(单位工作日、写精确值不取整):**卡片任何工作量均可编入**(2026-10-25 用户立:工作量限制属迭代层、非卡片层);编入后迭代总量 <5 个工作日=迭代行状态「冻结待凑批」、不可开工,凑批 ≥5 后由编排段改「待开工」(迭代体量偏好,2026-10-21 用户立、2026-10-25 改冻结制);5–10 个工作日为常规区间;超过 10 个工作日须经用户确认(确认前呈报整批/拆批两案等裁,禁自行拆分或塞入),确认后迭代行随带日期特批标记;超过 20 个工作日禁止编(硬上限,用户确认也不放行,必须拆批)④写完 roadmap 行后跑流水线闸确认绿;编入未完成迭代,新开迭代行经用户确认 |
| 五·实现 | iter | 代码与配置,可运行的游戏 | 需求卡片永不单独施工,统一由用户指定迭代号触发(=U0 开工令),按 iter 技能与本文 §3 执行;**本段是代码实现批:禁写 `design/` 与根规则文件,产出物只落 `reports/`(见 §3 第 12 条)**;设计权威文档(GDD/art-bible)批内一律不更新;完成人闸=实机目检清单+代拍板追认单登记交用户即完成批内义务 |
| 五·实现 | iter | 代码与配置,可运行的游戏 | 需求卡片永不单独施工,统一由用户指定迭代号触发(=U0 开工令),按 iter 技能与本文 §3 执行;**本段是代码实现批:禁写 `design/` 与根规则文件,产出物只落 `reports/`(见 §3 第 12 条)**;设计权威文档(GDD/art-bible)批内一律不更新;完成人闸=实机目检清单+实现决定记录写齐即完成批内义务 |
**实现段零裁断**:实现段的输入在编排段出口已锁死(卡片零待裁点+设计闭合凭据齐+编排四查过)。实现中冒出卡片没写清的分歧=上游缺陷——停该卡、待办清单状态回退+缺口补记,退回上游;禁自答、禁内联提问求裁断;该卡停摆不阻塞同迭代其他卡。环境故障与测试红走异常分级(自救重试/记录继续/停机呈报)。代拍板白名单保留:授权发生在卡片审问阶段,实现只执行预授权;批后追认单=备案确认。
**实现段零裁断**:实现段的输入在编排段出口已锁死(卡片零待裁点+设计闭合凭据齐+编排四查过)。实现中冒出卡片没写清的分歧=上游缺陷——停该卡、待办清单状态回退+缺口补记,退回上游;禁自答、禁内联提问求裁断;该卡停摆不阻塞同迭代其他卡。环境故障与测试红走异常分级(自救重试/记录继续/停机呈报)。代拍板白名单保留:授权发生在卡片审问阶段,实现只执行预授权;超白名单/超卡片明列范围事项记入实现报告「实现决定记录」节备案,不另立追认单。
**流水线闸**:`tools/pipeline_gate.py` 机检待办清单与 roadmap 两文件的格式与互相引用;已注册进 `run_all_gates.sh` 文档域。流程文档的条目格式、迭代行格式与状态机细则见 doc-conventions 第 12 节。
@@ -51,7 +51,7 @@
8. **批末按域验收才合并(worktree 批;直改车道无批末动作,验收在 commit 点由 git 钩子执行,见 §1 第 3 条)**——在任务 worktree 内跑 `tools/run_all_gates.sh`,**按本批改动域选档**:按文件性质判——代码面=`game/` 下非 `.md` 的行为载体(代码、测试脚本、探针、场景、数据表、素材)→ `--code`;文档件=`game/` 内 `.md`(README、生成清单)与 `game/` 外一切路径(`design/`、根规则文件、`tools/` 工具脚本、`.zcode/` 配置等)→ `--docs`;两类同批都有 → 全量档不带参数。所选域全绿才合回 master。合回前独立验收审计通过(iter 技能第 5 步),未过不合回。该脚本是全部验证闸的**唯一入口、唯一清单与唯一域划分**,闸件增减、分域调整都只改它;**本文与其他文档禁另列闸件清单**(清单散落多处正是 iter27 漏跑 `probe_gate --full` 的成因)。跑完写回执 `game/tests/.gates/receipt.json`(含 `domain` 与 `dirty_game` 字段),合回时由 worktree-guard 按 diff 文件性质推域强制校验(六况拦截:缺回执/quick 模式/回执未覆盖分支尖=回执 commit 之后代码面又有改动、或跑闸时代码面带着未提交改动(`dirty_game`)/域不覆盖本次改动/含新增红/master HEAD 非回执 commit 祖先=合并将产出未测内容)。回执与分支尖的对齐判据是**代码面**不是 commit 号:回执之后只追加文档件(`game/` 内 `.md`、`reports/`、`design/` 等)提交,回执照样有效,不构成复跑理由。闸件(`tools/` 下机检脚本与闸壳)自身的改动不占合回全量——其质量义务=落批时人工确认闸可跑通且判据口径未变,闸真崩溃时合回闸 fail-closed(跑不出回执即拦),不以合回全量为兜底
9. **合并后主区零复跑**(2026-10-24 用户裁:合回重跑验的是与回执同一份字节,零信息)——合回落地后 code 批只做两件秒级事:`--editor --quit` 重刷类名缓存(在册坑:.godot 缓存不入 git,与合并后代码失配会假红假绿)+冒烟启动确认可开机(合计约 1 分钟);docs 批零动作。全量验证**每批跑一次**=worktree 批末按域闸,顺序是「先并入 master、再跑闸」(§1 第 2 条);只有两种情形允许把这次跑作废重来——① 闸红且修法动了 `game/`,② 闸已开跑后 master 又被推进(合并将产出未测内容,由合回闸祖先判定拦下,§3.9 第六况)。「跑都跑了再跑一遍保险」「闸后顺手改点 `game/` 再补一跑」都不构成复跑理由;master 上永不跑全量
10. **批次完成后的登记义务**——合回 master 后按 doc-conventions §12.1 推进待办清单条目状态(做完整条删除),涉及迭代编排的在 roadmap 迭代总表与顶部「当前位」节换代——执行入口=项目技能 batch-closure(批后收尾与中间文档退役),跨会话教训写记忆库。批次过程与结论由 git 提交信息承载,禁止再写会话状态文件(见 doc-conventions 第 10 节)。`design/` 与根规则文件(`AGENTS.md`/`roadmap.md`/`待办清单.md`/`体验验证清单.md`)实现批禁写,见 §12
11. **文档同步闸(实现批禁写文档)**——实现批**禁写 `design/` 整个目录与根规则文件**,要往外交代的东西一律落 `reports/`:实现报告 `reports/iter<N>-实现报告-<日期>.md`(各卡状态+实机目检总清单+遗留读数义务)、代拍板追认单 `reports/iter<N>-代拍板-<日期>.md`、GDD 反哺点清单 `reports/iter<N>-反哺点-<日期>.md`(每条写清哪个文件哪一节、改成什么、依据是什么)。设计权威文档(GDD/art-bible)**任何批都不直改**:用户在会话中逐点裁决后,由工程/文档设计改动批(直改类)写入 `design/`(执行入口=doc-design 技能),并把反哺条目从 `reports/` 清掉(吸收即死;退役执行=batch-closure 技能)。机械面文档(roadmap 行/术语表/README 工具注)同样归工程/文档设计改动批在合并前更新。反哺点未落地期间相关 GDD 节视为待反哺,读前先查 `reports/` 与待办清单;需求卡片必列「关联文档同步面」按两层标注
11. **文档同步闸(实现批禁写文档)**——实现批**禁写 `design/` 整个目录与根规则文件**,要往外交代的东西一律落 `reports/`:实现报告 `reports/iter<N>-实现报告-<日期>.md`(各卡状态+实机目检总清单+遗留读数义务+实现决定记录——超白名单/超卡片明列范围事项逐条记「决了什么/为什么/代价/撤销方式」,全部按卡执行时只写一行「零拍板」)、GDD 反哺点清单 `reports/iter<N>-反哺点-<日期>.md`(每条写清哪个文件哪一节、改成什么、依据是什么)。设计权威文档(GDD/art-bible)**任何批都不直改**:用户在会话中逐点裁决后,由工程/文档设计改动批(直改类)写入 `design/`(执行入口=doc-design 技能),并把反哺条目从 `reports/` 清掉(吸收即死;退役执行=batch-closure 技能)。机械面文档(roadmap 行/术语表/README 工具注)同样归工程/文档设计改动批在合并前更新。反哺点未落地期间相关 GDD 节视为待反哺,读前先查 `reports/` 与待办清单;需求卡片必列「关联文档同步面」按两层标注
12. **实机目检归用户,只登记不阻塞**——真人检测项登记进实现报告目检总清单与体验验证清单即完成批内义务;禁把等目检当停工理由或完成前置
13. **中间产物吸收即死**——细则见 AGENTS.md 硬性红线与 doc-conventions 第 11 节
14. **改动级验收闭合**——写卡期列需求侧对照表,实现期补实际对照表(测试文件:行),每个行为改动做撤销证明;合回前独立验收审计。细则=test-conventions §8
+1 -2
View File
@@ -8,8 +8,7 @@
|---|---|---|
| `需求卡片-<批名>-<日期>.md` | 一个需求单位的实施文档(roadmap 迭代行里的「卡①②③」是需求单位,需求卡片是它的展开):目标与完成定义/设计事实源/现状事实/契约/范围边界/任务卡/验收闸/代拍板白名单/待裁点 | 写卡段(`req-card` 技能) |
| `提案-*`/`需求澄清-*`/`审计-*`/`评估-*` | 设计讨论段的过程稿:提案备选案与淘汰依据、需求澄清结论、调研与审计读数。被需求卡片或 GDD 当裁决源引用时在册;结论落进权威文档后即可删,删它不需要再裁(§11 吸收即死) | 设计讨论段 |
| `iter<N>-实现报告-<日期>.md` | 各任务卡状态、实机目检总清单、遗留读数义务 | 迭代批 |
| `iter<N>-代拍板-<日期>.md` | 批内 agent 替你拍的决定清单,等你追认或推翻 | 迭代批 |
| `iter<N>-实现报告-<日期>.md` | 各任务卡状态、实机目检总清单、遗留读数义务、实现决定记录(超白名单/超卡片明列范围事项的备案节,细则见 process-conventions §3 第 11 条) | 迭代批 |
| `iter<N>-反哺点-<日期>.md` | 需要写进 `design/` 权威文档的点,逐条列清"哪个文件哪一节、改成什么、依据是什么" | 迭代批 |
| `iter<N>-验收审计-<日期>.md` | 独立验收审计结果:逐行对照表核对、撤销证明抽查、未过项与例外及依据 | 独立审计方(未参与实现) |
| `iter<N>-<交付物名>-<日期>.md` | 需求卡片点名的其它交付物(例:`iter27-探针迁移对照-2026-10-14.md`=11 个探针的成员依赖面清单,已随迭代 27 收尾退役) | 迭代批 |
+1 -1
View File
@@ -23,7 +23,7 @@ from pathlib import Path
ROOT = Path(__file__).resolve().parent.parent
# 1) 顶层目录白名单(点开头目录一律忽略)
# reports/:迭代实现报告/代拍板追认单/GDD 反哺点
# reports/:迭代实现报告/GDD 反哺点
# 清单的家——迭代批禁写 design/,只准往这里写,design/ 全目录对它只读。只放 .md,不放图(图像白名单不含此目录)。
TOP_DIRS = {"archive", "artwork", "design", "game", "sim-data", "tools", "reports"}
# 2) 根目录文件白名单