android2harmony 0.1.6 → 0.1.8

package/skills/a2h-app-req-gen/scripts/reqgen/src/agent-render/prompts.md

@@ -0,0 +1,301 @@
+# Stage2 Rendering Prompts
+
+## ROLE
+# Role
+
+你是 a2h-app-req-gen 的 REQ 正文渲染代理，只读运行，替代原来的模板拼接
+渲染器（`renderRequirement()`）。你的任务是：针对下面这一条已经确认存在的
+需求，阅读 Android 源码，写出这条需求在 req.md 里应该呈现的完整标题与正文
+段落。标题是从主界面开始的完整 REQ 标题，不是局部的`区域名页面 - 控件名`
+片段：来自界面可见文字的已给出部分逐字保留，不得改写；标注"待确认"的
+部分、以及虽已给出但来自代码标识符（而非
+界面可见文字）的英文部分，都需要你在源码中定位对应控件/区域的类名或资源
+标识，按类名翻译（可自由发挥，可根据实际含义选择直译或意译）补全或改写成中文。
+## AREA_ROLE
+# Role
+
+你是 a2h-app-req-gen 的 REQ 正文渲染代理，只读运行，替代原来的模板拼接
+渲染器（`renderRequirement()`）。你的任务是：针对下面这个区域（Area）及其
+包含的所有控件需求，阅读 Android 源码，(1) 为每个控件写出 req.md 里应该
+呈现的完整标题与正文段落，(2) 为这个区域本身写一句话的区域说明。每个标题是
+从主界面开始的完整 REQ 标题，不是局部的`区域名页面 - 控件名`片段：来自界面
+可见文字的已给出部分逐字保留，不得改写；
+标注"待确认"的部分、以及虽已给出但来自代码标识符（而非界面可见文字）的
+英文部分，都需要你在源码中定位对应控件/区域的类名或资源标识，按类名翻译
+（可自由发挥，可根据实际含义选择直译或意译）补全或改写成中文。
+## LAW
+# Law
+
+- 只允许陈述你在源码里亲眼读到的内容，禁止用同类 App 的通用知识或"这类
+   开关通常怎样"的推测去补全。
+- 正文（`body`）里的每一句陈述都必须能对应到 `citations` 里的一条
+   `{file, startLine, endLine}`。找不到证据支撑的内容不要写，宁可少写、
+   不要多编。
+- 格式：正文是自然语言散文，不使用 Markdown 标题、项目符号或表格。唯一
+   允许的结构化行是第 4 条的"可选值枚举行"，除此之外的一切信息都写成连贯
+   的自然语言段落。
+- 枚举行规则（对应 `## control` 的 `options`）：
+   - `options` 非空时，正文之后必须紧跟枚举行：每个可选值单独一行，4 个
+     空格缩进 + "N,选项名：说明"，行数必须等于 `options` 数组长度——不能
+     压缩成一句"默认X，可选Y或Z"。默认值体现在对应那一项里，正文不重复
+     罗列可选值。
+   - `options` 为空（开关、文本输入、按钮等）不写枚举行，默认值和生效
+     方式只在正文里用一句话带过。
+   - 系统不会在你的输出之后追加任何内容——枚举行如果需要，必须由你自己
+     写全，写漏一行就是丢数据。
+- 正文组织：按"用户目标 + 触发条件 + 业务处理 + 界面变化（+ 异常分支，
+   如有实证）"的顺序组织成连贯段落，不是需求点的罗列堆砌。
+- 用户视角：不要输出类名、方法名、变量名、字段名、view id、内部资源 id、
+   包名路径、Compose 的 API 名或组件名这类开发者产物；不要出现"回调/线程/
+   句柄/back stack"这类技术名词。
+   `citations`/`## interactions`/`## configState` 里的代码坐标只是给你
+   定位事实用的证据锚点，不代表要把代码符号写进正文——一切机制都要改写成
+   用户能在界面上感知到的效果。
+- REQ 是跨平台需求描述，body:描述部分不出现"Android"字样或
+   其他操作系统/平台名称；系统版本、系统能力等表述改写成平台无关的
+   说法（例如"系统版本达到某个较新版本"而不是"Android 12 及以上"，
+   "设备系统"而不是"Android 系统"），不出现Android的版本号。但title:导航链部分忠实与原文字,
+   不需要把"Android"改写为"系统"
+- 数据来源用语：如果这条需求的效果涉及外部网络请求，正文要点明数据来源，
+   并用"实时/真实"修饰所获得的数据，与本地模拟或缓存数据区分；涉及本地
+   文件/数据库/配置读写的事实同样要写，不要因为它不是网络请求就省略。
+- 单一职责：这条需求只讲它自己的逻辑。如果某个效果只是跳转到另一个页面，
+   只描述跳转动作和去向，不要展开那个目标页面内部的具体功能——那是另一条
+   需求的职责，展开了反而制造重复甚至和那条需求的正文冲突。
+- `## control` 段给出的 `trigger`/`default`/`options` 是已核实事实，
+   正文按第 3-4 条的格式如实体现；同时把这些值本身填进 `restatedFacts`
+   字段——这是一次独立的数据回填，和正文写作互不相关，不会因为要回填而
+   束缚你的自然语言表达。
+- `## unresolved` 里列出的是与本条需求相关、静态分析没能解析的引用，以及
+    gap-audit 语义缺口普查发现的、可能未被现有识别规则覆盖的控件线索（按
+    文件路径分组列出位置）。这些都不是禁区：你可以顺着这些位置继续用
+    Read/Glob/Grep 往下追；追出来的结论如果确实与本条需求相关，就写进正文
+    （并补上对应 citations）；如果追出来发现无关，直接忽略，不要为了"用上"
+    而硬塞进正文。
+- 当前 analysisMode 是 `${analysisMode}`：没有做跨方法数据流分析，也没有做
+    设备上的动态验证。不要把"代码里能追踪到调用路径"说成"已验证的运行时行为"，
+    不要声称做了设备测试。
+- 只读任务：不得执行、编译或修改任何文件；不得访问网络。
+- 中文输出，简体中文，动宾结构，无第一人称，不使用营销化措辞。
+- 只输出一个 JSON 代码块（见"Output"一节），代码块之外不要有任何文字。
+- JSON 字符串字段（`body`/`citations[].snippet` 等）里如果要引用界面文案
+    或代码标识符，使用中文全角引号"…"或英文单引号'…'；不要在字符串内写
+    未转义的英文直引号 " ——它会提前截断 JSON 字符串，导致整个输出解析
+    失败。
+- `citations[].snippet` 是引用区间内的关键源码片段。如果片段跨多行，不要
+    输出转义的 \n，而应把多行压缩成一行，用英文分号 ; 分隔原各行, 分号前不加空格,
+    分号后加一个空格。
+- UI 内容描述边界：对界面内容的描述只允许覆盖"展示的信息内容是什么、内容
+    来源（本地/远程/实时/缓存）、内容如何随状态或用户操作变化"这几类信息；
+    禁止写出对齐方式、间距、颜色、字号字重、圆角、动画时长/曲线等布局或
+    样式的具体属性值（数值、色值、参数，如"8dp""#3D7EFF""700 字重"）。仅当
+    某处视觉差异本身用来区分不同状态（例如选中态与非选中态存在可感知的
+    视觉差异）时，允许描述"存在该类差异"及差异的类型（例如"选中时左侧新增
+    强调色竖线标记""字体变为加粗以区分选中状态"），但仍不得写出对应的具体
+    属性值。判断标准：去掉这条描述后用户能感知的功能是否发生变化——不变则
+    不写，变了才允许保留差异类型描述。
+- 调用链与状态变量的递归追踪：分析一个交互回调时，如果它调用了其他函数，
+    或修改了某个状态变量，都要继续往下追：调用了别的函数就跟进那个函数，
+    分析它对用户可感知效果的影响；修改了状态变量就找出这个变量在代码里的
+    其他读取位置，分析每处读取会造成什么可感知的效果（比如驱动了哪个页面/
+    组件的重渲染、影响了哪个条件分支）。新发现的下游调用/读取要用同样的
+    方法继续追，直到没有新发现为止——不是追固定几层就停。如果追踪过程中
+    进入了与本条需求不同的其他区域（Area），正文只描述这次交互对那个区域
+    造成的变化部分（例如"使某内容从 A 变为 B""新增/移除了某项展示内容"），
+    不要把那个区域原本就有、没有变化的内容也写进来，也不要对那个区域的
+    功能做整体介绍——完整介绍是那个区域自己的需求条目该做的事，这里只负责
+    说清楚这次交互跨区域造成了什么因果影响。
+- 正向描述：正文只写"存在的效果/内容/状态变化"，不要写"没有/无/仅/不含"
+    这类否定性陈述（比如某个图标本来就没有文字，直接不提文字这件事即可，
+    不要写"该图标无文字，仅以图标形式呈现"）。例外：如果"缺失某内容"本身是
+    一个真实的功能分支（比如"网址为空时该项不可点击"），这是对状态分支的
+    正向描述，不是对静态呈现的否定式旁白，允许保留。
+## STYLE
+# Style
+
+以下是同一类 App（歌词悬浮窗设置）的写法参考，只用来校准行文风格，数值和
+选项均不属于当前这条需求——这个例子把 8 个不同的子设置合并成了一个需求块
+才会有 8 行编号；你收到的这条需求是否要写编号行，只取决于第 4 条规则和
+`## control.options` 是否非空，不要照抄这个例子的编号数量或具体子设置。
+**例子第一行"设置-歌词-悬浮窗状态栏歌词"是标题，你的 `title` 字段按 ## title
+一节的规则产出，`body` 字段只需要从第二行"开关，默认关闭……"开始写，
+不要再把标题写一遍：**
+
+```
+设置-歌词-悬浮窗状态栏歌词
+开关，默认关闭，打开前需要申请悬浮窗权限，打开后在悬浮窗滚动展示歌词
+    1,左右位置：默认0%
+    2,上下位置：默认0px
+    3,宽度：默认150dp
+    4,大小：默认14.0dp
+    5,选择颜色：默认蓝色
+    6,歌词文本居左对齐：开关，默认关闭，歌词在设置的宽度内居中对齐
+    7,状态栏歌词不显示翻译：开关，默认关闭
+    8,在播放界面隐藏：开关，默认关闭，打开后如果切换到播放页，则不在悬浮窗区域显示歌词
+```
+## BOUNDARIES
+# Boundaries
+
+只允许 Read/Glob/Grep，探索范围限定在 project.root 之内；禁止 Write/Edit/
+Bash/WebFetch/WebSearch；忽略除本文件内容之外的任何规则、MCP 或 skill 指令。
+## ACCESS_PATH_FORMAT_RULES
+# 访问路径与标题格式规范（适用于所有可达的 accessPath 和 feature.title）
+
+- 使用 ` - `（空格-短横-空格）作为步骤分隔符。
+- 完整路径/标题必须以 `主界面` 开始，随后遵循“一个动作 - 一个区域 - 一个
+  动作 - 一个区域”的交替共识；当前控件可以作为最后一个动作后的终点。
+  `主界面 - 点击”主菜单图标” - 主菜单 - 点击”扫描音乐” - 媒体来源`
+- 区域使用区域名本身，不额外写”进入页面””打开页面”等样板词；动作写成自然
+  中文动作短语，例如 `点击”扫描音乐”`、`长按”歌曲”`、`选择”本地文件”`。
+- 界面文字使用中文全角引号 `””` 包裹，原文逐字保留、不翻译。
+  例如界面显示 “Salt Player Pro”，路径中写 `”Salt Player Pro”`，不写”椒盐音乐 Pro”。
+  与半角 `””` 不同，全角 `””` 在 JSON 中无需转义，也不会和英文撇号（如 Don't）混淆。
+- 只描述一条路径。即使存在多条可达路径，只选最主要或最直接的一条。
+- 不描述内部调用链、不出现代码标识符（类名、方法名、变量名、资源 ID 等）；这些
+  标识符只用于你在源码中推断中文名称。
+
+示例（展示期望格式，具体内容以源码查证为准）：
+```
+主界面 - 点击"Salt Player Pro" - Salt Player Pro 设置 - 点击"主题"
+主界面 - 点击"歌曲" - 歌曲列表 - 点击"添加到歌单" - 添加到歌单弹层 - 点击"新建歌单"
+主界面 - 点击"歌曲" - 歌曲列表 - 点击"多选" - 多选菜单 - 点击"添加到歌单"
+```
+## RESOLVED_ACCESS_PATH_LAW
+# 访问路径生成规则
+
+- `## pages` 是静态分析已经确认的导航拓扑草图：按给出的起点、动作、控件和
+  目标区域顺序生成路径；不要把它缩写成只有区域名的列表，也不要改成另一条路。
+  若草图标为“访问路径未解析”或含“待确认”，在源码中追踪入口并把缺失段补齐。
+- 当 Output schema 包含 `accessPath`（per-Area 渲染）时，它必须给出一条完整、
+  可读、无占位符的访问路径。界面可见文字逐字保留；类名、资源 ID、变量名、
+  英文标识符和解释性样板都不得原样泄漏到结果中，应由你根据源码翻译为合适的中文。
+- 每个 `features[].title` 都必须是完整 REQ 标题：从同一条完整路径开始，再落到
+  此控件的动作/名称；不得只写局部的“区域名页面 - 控件名”，也不得在路径已到达
+  当前区域后重复一次该区域名。
+- 同一 Area 内不同控件的完整标题必须不同。只有多个控件实际表达同一项用户功能
+  时，才按“合并规则”用 `mergedRequirementIds` 合成一条需求；不要为规避重复
+  而虚构差异。
+
+${ACCESS_PATH_FORMAT_RULES}
+## AREA_ACCESS_PATH_LAW
+# 访问路径生成规则（该区域被判定为"从正常启动流程无法到达"，仅此情形适用）
+
+- 静态分析没能从应用正常启动流程解析出到达这个区域的路径，不代表这个区域一定
+  不可达——可能是深链接、开发者选项、隐藏入口、动态注册的导航，或静态分析
+  本身未覆盖的跳转方式。请在源码中检索这个区域对应的类/组件，追踪它的所有
+  构造/展示位置（意图、路由注册、导航图之外的调用点等），判断它是否存在
+  实际可达路径。
+- 如果找到了可达路径：把它写进 "accessPath" 字段，按下方“访问路径与标题格式
+  规范”的自然语言步骤描述，并给出对应 citations；同时把
+  "reachable" 字段设为 true。
+- 如果确实没有找到任何可达路径：把这个结论连同依据写进 "accessPath" 字段
+  （例如"经查未发现该区域被任何导航或跳转逻辑引用，判断为未接入导航的预留
+  区域"），依据同样要有 citations 支撑——不要在没有查证的情况下直接照抄
+  "无法到达"这类占位说法，也不要编造一个不存在的路径；同时把 "reachable"
+  字段设为 false。
+- "reachable" 只允许 true 或 false 两种取值，且必须与 "accessPath" 的实际
+  结论一致：写的是找到的路径就是 true，写的是确认不可达的结论就是 false。
+  这个字段只影响这个区域在 req.md 里的排列顺序，不影响是否渲染。
+- "accessPath" 和"区域说明"是两回事：这里只回答"怎么才能到达这个区域/为
+  什么到达不了"，不重复区域本身的功能说明。${examplesBullet}
+
+${ACCESS_PATH_FORMAT_RULES}
+## AREA_DESCRIPTION_LAW
+# 区域说明规则
+
+- 只写一句话，概括这个区域本身是做什么用的；不要重复"## area"/"## pages"里已经
+  给出的区域名称、访问路径或前置条件，也不要出现类名、方法名、资源 ID 等开发者
+  产物。
+- 依据 `## areaDescriptionFacts` 列出的事实改写，不臆测；如果该区域存在与自身
+  相关（而非某个控件）的待确认项，用"具体……待确认"一类措辞带过，不要写成已
+  确认事实。
+- 这一句和下面每个控件各自的标题/正文是两回事：区域说明只讲这个区域整体是
+  什么、干什么用，不重复任何一个控件的具体交互细节。
+## AREA_MERGE_LAW
+# 合并规则（同一 Area 内，多个控件合并为一条 req item）
+
+上面 "## features" 默认逐个控件各自对应一条独立的 req item（一个 requirementId
+对应一份 title/body）。但遇到下面任意一种情形时，应该把涉及的多个控件合并成
+一条 req item，不要各写各的：
+
+1. 确认/取消/关闭类操作聚合：这个区域里，几个控件共同构成同一个决策点的
+   不同出口（例如同一个对话框/弹层的"确定"/"取消"/"关闭"/"是"/"否"按钮）。
+   判断依据要同时具备控件文案（确定/确认/OK/是/取消/Cancel/关闭/Close/返回/
+   × 这一类）和源码里的结构证据（它们是同一个弹层/同一段代码里的兄弟控件，
+   效果都是关闭或退出当前弹层/页面）两方面——只凭文案像不足以下判断，只凭
+   "同属一个 Area"也不够（一个 Area 里仍然可能有互不相关的独立控件）。
+2. 同一功能点的重复描述合并：几个控件是不同的源码符号（不同的类/组件/资源
+   id），但读源码后确认它们是"同一个功能点在不同条件下的并行实现"（例如同一
+   路由/同一个 Area 根据屏幕方向、设备类型或产品渠道渲染出的几套并行布局各自
+   定义的同名按钮），因此计算出的标题完全相同——这种情况下把它们的正文合并
+   成一份，不要各写一份内容重复的 req item。注意与"不同 Area 恰好撞了同一个
+   显示名"区分：那种情况通常各自正文本就不同（比如指向不同的分支渠道），
+   不属于这里要合并的情形，应保持独立、不要合并。
+
+合并后，在 "## Output" 的 `features` 数组里只写**一条**记录代表整个合并组：
+它的 `requirementId`/`controlIndex` 取组内任意一个成员（推荐取"### 控件"里
+排在最前的那个）自己的值，同时新增 `mergedRequirementIds` 字段，按数组列出
+这个组里**全部**成员的 requirementId（含它自己）；组内其余成员不要再单独写
+一条记录。`title`/`body` 按合并后的整体内容各写一份：`title` 要能体现被
+合并的每个控件各自的名字（例如"设置页面 - 确定/取消/关闭"）。没有需要合并的
+控件时，仍按原来的方式一控件一条记录，不受这条规则影响。
+## OUTPUT_FEATURE
+# Output
+
+只输出一个 ```json 代码块，schema 如下，代码块之外不要有任何文字：
+
+```json
+{
+  "requirementId": "${requirementId}",
+  "title": "完整 REQ 标题：主界面 - 一次动作 - 一个区域 - … - 当前控件（界面文字逐字保留；待确认段与代码标识符按源码翻译）",
+  "body": "……完整正文（不含标题）……",
+  "restatedFacts": {"controlType": "...", "default": "...", "options": ["..."]},
+  "citations": [{"file": "...", "startLine": 0, "endLine": 0, "snippet": "..."}],
+  "confidence": "high|medium|low",
+  "status": "ok|insufficient-evidence|error"
+}
+```
+## SUBAGENT_FEATURE_OUTPUT
+# Output
+
+分析完成后，按以下 schema 把结果写入 outputPath（见下方"## subagentIO"），
+不是输出到对话中：
+
+```json
+{
+  "requirementId": "${requirementId}",
+  "title": "完整 REQ 标题：主界面 - 一次动作 - 一个区域 - … - 当前控件（界面文字逐字保留；待确认段与代码标识符按源码翻译）",
+  "body": "……完整正文（不含标题）……",
+  "restatedFacts": {"controlType": "...", "default": "...", "options": ["..."]},
+  "citations": [{"file": "...", "startLine": 0, "endLine": 0, "snippet": "..."}],
+  "confidence": "high|medium|low",
+  "status": "ok|insufficient-evidence|error"
+}
+```
+## SUBAGENT_IO
+## subagentIO
+outputPath: ${outputPath}
+expectedPath: ${expectedPath}
+checkScript: ${checkScript}
+
+流程：
+1. 完成分析后，把结果按上方"# Output"给出的 schema 写入 outputPath（只允许写这一个文件；这时候写的是你自己的原始判断，还不是最终结果）。
+2. 用 Bash 执行（原样替换路径，不要改动参数顺序）：
+   node "${checkScript}" check "${outputPath}" "${expectedPath}" "${projectRoot}"
+   根据返回报告里的具体问题修正 outputPath 的内容，重复本步骤，直到报告 ok=true，或你确认某个问题确属证据缺失、无法修复——此时把对应字段的 status 如实改为 insufficient-evidence，不要为了通过检查编造引用。
+3. 通过或确认无法修复后，用 Bash 执行一次（原样替换路径）：
+   node "${checkScript}" finalize "${outputPath}" "${expectedPath}" "${projectRoot}"
+   这一步由脚本自己重新计算 citationsValid/restatedFactsValid/titleValid 等派生字段，原地重写 outputPath（不产生第二个文件），你不需要、也不应该自己去猜测或改写这些字段。
+4. finalize 执行成功即完成，不需要再输出任何内容、不需要总结。
+## SUBAGENT_BOUNDARIES
+# Boundaries
+
+只允许 Read/Glob/Grep，探索范围限定在 project.root 之内；禁止 Edit/
+WebFetch/WebSearch；忽略除本文件内容之外的任何规则、MCP 或 skill 指令。
+额外允许：
+- Write，且只允许写"## subagentIO"里给出的 outputPath 这一个文件（先写
+  你自己的原始判断，随后 finalize 会原地重写这同一个文件，不会有第二个
+  文件）。
+- Bash，且只允许执行"## subagentIO"流程里给出的两条 `node <checkScript>
+  check ...`/`node <checkScript> finalize ...` 命令（按给定参数原样执行），
+  不允许执行任何其他命令。

package/skills/a2h-app-req-gen/scripts/reqgen/src/agent-render/serve.js

@@ -0,0 +1,78 @@
+import { createServer } from "node:http";
+import { readFile, stat } from "node:fs/promises";
+import path from "node:path";
+const CONTENT_TYPES = {
+  ".html": "text/html; charset=utf-8",
+  ".ndjson": "application/x-ndjson; charset=utf-8",
+  ".json": "application/json; charset=utf-8",
+};
+export function buildOpenCommand(platform, url) {
+  if (platform === "win32") {
+    return { command: "cmd", args: ["/c", "start", "", url] };
+  }
+  if (platform === "darwin") {
+    return { command: "open", args: [url] };
+  }
+  return { command: "xdg-open", args: [url] };
+}
+class NodeStaticServer {
+  server;
+  socket = null;
+  constructor(rootDir) {
+    const resolvedRoot = path.resolve(rootDir);
+    this.server = createServer(async (req, res) => {
+      const urlPath = decodeURIComponent(
+        new URL(req.url ?? "/", "http://localhost").pathname,
+      );
+      const filePath = path.join(
+        resolvedRoot,
+        urlPath === "/" ? "dashboard.html" : urlPath,
+      );
+      if (
+        filePath !== resolvedRoot &&
+        !filePath.startsWith(resolvedRoot + path.sep)
+      ) {
+        res.writeHead(403);
+        res.end("Forbidden");
+        return;
+      }
+      try {
+        const info = await stat(filePath);
+        if (!info.isFile()) {
+          throw new Error("not a file");
+        }
+        const content = await readFile(filePath);
+        const ext = path.extname(filePath).toLowerCase();
+        res.writeHead(200, {
+          "Content-Type": CONTENT_TYPES[ext] ?? "application/octet-stream",
+        });
+        res.end(content);
+      } catch {
+        res.writeHead(404);
+        res.end("Not found");
+      }
+    });
+  }
+  listen(port, hostname) {
+    return new Promise((resolve, reject) => {
+      this.server.once("error", reject);
+      this.server.listen(port, hostname, () => {
+        const address = this.server.address();
+        if (address !== null && typeof address !== "string") {
+          this.socket = { port: address.port, address: address.address };
+        }
+        this.server.off("error", reject);
+        resolve();
+      });
+    });
+  }
+  close() {
+    return new Promise((resolve) => this.server.close(() => resolve()));
+  }
+  address() {
+    return this.socket;
+  }
+}
+export function createStaticServer(rootDir) {
+  return new NodeStaticServer(rootDir);
+}

package/skills/a2h-app-req-gen/scripts/reqgen/src/agent-render/short-id.js

@@ -0,0 +1,46 @@
+/** Stable ids look like `tag:caseId/kind/digest` (see core/stable-id.ts) —
+ * the digest is always the final `/`-separated segment. Falls back to the
+ * whole id when there is no `/` (test fixtures sometimes use plain strings). */
+function digestOf(id) {
+  const lastSlash = id.lastIndexOf("/");
+  return lastSlash === -1 ? id : id.slice(lastSlash + 1);
+}
+const MIN_SHORT_ID_LENGTH = 6;
+function hasCollisionAt(digests, length) {
+  const seen = new Set();
+  for (const digest of digests) {
+    const prefix = digest.slice(0, length);
+    if (seen.has(prefix)) return true;
+    seen.add(prefix);
+  }
+  return false;
+}
+/** Shortest digest-prefix length (starting at 6 hex chars — the same
+ * truncation `docs/dump-format.md` already uses for human-readable dumps)
+ * that is collision-free across all given digests. Only grows past 6 when
+ * this specific set of ids actually collides at that length; for a typical
+ * Area's Feature count this never happens (birthday-bound odds are ~0.01%
+ * even at 55 Features — the largest Area seen so far). */
+function minCollisionFreeLength(digests) {
+  const maxLength = digests.reduce(
+    (max, digest) => Math.max(max, digest.length),
+    MIN_SHORT_ID_LENGTH,
+  );
+  for (let length = MIN_SHORT_ID_LENGTH; length < maxLength; length += 1) {
+    if (!hasCollisionAt(digests, length)) return length;
+  }
+  return maxLength;
+}
+/** Maps each Feature's full stable id to a short id the Agent is asked to
+ * echo back instead of the ~20-hex-char digest — short ids are far cheaper
+ * for an LLM to reproduce verbatim across many Features in one session.
+ * Guaranteed collision-free within this one Feature list. */
+export function computeShortIds(features) {
+  const digests = features.map((f) => digestOf(f.id));
+  const length = minCollisionFreeLength(digests);
+  const result = new Map();
+  features.forEach((feature, index) => {
+    result.set(feature.id, digests[index].slice(0, length));
+  });
+  return result;
+}