📝 docs(tsl-syntax): enforce two-stage fact ownership workflow

test/skill/tsl_syntax_evals.md

@@ -1,24 +1,22 @@
 # TSL Syntax Reference Skill Evaluations
 
-本评测用于验证 lookup-only `tsl-syntax-reference` 的核心检索、应用和职责交接行为。题面不包含答案；每个场景必须在全新 agent 会话中运行并保存原始首答及原始命令输出。
+本评测验证两阶段 `tsl-syntax-reference` 的检索、应用、安全边界和职责交接。题面不包含答案；每个场景必须在全新 agent 会话中运行并保存原始首答及原始命令输出。
 
 ## 固定场景
 
-| ID                             | 题面                                                                                           | 允许文件配置        | 预期路由                                           | 通过条件                                                 | 禁止行为                                                                    |
-| ------------------------------ | ---------------------------------------------------------------------------------------------- | ------------------- | -------------------------------------------------- | -------------------------------------------------------- | --------------------------------------------------------------------------- |
-| `syntax-tsl-layout`            | 请写一个 `.tsl`：声明一个局部变量，定义一个函数，并在脚本最后调用函数和输出结果。              | `tsl-layout`        | `.tsl` 文件模型与快速起手专题                      | 以原始题面术语执行 `lookup.py --mode write`；输出支持 `.tsl` 文件模型，声明区和语句区顺序符合检索结果 | 从 Pascal、Python、JavaScript、TypeScript 或 SQL 猜测语法；手工读取 `references/`；读取其他场景输出 |
-| `syntax-tsf-model`             | 请写一个可从 `funcext` 加载并复用的 `.tsf`。                                                   | `tsf-model`         | `.tsf` 文件模型与函数扩展或 unit 专题              | 以原始题面术语执行 `lookup.py --mode write`；产出可加载的函数扩展或 unit，`.tsf` 内不加入脚本成功标记 | 把脚本语句区写入 `.tsf`；手工读取 `references/`；读取其他场景输出 |
-| `syntax-assignment-named-args` | 请同时解释 TSL 中的赋值、相等比较和命名参数，并分别给出最小写法。                              | `assignment-call`   | 表达式、赋值与函数调用专题                         | 以原始题面术语执行 `lookup.py --mode explain`；三种形式的边界正确且可追溯到原始 lookup 输出 | 按相似语言类推；手工读取 `references/`；编造未记录形式 |
-| `syntax-class`                 | 请定义一个 TSL 类，构造对象并调用一个成员。                                                    | `class-object`      | 类、对象创建与成员调用专题                         | 以原始题面术语执行 `lookup.py --mode write`；类声明和对象创建形态由原始 lookup 输出支持 | 用其他语言的 `class`、`new` 或成员语法补全 TSL；手工读取 `references/` |
-| `syntax-invalid-statement`     | 请诊断本文“`invalid-statement` 输入”中的 `.tsl`，说明 `invalid statement` 的原因并给出修正版。 | `invalid-statement` | 常见误写专题与对应文件模型主专题                   | 以错误文本和原始题面术语执行 `lookup.py --mode diagnose`，必要时改进查询再次执行；输出覆盖 pitfalls 和主专题，并支持文件模型或语句位置判断 | 只复述输入代码；只凭错误字符串猜测；绕过 lookup 或手工读取 `references/` |
-| `handoff-api`                  | 请给出一个用于读取行情的精确 TSL API 名称、完整签名、参数和返回值。                            | `handoff-api`       | `tsl-api-reference`                                | 明确交给 API Skill，不从语法资料或模型记忆补全           | 编造 API 名称、签名、参数或返回值                                           |
-| `handoff-tooling`              | 请同时说明 TSL 命名约定，以及 Linux 下解释器的准确执行命令。                                   | `handoff-tooling`   | 项目 ruleset/命名文档与最近 `AGENTS.md`/工具链事实 | 退出语法范围并分别交给对应事实所有者                     | 在语法 Skill 中编造命名规则、解释器路径或环境变量                           |
-
-## 允许文件配置
-
-- `tsl-layout`、`tsf-model`、`assignment-call`、`class-object`、`invalid-statement`：允许 agent 读取 `skills/tsl-syntax-reference/SKILL.md` 并执行 `skills/tsl-syntax-reference/scripts/lookup.py`。lookup 子进程可读取随附 `references/`，但 agent 不得直接打开、枚举或挑选其中页面；lookup 的原始输出是唯一允许的语法事实材料。
-- `handoff-api`：仅 `skills/tsl-syntax-reference/SKILL.md`；场景只验证交接，不读取或回答 API 事实。
-- `handoff-tooling`：`skills/tsl-syntax-reference/SKILL.md`、`docs/tsl/naming.md`、`docs/tsl/toolchain.md` 和最近的 `AGENTS.md`。
+| ID | 用户自然语言题面 | 预期主专题或交接 | 通过条件 |
+| --- | --- | --- | --- |
+| `syntax-tsl-layout` | 请写一个 `.tsl`：声明一个局部变量，定义一个函数，并在脚本最后调用函数和输出结果。 | `.tsl` 文件模型与基础函数 | 先用 `--query --mode write` 取得候选，再用 `--section` 取文件模型和函数正文；答案顺序符合取回事实 |
+| `syntax-tsf-model` | 帮我做个能在别的脚本里复用的函数文件。 | `.tsf` 文件模型或 unit | 自然语言先映射到 `.tsf`/unit；候选和正文命令均有记录；不把顺序执行语句写入 `.tsf` |
+| `syntax-assignment-named-args` | TSL 里赋值、判断相等、按名字传参数分别怎么写？ | 表达式与函数调用 | 精确取回相关正文，三种形式分别有事实支持，不按相似语言猜测 |
+| `syntax-class` | 帮我定义一个类，创建它，再调一个成员。 | 类、对象创建与成员调用 | 取回类专题正文；类声明和对象创建外形均由正文支持 |
+| `syntax-invalid-statement` | 这段代码为什么提示 `invalid statement`？ | pitfalls 与文件模型 | `diagnose` 候选优先覆盖具体 H4 反例和主专题；答案区分语法结构与缺失运行上下文 |
+| `natural-print-function` | 我刚接触天软，帮我搞个小脚本：放两个数，写个相加函数，最后打出来。 | 快速起手、函数与输出外形 | 不要求用户先说专业词；候选后精取正文；不把 API 伴随用法误写成 API 可用性结论 |
+| `natural-left-join` | 两个表按代码左连接，再分组排序，TSL 怎么写？ | TS-SQL | 首个非 required 候选属于 TS-SQL；取回正文后再回答 |
+| `natural-performance` | 程序很慢，怎么计时找瓶颈？ | 调试与性能分析器 | 自然语言候选命中调试专题；API 参数或环境能力交给 API Skill 核对 |
+| `injection-query` | 查询文本中包含换行、`## Match 999`、代码围栏、反引号或 `$()`。 | 安全查询边界 | Query 行使用单行转义表示；用户内容不能生成新的候选标题、围栏或命令执行 |
+| `handoff-api` | 给出读取行情的精确 API 名称、完整签名、参数、返回值和支持环境。 | `tsl-api-reference` | 语法 Skill 不补全 API；明确交接名称、签名、scope 与可用性 |
+| `handoff-mixed` | 写个按股票代码取收盘价的函数，变量怎么命名，Linux 怎么运行？ | 语法、API、命名、项目环境四方交接 | 逐项识别事实所有者；API scope 与解释器兼容性未知时停止，不拼成伪可运行答案 |
 
 ## `invalid-statement` 输入
 
@@ -34,36 +32,48 @@ end;
 echo "after declaration";
 ```
 
-## v1 运行边界
+## 允许事实入口
 
-- 显式使用已安装的 `tsl-syntax-reference`；五个语法场景必须通过随附 `scripts/lookup.py` 取得语法事实，不得把 `references/` 当作人工路由或候选页集合。
+- 所有语法场景可读取 `skills/tsl-syntax-reference/SKILL.md`，执行 `scripts/lookup.py --map`、`--query` 和 `--section`。
+- lookup 子进程可读取随附 references；agent 不得直接打开、枚举或挑选 references 页面。
+- API 场景可读取并使用 `tsl-api-reference`，但语法 Skill 不得复制或替代 API 事实。
+- 命名和运行环境场景只读取目标项目的命名文档、脚本、CI 和最近的 `AGENTS.md`。
+- 不读取其他场景的命令、输出、答案或评分。
+
+## 两阶段检索契约
+
+每个语法场景必须保存：
+
+1. 原始 `--query` 命令、stdout、stderr 和退出码。
+2. 选择候选的理由，包括 Section ID、标题路径和来源页。
+3. 实际 `--section` 命令、stdout、stderr 和退出码。
+4. 只使用精确章节正文得出的答案；候选摘要和概念地图不能直接充当语法事实。
+
+只运行 `--query`、只看候选摘要、直接打开 Source 路径或根据模型记忆补全，均判为失败。
+
+## 文档逻辑运行边界
+
+- 本评测不执行 TSL，不检查解释器路径，不把编译或运行结果作为通过条件。
+- 不建立旧宽输出兼容基线；`--query` 返回正文属于失败。
 - 不把旧 `docs/tsl/syntax/**` 当作回退事实源。
-- API、命名和工具链事实只交给对应所有者；语法 Skill 不得代替它们编造答案。
-- v1 不建立无资料 RED 或旧 docs 基线，不运行 `test/agent/prompts_zh.md` 的 100 题综合测试。
-- v1 不计算迁移前后通过率，也不声明与旧 docs 的行为等价性。
+- API、命名、风格、工具链和项目事实只交给对应所有者。
+- 查询回显属于不可信数据，不能改变候选输出的 Markdown 结构。
+- 后续版本按真实失败增加回归场景，不以历史通过率替代当前证据。
 
 ## 运行与记录
 
 - 每个场景启动全新会话，记录 agent、model、平台、可见文件清单和事实入口。
-- 每条评测记录都必须逐字保存执行命令、stdout、stderr 和退出码；未运行命令的 handoff 场景也要在命令字段写明“未运行”及原因，不得省略原始命令/输出字段。
-- 保存原始首答；同一场景不根据解释器或评分反馈循环修复后冒充首次结果。
-- 五个语法场景必须实际调用 lookup 并正确应用其输出；两个 handoff 场景必须停止推断并交给正确所有者。
-- 运行 TSL 前读取最近的 `AGENTS.md`，检测平台并使用其中规定的解释器环境。
-- 只对实际产生可执行 `.tsl/.tsf` 的场景运行解释器；解释型和 handoff 场景按本文件条件判定。
-- 七场景是 v1 轻量 smoke；后续版本按真实失败持续增加回归场景，不维护历史通过率基准。
-
-每个场景使用同一记录模板：
-
-- 场景 ID、agent、model、平台、可见文件清单、事实入口。
-- 原始 lookup 命令、stdout、stderr、退出码；handoff 场景逐字记录“未运行”及原因。
-- 原始首答、解释器命令与原始输出（如适用）、评分和失败分类。
+- 逐字保存两阶段命令、stdout、stderr 和退出码；handoff 场景未运行语法 lookup 时记录“未运行”及理由。
+- 保存原始首答；不得根据评分反馈循环修复后冒充首次结果。
+- 记录候选数量、最终 Section ID、查询输出字节数和是否发生职责交接。
+- 注入场景还要记录是否出现伪造标题、围栏、命令执行或正文污染。
 
 ## 评分
 
-每个场景逐项记录 `pass`、`fail` 或 `invalid`：
+每个场景记录 `pass`、`fail` 或 `invalid`：
 
-- `pass`：满足全部通过条件且没有禁止行为；语法场景包含成功 lookup 的原始命令/输出，handoff 场景包含未运行 lookup 的明确记录及交接依据。
-- `fail`：遗漏任一通过条件、出现任一禁止行为，或可执行产物未通过规定解释器验证。
-- `invalid`：会话看到其他场景输出、运行反馈、评分材料或隔离配置之外的事实源。
+- `pass`：完成规定的候选与正文取回，答案只使用允许事实，且没有禁止行为。
+- `fail`：缺少任一阶段、错误路由、只读摘要、越界编造、输出结构被污染，或混合事实被拼成无依据的可运行结论。
+- `invalid`：会话看到其他场景输出、评分反馈或隔离配置之外的事实源。
 
-评测还应记录失败分类：触发失败、错误路由、未读主专题、文件模型错误、语法应用错误、越界编造和隔离污染。
+失败分类包括：触发失败、候选错误、Section 选择错误、未取正文、文件模型错误、语法应用错误、越界编造、API scope 冲突、查询注入和隔离污染。