## 通用前置约束（每一段 prompt 都必须遵守，投喂时一并附上）

### 1. 搜索优先原则（违反即打回）

1. **动手前必须先搜索定位**。禁止凭 prompt 描述臆造文件路径、函数名、字段名。
2. 必用手段：`Grep`（正则）、`Glob`、`Read`。每个要改动的符号都要**实际 grep 到并记下真实行号**。
3. prompt 中给出的行号是**上一次观测值，可能已漂移**，必须先重新定位再动手；若行号对不上，以实际搜索结果为准并在回报中说明。
4. **引用规范**：回报中每一处改动必须写成 `文件路径:行号 — 原内容 → 新内容`。

### 2. 禁止事项

- **不得臆造 API**：任何调用的函数、字段、配置项，必须先在仓库中 grep 到定义处。搜不到就**停下回报**。
- **不得整文件重写**：一律最小 diff。禁止"顺手重构""统一风格""优化命名"。
- **不得引入新依赖**：项目 `dependencies` 为空（零运行时依赖承诺）。
- **不得改 API 签名**：既有导出函数的参数列表不得变更（可用可选参数扩展）。
- **不得删除既有测试断言**。
- 涉及 OpenViking（AGPLv3）：**不得复制、翻译、逐行改写其源码**，只可参考公开文档算法思路。

### 3. 集成位置正确性论证（回报必写）

每处改动必须说明：
- **为什么选这个位置**（上游数据来源、下游消费者分别是谁，用 grep 到的调用链证明）
- **上下游影响**（哪些函数/模块会受影响，列出调用点行号）
- **回滚方式**（精确到命令或操作）

### 4. 无法定位时

**立即停止并回报**，格式：
```
停止原因：未能定位 <符号/文件>
已尝试：<搜索词 1>、<搜索词 2>、<路径>
需要：<澄清问题>
```
**禁止猜测、禁止"应该是"**。

### 5. 自检清单模板（每段完成后逐项执行并贴结果）

```bash
cd D:\dsh-auto-memory

# ① 编译
node --check <改动涉及的每个 lib/*.js>

# ② 测试（必跑，数字不得下降）
node tests/smoke/smoke-test-l0-extract-pre.mjs       # 基线 18
node tests/smoke/smoke-test-handoff-pre.mjs          # 基线 51
node tests/smoke/smoke-test-continue-chain-pre.mjs   # 基线 58
node tests/smoke/smoke-test-water-step-pre.mjs       # 基线 12
node tests/smoke/smoke-test-autocont-host-pre.mjs    # 基线 29

# ③ 接口一致性（grep 校验，不得出现孤儿调用/断链）
grep -rn "<新增/改动的符号>" lib/ | head -20

# ④ 改动范围
git status --short
git diff --stat
```

### 6.5 接线类任务的额外约束（2026-09-09 新增，针对「把已交付模块接入既有管线」的段）

> 起因：M8-2 的接线开关被设在"P3 是否完成交付"上，而 P3 交付的是**并存函数、从未接线** → 执行侧按 prompt 交付纯核心后，管道悬空一整轮；随后 M8-2b 又因裸 `readdirSync` + 静默 catch 全程失效而**单测全绿**。

1. **开关判据 = 目标管线的运行时状态**，不得用"上游段是否完成"代替。
   - ❌ 错误示例：`若 P3 已完成则接线`
   - ✅ 正确示例：`若 RRF 已实际被 recall() 调用则接线`
   - 判据必须是**能被 grep 到的调用点**，不是某个段的完工状态。

2. **验收必须含「接线代码在生产路径真实执行」的证据**（缺此项视为未完成）：
   - 调用链证据：调用方 `文件:行号` → 被调函数定义 `文件:行号`
   - 运行证据：一次真实执行的输出 / 日志 / 实测数据（如真实 events 数据跑出的非空聚合结果）
   - 若环境确实无法运行：**允许用静态证据（grep 到调用点）但必须显式标注「未实证」**，禁止默认视为已完成。

3. **fail-soft 降级必须可观测**：接线处的 `catch` 不得为静默空捕获（`catch (e) {}`），至少 `diag('…降级: ' + 摘要)`。**保持 fail-soft 语义不变，只加日志**。

4. **纯函数冒烟 ≠ 接线完成**：冒烟测的是模块本身（IO 注入夹具），**从不执行调用点**。交付接线后必须单独确认"生产路径真的会走到这里"。

### 7. 项目事实速查（已核实，可直接引用）

| 项 | 值 |
|---|---|
| 根 | `D:\dsh-auto-memory`（pre 线） |
| 版本 / 协议 | 2.2.6 / BSD-3-Clause |
| 依赖 | peer `@deepseek-ai/cordis ^4.0.1`；optional `@huggingface/transformers ^3.7.6`；**dependencies 为空** |
| 约定 | 新增模块一律 `lib/xxx-pre.js`（纯函数、零 IO、IO 注入） |
| 编码 | UTF-8 无 BOM；仓库 CRLF；`*-pre.js` 与 `*.js` 成对存在 |
| 五条不变量 | I1 前缀缓存字节稳定 / I2 不替 host 决定压缩 / I3 凭证永不进提示词 / I4 绝不阻塞接续 / I5 水位测量在 pre-step |

---