cgraphx 2.0.1 → 2.0.3

package/dist/.claude-template/skills/write-delivery-guide/template-change-type.md

@@ -0,0 +1,120 @@
+# 场景模板:改动型
+
+本文件是 `write-delivery-guide` 的「改动型」形态场景模板——统一六项结构:判断特征 / 故事线主轴 / 讲解维度要求 / 图表类型 / 完整参考案例 / 常见讲错。生成交付讲解时 Read 本文件并照此生成。
+
+> ⚠️ **本模板参考案例为拟真案例,待真实使用替换**(第一次真实改动交付后,用实际生成的讲解替换参考案例,并借此校准本模板六项)。
+
+## 判断特征
+
+- diff 以修改/删除既有代码为主(不是以新增文件为主);
+- 触碰既有流程:状态机、既有接口行为、既有任务/事件的逻辑;
+- spec 中表述为「修改/调整既有行为」,常伴随兼容性说明与需保留行为清单。
+
+## 故事线主轴
+
+**原流程中的部位**:先讲改动前的原故事线(读者已有的心智地图),再标出改动落在第几步。读者关心的第一问题是「改在我熟悉的流程的哪里」,不是「改了几个文件」。
+
+## 讲解维度要求
+
+1. **原流程全景**:改动前的完整故事线,高亮改动部位;
+2. **前后对比**:之前什么样 → 现在什么样(两边各一句话逻辑 + 关键代码位置);
+3. **为什么改**:来自 spec / 任务上下文,一句话;
+4. **波及范围**:谁会受影响——逐个判断调用方、相关场景、定时任务、数据,列成表;
+5. **什么没变**:显式列出需保留的行为(取自 spec「需保留行为」),让接收者确认既有行为安全;
+6. 改动的组件按四问展开(见 SKILL.md 通用规则)。
+
+## 图表类型
+
+全景与改动定位用 flowchart / stateDiagram,改动部位用虚线或标注高亮;前后对比可用表格辅助。
+
+## 完整参考案例
+
+> 拟真案例(待真实使用替换):
+
+---
+
+# 交付讲解:订单状态机加入退款分支
+
+## 1. 30 秒看懂
+
+给订单流程加了一条退款分支:订单支付完成后可以进入 REFUNDING,退款处理完毕回到 PAID 或终态 REFUNDED。只改了状态机的流转部位,下单与支付流程不变。
+
+## 2. 全景(高亮改动部位)
+
+```mermaid
+flowchart LR
+    A[下单 CREATED] --> B[支付 PAID]
+    B --> C[发货 SHIPPED]
+    B --> D[关单 CLOSED]
+    B -. 本次新增 .-> E[退款中 REFUNDING]
+    E -. 取消 .-> B
+    E -. 成功 .-> F[已退款 REFUNDED]
+```
+
+## 3. 场景故事线:原流程与改动部位
+
+**原流程**(改动前):下单 → 支付 → {发货 | 关单}——PAID 之后只能去 SHIPPED / CLOSED。
+
+**改动部位**:在「支付完成」这个环节之后,插入一条退款分支(上图虚线)。其余环节不变。
+
+**为什么改**:业务要求支持支付后退款(spec:订单在发货前允许申请退款)。
+
+## 4. 组件挂接(改动涉及的组件)
+
+### `OrderStateMachine` — 状态流转注册(核心改动)
+
+- **何时用**:任何推动订单状态的入口(支付回调、发货、关单、新增的退款入口)都会经过它
+- **做什么**(改动后):PAID 的合法后继从 {SHIPPED, CLOSED} 扩为 {SHIPPED, CLOSED, REFUNDING};新增 REFUNDING 的两条出边(退款成功 → REFUNDED,退款取消 → 回 PAID)
+- **用了之后使什么成为可能**:退款入口可以合法推动订单进入退款中
+- **挂点**:各状态变更入口 → 本组件 → 下游按状态分发的逻辑
+- 代码:`OrderStateMachine.java:45-67`(改动前仅 45 行的两条注册)
+
+### `OrderCloseJob` — 关单定时任务(适配改动)
+
+- **何时用**:定时扫描超时未发货订单并关单(既有任务,本次只加过滤)
+- **做什么**(改动后):扫描 PAID 超时订单时**排除 REFUNDING**——退款中的订单不应被关单
+- **用了之后使什么成为可能**:新分支不会误伤既有关单逻辑
+- **挂点**:定时触发 → 本任务 → 订单置 CLOSED
+- 代码:`OrderCloseJob.java:30`
+
+## 5. 改动定位:前后对比与波及
+
+| | 之前 | 现在 |
+|---|---|---|
+| PAID 可流转到 | SHIPPED / CLOSED | SHIPPED / CLOSED / **REFUNDING** |
+| REFUNDING 流转到 | —(无此状态) | 退款成功 → REFUNDED;退款取消 → 回 PAID |
+
+**波及范围**(逐个判断):
+
+| 受影响方 | 影响 |
+|---|---|
+| `OrderCloseJob` 关单定时任务 | 原扫描「所有 PAID 状态订单」——现在必须排除 REFUNDING,否则会把退款中的订单关掉(已处理) |
+| 订单列表页状态筛选 | 需要新增 REFUNDING 枚举展示(本次只交付后端枚举与接口返回,前端后续需求) |
+| 发货流程 | 不受影响——SHIPPED 前置仍是 PAID,退款分支是并行岔路不是串行 |
+
+**什么没变**:下单、支付回调、发货流程、关单规则(除排除 REFUNDING 外)。
+
+## 6. 已验证与已知边界
+
+- 已验证:PAID → REFUNDING → REFUNDED;退款取消回 PAID;关单任务不再误关 REFUNDING 订单。
+- 已知边界:部分退款本次不支持(业务确认 v1 砍掉)。
+
+## 7. 导读入口
+
+以上任何一节都可以追问,例如:
+
+- 「为什么退款取消回到 PAID,而不是单独加一个状态?」
+- 「除了关单任务,还有哪些地方扫描 PAID 状态?」
+- 「REFUNDING 中的订单,用户再次下单/再次支付会被拦截吗?」
+
+---
+
+(参考案例完)
+
+## 常见讲错
+
+- ❌ 只列改动的文件/函数,不把它放回原流程——接收者找不到改动部位;
+- ❌ 只讲新逻辑,不讲原来是什么样——没有前后对比就看不出「改了什么」;
+- ❌ 漏波及范围——不讲哪些调用方/定时任务/场景受影响;
+- ❌ 全景图不高亮改动范围——接收者误以为整条流程都变了;
+- ❌ 不讲「什么没变」——接收者无法确认既有行为是否安全。

package/dist/.claude-template/skills/write-delivery-guide/template-multi-role-flow.md

@@ -0,0 +1,148 @@
+# 场景模板:多角色流程
+
+本文件是 `write-delivery-guide` 的「多角色流程」形态场景模板——统一六项结构:判断特征 / 故事线主轴 / 讲解维度要求 / 图表类型 / 完整参考案例 / 常见讲错。生成交付讲解时 Read 本文件并照此生成。
+
+## 判断特征
+
+- 交付包含服务不同角色的多个接口/入口(如申请人 / 审批人 / 管理员);
+- 流程有明确环节,环节之间有状态流转(草稿 → 已提交 → 通过/拒绝 之类);
+- spec 中有角色、环节、状态流转章节。
+
+## 故事线主轴
+
+**角色 × 环节**:谁在第几步干什么。读者的心智索引是「那条用户提交、管理员审批的流程」,不是「那 6 个接口」——先给故事,接口挂在故事环节上。
+
+## 讲解维度要求
+
+1. **故事线表**:环节 / 谁 / 干什么 / 入口,一步一行;
+2. **一次完整走查**:至少一个带真实角色与数据的请求走查(故事式);
+3. **状态流转讲透**:哪个接口把状态从哪推到哪、哪个状态驱动哪个接口可见(如待办列表由 PENDING 驱动)——这是多角色流程最容易漏的暗线;
+4. **角色边界**:哪些接口属于哪个角色、谁能看见什么;
+5. 每个接口按四问展开(见 SKILL.md 通用规则)。
+
+## 图表类型
+
+全景节用 flowchart(按角色分组);故事线可用 sequenceDiagram;状态流转用 stateDiagram。
+
+## 完整参考案例
+
+以下是「审批流」交付的讲解全文(真实交付场景)。生成时模仿它的结构与讲解深度:
+
+---
+
+# 交付讲解:审批流
+
+## 1. 30 秒看懂
+
+给系统加了一条完整的「申请人发起 → 管理员审批」链路:申请人创建并提交审批,管理员在待办里看到并处理,通过后触发下游流程,拒绝后申请人可修改重提。本次交付全部为新增代码,未改动既有逻辑。
+
+## 2. 全景
+
+```mermaid
+flowchart LR
+    subgraph A1[申请人]
+        A11[创建草稿] --> A12[提交审批]
+    end
+    subgraph M1[管理员]
+        B11[待办列表] --> B12[查看详情] --> B13{通过 / 拒绝}
+    end
+    A12 -->|状态 PENDING| B11
+    B13 -->|通过 APPROVED| C[下游通知/回调]
+    B13 -->|拒绝 REJECTED| A11
+```
+
+本次交付覆盖上图全部环节(均为新增)。
+
+## 3. 场景故事线:审批流(角色:申请人 / 管理员)
+
+| 环节 | 谁 | 干什么 | 入口 |
+|---|---|---|---|
+| 1 | 申请人 | 创建审批草稿 | `POST /approvals/draft` |
+| 2 | 申请人 | 提交,进入审批流程 | `POST /approvals/{id}/submit` |
+| 3 | 管理员 | 待办列表看到这条审批 | `GET /approvals/todo` |
+| 4 | 管理员 | 查看审批详情 | `GET /approvals/{id}` |
+| 5 | 管理员 | 通过或拒绝 | `POST /approvals/{id}/approve` / `reject` |
+
+**一次审批走查**:张三要请假——先创建草稿(状态 DRAFT,可反复修改),确认后提交 → 状态变为 PENDING,系统给管理员生成一条待办 → 管理员李四打开待办列表看到「张三 · 请假」→ 点进详情查看 → 点通过:状态 APPROVED,张三收到通知,下游考勤流程触发;若拒绝:状态 REJECTED,张三可修改草稿后重新提交(回到环节 1)。
+
+## 4. 组件挂接
+
+### `POST /approvals/draft` — 创建草稿(环节 1)
+
+- **何时用**:申请人开始填写审批时;无前置
+- **做什么**:创建一条审批记录,状态初始化为 DRAFT
+- **用了之后使什么成为可能**:草稿可反复修改、可提交(解锁环节 2)
+- **挂点**:(入口)→ 本接口 → submit
+- 副作用:`approval` 表 +1 行
+- 代码:`ApprovalController.java:32` → `ApprovalService.createDraft()`
+
+### `POST /approvals/{id}/submit` — 提交(环节 2)
+
+- **何时用**:申请人填完草稿、要正式进入流程;前置:草稿存在且状态 = DRAFT
+- **做什么**:校验必填 → 状态 DRAFT → PENDING → 给管理员生成待办
+- **用了之后使什么成为可能**:这条审批出现在管理员待办列表(解锁环节 3)
+- **挂点**:draft → 本接口 → 管理员待办
+- 副作用:`approval.status` 变更、`todo` 表 +1 行、发通知
+- 代码:`ApprovalService.java:58`
+
+### `GET /approvals/todo` — 待办列表(环节 3)
+
+- **何时用**:管理员打开待办页;须有审批权限
+- **做什么**:查出本管理员权限范围内状态为 PENDING 的审批,返回列表
+- **用了之后使什么成为可能**:管理员选择一条去处理(解锁环节 4)
+- **挂点**:submit → 本接口 → 详情
+- 关键点:列表由状态 = PENDING 驱动——是 submit 让数据出现在这里
+- 代码:`ApprovalQueryController.java:21`
+
+### `GET /approvals/{id}` — 查看详情(环节 4)
+
+- **何时用**:管理员处理前看审批内容;前置:对该条有可见权限
+- **做什么**:返回审批完整内容 + 附件信息 + 当前状态
+- **用了之后使什么成为可能**:管理员能做出通过/拒绝决策(解锁环节 5)
+- **挂点**:待办列表 → 本接口 → approve/reject
+- 代码:`ApprovalQueryController.java:44`
+
+### `POST /approvals/{id}/approve` — 通过(环节 5a)
+
+- **何时用**:管理员决定通过;前置:状态 = PENDING 且有审批权限
+- **做什么**:状态 PENDING → APPROVED → 移除待办 → 触发下游(通知 + 业务回调)
+- **用了之后使什么成为可能**:审批生效,下游业务被触发
+- **挂点**:详情 → 本接口 → 下游流程
+- 副作用:`approval.status` 变更、`todo` 删行、发事件
+- 代码:`ApprovalService.java:87`
+
+### `POST /approvals/{id}/reject` — 拒绝(环节 5b)
+
+- **何时用**:管理员决定拒绝;前置同通过
+- **做什么**:状态 PENDING → REJECTED → 移除待办 → 记录拒绝原因 → 通知申请人
+- **用了之后使什么成为可能**:申请人可修改草稿后重新提交(回到环节 1)
+- **挂点**:详情 → 本接口 → 申请人修改重提
+- 代码:`ApprovalService.java:112`
+
+## 5. 改动定位
+
+(本次交付全部为新增,未改动既有流程,此节省略。有改动已有流程时按改动型模板生成。)
+
+## 6. 已验证与已知边界
+
+- 已验证:提交 → 通过 → 下游触发全链路;拒绝 → 修改重提;待办列表由 PENDING 状态驱动。
+- 已知边界:审批撤回本次不支持(业务已确认砍掉);会签/加签在下一期。
+
+## 7. 导读入口
+
+以上任何一节都可以追问,例如:
+
+- 「为什么待办列表依赖 PENDING 状态,而不是单独维护一张待办表?」
+- 「连续点两次通过会怎样(幂等)?」
+- 「通过时触发的下游回调失败了怎么办?」
+
+---
+
+(参考案例完)
+
+## 常见讲错
+
+- ❌ 按接口清单逐个列协议,没有故事线——接收者无法重建场景;
+- ❌ 只讲参数返回值,不讲何时用、谁触发;
+- ❌ 漏掉状态流转暗线——没讲哪个状态驱动待办/可见性接口;
+- ❌ 不标角色边界——分不清哪些接口是申请人的、哪些是管理员的。

package/dist/.claude-template/skills/write-unit-test-code/SKILL.md

@@ -40,6 +40,8 @@ description: 基于 write-unit-test-spec 产出的测试规格文档 + 已有实
 
 ## 流程
 
+**前置(每次执行,先于步骤 1):读测试规范** `docs/guides/testing-standards.md` —— 约束步骤 4 测试文件产出:测试目录与命名(规范「目录与命名(偏离项)」优先于测试规格的骨架映射)、框架与文件后缀、Mock 政策与 fixture 组织、单测/集成边界。**缺失 → 中断,提示用户先跑 `/init-project-guides` 补齐**,用户明确表示不需要规范才可继续——不对齐项目约定的测试代码,合并时全是返工。
+
 ### 1. 前置检查
 
 - 确认 `docs/features/<feature-id>/<前缀>-单元测试-spec.md` 存在。**不存在 → 报错退出**:"找不到测试规格,请先跑 /write-unit-test-spec"。不现场派生场景。
@@ -66,21 +68,36 @@ description: 基于 write-unit-test-spec 产出的测试规格文档 + 已有实
 
 ### 4. 产出测试文件(断言填实)
 
-写到 `<项目测试目录>/<feature-id>.test.ts`(或项目约定的命名/后缀,从测试规格的"骨架映射"节读取)。形态:
+写到 `<项目测试目录>/<feature-id>.test.ts`(命名/后缀:测试规范「目录与命名(偏离项)」优先,其次测试规格的"骨架映射"节)。形态:
 
 - 实现已就绪的场景 → `describe` + `it`(含真实断言,基于读到的签名写,能真跑)
 - 实现缺失的场景 → `it.skip` + `// TODO: 实现提供后填实` 占位
 - import 被目标(已存在的模块直接 import;不存在的标 TODO 注释,不强行 import)
-- 框架(vitest/jest/...)和文件后缀按项目约定
+- 框架(vitest/jest/...)和文件后缀按测试规范,规范未写按项目既有约定
 - 已有同模块测试文件 → 文件名加后缀避免覆盖(如 `<feature-id>.补充.test.ts`),在报告里提示"已有 X,是否合并由用户判断"
 
-**AI 自己发挥的空间**:fixture / mock 怎么组织、describe 嵌套多深、断言写多细,agent 按既有测试风格判断,不强加模板。
+**AI 自己发挥的空间**:fixture / mock 怎么组织、describe 嵌套多深、断言写多细——测试规范有约定按约定(Mock 政策 / fixture 组织),未约定处 agent 按既有测试风格判断,不强加模板。
 
 ### 5. 跑测试验证 + 产出测试报告
 
 跑一次项目的测试命令(如 `npm test`),确认新写的测试能跑(通过或失败都行,失败说明实现有 bug 或测试断言写错)。
 
-**产出单元测试报告**,写到 `docs/features/<feature-id>/<前缀>-单元测试报告.md`。结构轻量,至少包含:
+**产出单元测试报告**,写到 `docs/features/<feature-id>/<前缀>-单元测试报告.md`。头部直接写入(测试人取 `git config user.name`,不问用户),正文结构轻量,至少包含:
+
+**头部样例**:
+
+```markdown
+# 单元测试报告: <需求名称>
+
+> feature-id: <feature-id>
+> 测试人: <git config user.name>
+> 测试时间: <YYYY-MM-DD>
+> 关联测试规格: <前缀>-单元测试-spec.md
+> 关联被测实现: <实现代码路径,多个逐行列出>
+> 关联测试代码: <测试文件路径;补充测试文件一并列出>
+> 测试框架: <如 JUnit 4.13.2 + Mockito / vitest 2.x>
+> 运行时: <如 JDK 17.0.19(homebrew openjdk@17)/ Node v22.x>
+```
 
 - 测试概况:总数 / 通过 / 失败 / 跳过(it.skip 占位)/ 时长
 - 逐场景详细结果:每个 `it` 的通过/失败/跳过 + 入参 + 执行过程 + 断言判定 + 失败原因(如有)
@@ -193,7 +210,7 @@ it.skip('权限不足应返回 403', () => {
 | 产物 | 路径 | 形态 |
 |---|---|---|
 | 测试文件 | `<项目测试目录>/<feature-id>.test.ts` | describe + `it`(断言填实) / `it.skip`(实现待补) |
-| 单元测试报告 | `docs/features/<feature-id>/<前缀>-单元测试报告.md` | 测试概况 + 逐场景结果 + 偏差小结 + 下一步建议 |
+| 单元测试报告 | `docs/features/<feature-id>/<前缀>-单元测试报告.md` | 头部溯源(测试人/时间/关联产物/环境)+ 测试概况 + 逐场景结果 + 偏差小结 + 下一步建议 |
 
 ## 边界场景
 
@@ -211,7 +228,7 @@ it.skip('权限不足应返回 403', () => {
 - 不修实现代码(失败如实报告)
 - 不假装通过(断言不调到假绿)
 - 不引入硬 gate(precommit hook / 提交拦截)
-- 不假设测试框架(从测试规格的骨架映射读,或运行时探测)
+- 不假设测试框架(从测试规范、测试规格的骨架映射读,或运行时探测)
 - 不改 write-unit-test-spec / implementation / write-plan(它们对本 skill 零依赖)
 
 ## 和其他 skill 的关系

package/dist/core/code/engine/cli/analyze-config.js

@@ -0,0 +1,320 @@
+"use strict";
+/**
+ * Project-local `.cgraphrc` support for `cgraph analyze` (#243).
+ *
+ * Lets a repository commit recurring `analyze` defaults — embedding knobs,
+ * worker tuning, registry naming — so contributors don't re-pass the same
+ * flags on every run. Design rules:
+ *
+ *   - Config is repo-local (`.cgraphrc` at the resolved repo root). It is NOT
+ *     read from `.cgraphx/code/` because that directory is index storage and is
+ *     commonly gitignored.
+ *   - JSON only. No YAML, no `package.json` field, no global `~/.cgraphx/code`
+ *     file in this pass.
+ *   - CLI flags always override config (see {@link mergeAnalyzeOptions}).
+ *   - Fail closed: unknown keys, wrong value types, and invalid JSON all throw
+ *     {@link GitNexusRcError} so a typo never silently no-ops. Errors are
+ *     actionable and surface before any expensive analysis.
+ *   - Config values never reach a shell. Strings are validated against control
+ *     and hidden/bidirectional characters.
+ *
+ * Both a flat shape and a nested `analyze` block are accepted:
+ *
+ *     { "pdg": true, "workerTimeout": 60 }
+ *     { "analyze": { "pdg": true } }
+ *
+ * When both set the same option, the nested `analyze` block wins (deterministic,
+ * documented precedence).
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GitNexusRcError = exports.CGRAPH_RC_FILENAME = void 0;
+exports.validateBranchName = validateBranchName;
+exports.sanitizeDetectedBranch = sanitizeDetectedBranch;
+exports.loadAnalyzeConfig = loadAnalyzeConfig;
+exports.mergeAnalyzeOptions = mergeAnalyzeOptions;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+exports.CGRAPH_RC_FILENAME = '.cgraphrc';
+/** Git refs longer than this are almost certainly a mistake / injection attempt. */
+const BRANCH_MAX_LENGTH = 255;
+/**
+ * Thrown for any `.cgraphrc` problem (missing-file is NOT an error — it
+ * returns `undefined`). The message is user-facing and names the file so the
+ * CLI can print it verbatim before starting the progress bar.
+ */
+class GitNexusRcError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'GitNexusRcError';
+    }
+}
+exports.GitNexusRcError = GitNexusRcError;
+/** Allowed `.cgraphrc` keys and how each maps onto `AnalyzeOptions`. */
+const KEY_SPECS = {
+    name: { target: 'name', kind: 'string' },
+    allowDuplicateName: { target: 'allowDuplicateName', kind: 'boolean' },
+    maxFileSize: { target: 'maxFileSize', kind: 'numeric-string' },
+    workerTimeout: { target: 'workerTimeout', kind: 'numeric-string' },
+    walCheckpointThreshold: { target: 'walCheckpointThreshold', kind: 'numeric-string' },
+    workers: { target: 'workers', kind: 'numeric-string' },
+    // #1589/#1852 residual — extra fetch-wrapper function names to treat as HTTP
+    // consumers. The auto-detector only flags functions that call the bare global
+    // `fetch()`; a wrapper built on axios / a custom client, or named outside the
+    // built-in convention set, is otherwise invisible to route_map consumers.
+    // Listing it here adds it to the cross-file consumer scan.
+    fetchWrappers: { target: 'fetchWrappers', kind: 'string-array' },
+};
+/** Top-level container key for the nested form; not itself an `AnalyzeOptions` field. */
+const NESTED_KEY = 'analyze';
+const ALLOWED_KEYS_HINT = `Allowed keys: ${Object.keys(KEY_SPECS).join(', ')} (or a nested "${NESTED_KEY}" object).`;
+/**
+ * Reject control characters and hidden / bidirectional Unicode in a string
+ * value. These have no legitimate place in a branch name, registry name, or
+ * device string, and would otherwise let a committed config smuggle invisible
+ * controls into downstream consumers.
+ */
+const isHiddenOrControl = (codePoint) => codePoint < 0x20 ||
+    codePoint === 0x7f ||
+    (codePoint >= 0x200b && codePoint <= 0x200f) || // zero-width + LRM/RLM
+    (codePoint >= 0x202a && codePoint <= 0x202e) || // bidi embeddings/overrides
+    (codePoint >= 0x2060 && codePoint <= 0x2064) || // word-joiner + invisible math
+    (codePoint >= 0x2066 && codePoint <= 0x206f) || // bidi isolates + deprecated
+    codePoint === 0xfeff; // BOM / zero-width no-break space
+const assertNoHiddenChars = (value, source) => {
+    for (const ch of value) {
+        const cp = ch.codePointAt(0);
+        if (cp !== undefined && isHiddenOrControl(cp)) {
+            throw new GitNexusRcError(`${source}: value contains control or hidden/bidirectional characters, which are not allowed.`);
+        }
+    }
+};
+/**
+ * Validate a user-supplied branch name (from CLI or `.cgraphrc`). Returns the
+ * trimmed name or throws {@link GitNexusRcError}. Conservative but accepts the
+ * shapes real branches use (`feature/foo-bar`, `release/1.2`, `develop`).
+ */
+function validateBranchName(value, source) {
+    const trimmed = value.trim();
+    if (!trimmed) {
+        throw new GitNexusRcError(`${source}: branch name must not be empty.`);
+    }
+    if (trimmed.length > BRANCH_MAX_LENGTH) {
+        throw new GitNexusRcError(`${source}: branch name is too long (max ${BRANCH_MAX_LENGTH}).`);
+    }
+    assertNoHiddenChars(trimmed, source);
+    if (/\s/.test(trimmed)) {
+        throw new GitNexusRcError(`${source}: branch name must not contain whitespace.`);
+    }
+    // git ref-name rules (subset): reject characters git itself forbids in refs.
+    if (/[~^:?*[\\]/.test(trimmed)) {
+        throw new GitNexusRcError(`${source}: branch name contains characters not allowed in a git ref (~ ^ : ? * [ \\).`);
+    }
+    if (trimmed.startsWith('-')) {
+        throw new GitNexusRcError(`${source}: branch name must not start with "-".`);
+    }
+    if (trimmed.includes('..')) {
+        throw new GitNexusRcError(`${source}: branch name must not contain "..".`);
+    }
+    // Git permits a backtick in a ref, but branch labels surface in user-facing
+    // messages and registry metadata; a backtick is rejected at this single
+    // chokepoint so all tiers (CLI flag, auto-detect via sanitizeDetectedBranch)
+    // are covered (#1996 tri-review P1).
+    if (trimmed.includes('`')) {
+        throw new GitNexusRcError(`${source}: branch name must not contain a backtick.`);
+    }
+    return trimmed;
+}
+/**
+ * Best-effort validation for an auto-detected branch (from git). Never throws —
+ * returns `undefined` for anything unusable so the resolver falls back to the
+ * next precedence tier.
+ */
+function sanitizeDetectedBranch(value) {
+    if (!value)
+        return undefined;
+    try {
+        return validateBranchName(value, 'detected branch');
+    }
+    catch {
+        return undefined;
+    }
+}
+const normalizeValue = (kind, value, key) => {
+    const source = `${exports.CGRAPH_RC_FILENAME} "${key}"`;
+    switch (kind) {
+        case 'boolean':
+            if (typeof value !== 'boolean') {
+                throw new GitNexusRcError(`${source} must be a boolean (true/false).`);
+            }
+            return value;
+        case 'string': {
+            if (typeof value !== 'string') {
+                throw new GitNexusRcError(`${source} must be a string.`);
+            }
+            const trimmed = value.trim();
+            if (!trimmed) {
+                throw new GitNexusRcError(`${source} must not be empty.`);
+            }
+            assertNoHiddenChars(trimmed, source);
+            // `name` flows into registry metadata and user-facing messages, so a
+            // Markdown-significant character is rejected (#1996 tri-review P1). `_`
+            // is intentionally allowed (legitimate in repo names). embeddingDevice
+            // (the other `string`-kind option) only ever holds a fixed device token,
+            // so this guard never rejects a valid value there.
+            if (/[`*[\]<>]/.test(trimmed)) {
+                throw new GitNexusRcError(`${source} must not contain Markdown-significant characters (\` * [ ] < >).`);
+            }
+            return trimmed;
+        }
+        case 'string-array': {
+            // Generic shared validator — `source` already names the config key, so
+            // messages here stay key-agnostic (no fetch-wrapper coupling in the
+            // shared normalizer; #1589/#1852 review F7).
+            if (!Array.isArray(value)) {
+                throw new GitNexusRcError(`${source} must be an array of strings.`);
+            }
+            const names = [];
+            for (const item of value) {
+                if (typeof item !== 'string') {
+                    throw new GitNexusRcError(`${source} entries must all be strings.`);
+                }
+                const trimmed = item.trim();
+                if (!trimmed) {
+                    throw new GitNexusRcError(`${source} entries must not be empty.`);
+                }
+                assertNoHiddenChars(trimmed, source);
+                // Values may be interpolated into a RegExp downstream. Restrict to
+                // identifier / member-access shapes so a config value can never smuggle
+                // regex metacharacters into a consumer.
+                if (!/^[A-Za-z_$][A-Za-z0-9_$.]*$/.test(trimmed)) {
+                    throw new GitNexusRcError(`${source} entry "${trimmed}" must be an identifier or member name ` +
+                        `(letters, digits, _, $, . — e.g. "client.get").`);
+                }
+                names.push(trimmed);
+            }
+            if (names.length === 0) {
+                throw new GitNexusRcError(`${source} must list at least one string.`);
+            }
+            // De-duplicate and cap to a sane bound so a pathological config cannot
+            // blow up the consumer scan's alternation.
+            return Array.from(new Set(names)).slice(0, 100);
+        }
+        case 'numeric-string': {
+            // Mirror Commander's contract: these options reach the existing CLI
+            // validation as strings. Accept a JSON number or a string; normalize to a
+            // string and let the downstream per-flag validation enforce ranges so the
+            // error messages stay in one place.
+            if (typeof value === 'number') {
+                if (!Number.isFinite(value)) {
+                    throw new GitNexusRcError(`${source} must be a finite number.`);
+                }
+                return String(value);
+            }
+            if (typeof value === 'string') {
+                const trimmed = value.trim();
+                if (!trimmed) {
+                    throw new GitNexusRcError(`${source} must not be empty.`);
+                }
+                return trimmed;
+            }
+            throw new GitNexusRcError(`${source} must be a number or numeric string.`);
+        }
+        default:
+            // Exhaustive — kept for forward-compat if a new kind is added.
+            throw new GitNexusRcError(`${source}: unsupported config value kind.`);
+    }
+};
+/**
+ * Normalize one level (flat top-level or the nested `analyze` block) into a
+ * partial `AnalyzeOptions`. Rejects unknown keys (and, defensively, two keys
+ * that map onto the same option at the same level).
+ */
+const normalizeLevel = (obj, { allowNestedKey }) => {
+    const out = {};
+    const setBy = new Map();
+    for (const [key, value] of Object.entries(obj)) {
+        if (allowNestedKey && key === NESTED_KEY)
+            continue; // handled separately
+        // `Object.hasOwn`, not a truthiness check: a plain-object lookup like
+        // `KEY_SPECS["__proto__"]` returns an inherited member (Object.prototype,
+        // truthy) and would slip past `if (!spec)`, hitting the wrong error branch
+        // instead of the documented "Unknown key" message (#1996 tri-review P3).
+        if (!Object.hasOwn(KEY_SPECS, key)) {
+            throw new GitNexusRcError(`Unknown key "${key}" in ${exports.CGRAPH_RC_FILENAME}. ${ALLOWED_KEYS_HINT}`);
+        }
+        const spec = KEY_SPECS[key];
+        const prev = setBy.get(spec.target);
+        if (prev && prev !== key) {
+            throw new GitNexusRcError(`${exports.CGRAPH_RC_FILENAME}: "${prev}" and "${key}" both configure the same option; set only one.`);
+        }
+        setBy.set(spec.target, key);
+        out[spec.target] = normalizeValue(spec.kind, value, key);
+    }
+    return out;
+};
+/**
+ * Locate, read, parse, validate, and normalize `.cgraphrc` at `repoRoot`.
+ *
+ * @returns the normalized config defaults, or `undefined` when no file exists
+ *          (the normal case). Throws {@link GitNexusRcError} on any problem.
+ */
+function loadAnalyzeConfig(repoRoot) {
+    const filePath = node_path_1.default.join(repoRoot, exports.CGRAPH_RC_FILENAME);
+    let raw;
+    try {
+        raw = node_fs_1.default.readFileSync(filePath, 'utf-8');
+    }
+    catch (err) {
+        if (err?.code === 'ENOENT')
+            return undefined;
+        throw new GitNexusRcError(`Could not read ${exports.CGRAPH_RC_FILENAME}: ${err.message}`);
+    }
+    // Strip a leading UTF-8 BOM: Node's 'utf-8' decode keeps it, and JSON.parse
+    // then fails with a confusing "Unexpected token" on an otherwise-valid file
+    // (#1996 tri-review). Only one leading BOM is stripped; in-string control
+    // rejection still applies to the parsed values.
+    if (raw.charCodeAt(0) === 0xfeff)
+        raw = raw.slice(1);
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        throw new GitNexusRcError(`${exports.CGRAPH_RC_FILENAME} is not valid JSON: ${err.message}. ` +
+            `Expected a JSON object such as {"pdg": true, "workerTimeout": 60}.`);
+    }
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw new GitNexusRcError(`${exports.CGRAPH_RC_FILENAME} must contain a JSON object.`);
+    }
+    const obj = parsed;
+    const flat = normalizeLevel(obj, { allowNestedKey: true });
+    let nested = {};
+    if (Object.prototype.hasOwnProperty.call(obj, NESTED_KEY)) {
+        const nestedRaw = obj[NESTED_KEY];
+        if (nestedRaw === null || typeof nestedRaw !== 'object' || Array.isArray(nestedRaw)) {
+            throw new GitNexusRcError(`${exports.CGRAPH_RC_FILENAME} "${NESTED_KEY}" must be a JSON object.`);
+        }
+        nested = normalizeLevel(nestedRaw, { allowNestedKey: false });
+    }
+    // Nested `analyze` block overrides flat top-level keys for the same option.
+    return { ...flat, ...nested };
+}
+/**
+ * Merge CLI options over `.cgraphrc` defaults. CLI wins whenever it provides a
+ * value — including an explicit `false` (so an explicit CLI off-switch beats a
+ * config `true`). Config fills only the genuinely-unset (`undefined`) options.
+ */
+function mergeAnalyzeOptions(cli, config) {
+    if (!config)
+        return cli;
+    const merged = { ...cli };
+    for (const key of Object.keys(config)) {
+        if (merged[key] === undefined) {
+            merged[key] = config[key];
+        }
+    }
+    return merged;
+}