@namewta/speculo 1.0.21 → 1.0.24

package/template/canonical/canonical-specdev-tickets.md

@@ -40,6 +40,12 @@ node 本地只读 Goal 控制器（不含于网页快照） --map specdev/change
 
 需要正式 Goal、多 change、迁移或跨票 Gate 时交给 “目标规划阶段”；少量线性票可从 map 按已授权范围调用 “实现阶段”。不得以“精简”为理由静默更换默认工具或少交付。
 
+## 工程义务与证据失效
+
+每票按实际影响列明真实生产消费者、接口两端、文档/升级说明、回归与模型可见输出的责任；删除测试要给出原风险在新测试中的承接。风险及证据选择使用 下方 `<evidence-and-verification>` 标签，失败状态使用 下方 `<ref-common-rules-error-handling>` 标签。工具定义或上下文变更才加载 下方 `<ref-common-rules-agent-experience>` 标签。
+
+将有关检查合并进负责该行为的 Ticket，不为每个检查项创建一票。documentation 仍用现有 kind，性能实施引用 R 的测量基线，不增加分类 schema。每票说明 base/head、配置、输入或 Skill 改变后哪些证据需重新验证。
+
 ## 原型证据
 
 可以引用已验证 LOGIC/UI 原型中的行为、边界与已确认决定，记录具体 locator 和验证证据；源码片段可承载设计选择，但不自动成为生产实现。未闭合高影响产品决定返回 G，S 综合已确认设计而不重新开启无关访谈。
@@ -109,6 +115,10 @@ node 本地只读 Goal 控制器（不含于网页快照） --map specdev/change
 
 已确认根因时，以 `specdev/changes/{change}/diagnosis.md` 的修复契约为依据；根因未知时先运行 “Bug 诊断阶段”。
 
+## 工程证据随行为切片
+
+把文档、失败恢复、真实入口与回归检查放入拥有该行为的票，不逐检查项拆票制造交接。复杂迁移保留 Expand → Migrate → Contract 的真实顺序和旧数据核对；低风险文档继续使用现有 documentation kind。
+
 </decomposition-rules>
 
 <ticket-readiness>
@@ -164,6 +174,10 @@ status: ready
 
 未通过时保持 `ready: false`，并在未决问题、阻塞原因或偏差记录中写明原因。
 
+## 适用工程义务
+
+Ready 前确认真实调用方、文档/升级说明、正常与失败验证、恢复条件和证据失效条件。删除测试有风险承接；性能票有测量基线和真实用户操作；文档票分清纯说明与可见行为。缺少 required 验证不因工具暂不可用而标 ready。
+
 </ticket-readiness>
 
 <ticket-template>
@@ -324,6 +338,10 @@ E2E 由实际跨边界行为与风险决定，不限于 UI；required 模式不
 - **检查点：** 记录源版本、绑定摘要、已完成步骤、Evidence 和未闭合动作；恢复前回读。
 - **完成出口：** 全部适用验收及实际 Skill 证据通过，再将结果交回 Goal；未完成项明确列出。
 
+## 工程验收补充（适用时）
+
+列明真实消费者/入口、文档和升级说明、错误后的状态保证、恢复责任、旧测试的风险承接，以及代码/输入/配置/Skill 变化时需重验的证据。性能票引用用户操作与基线；documentation 票区分纯说明与模型/用户可见变化。无关项写不适用及理由，不逐项另造 Ticket。
+
 </ticket-template>
 
 <tickets-map-template>
@@ -599,6 +617,12 @@ W 的 `specdev/changes/{change}/initiative.json` 只拥有候选 change 的边
 - P：specdev/changes/{change}/prototypes/LOGIC-NNN/logic.md 记录逻辑模型与浏览器证据；index.html 是可运行原型，ready 时 hash 与记录一致。
 - 来源更新：specdev/changes/{change}/source.md 冻结后保持不变。T 将后续读取写入 specdev/changes/{change}/sources/SRC-###.md，记录 replaces、固定 SHA/hash、完整性和原 locator，triage 正文选择有效快照；不得把新远程事实自动升级为已接受 Spec。
 
+## 专业分支的证据归属
+
+R.performance 的测量卡、原始样本引用和优化候选仍由 architecture-review 拥有，不直接修改生产代码。I.documentation 修改获批项目文档并在原本票或 Direct Spec Evidence 保存验证；不另造文档状态。D.evidence-triage 在 diagnosis 的现象/事件节记录观察、未知与下一检查；它不是已经接受的根因或修复合同。具体记录见 下方 `<ref-common-rules-engineering-evidence>` 标签。
+
+代码、运行证据可以证明计划尚未实现或已过时，但不能改写用户目标。ADR 记录采纳与真实备选；未确认解释属于 LOG/设计树，未完成计划不能进入当前事实摘要。实际文档职责遵守 下方 `<ref-common-rules-documentation-standard>` 标签。
+
 </artifact-contract>
 
 <readiness-and-depth>
@@ -755,6 +779,22 @@ Direct Spec Evidence 至少包含：用户批准与轻量合同、Lead、实施
 
 Evidence 原文不出仓库。对 GitHub 的公共投影由 T-triage publish 按公共投影规则生成，不替代本文件的完整记录。
 
+## 6. 按改动选择检查与复用证据
+
+先固定当前真实 base/head、dirty 写集、配置和消费者，选择能在本次回归上失败的最窄检查；动态配置、Worker、子进程、发布构件或跨模块接口需显式选择真实入口。CI 负责目标项目规定的全量矩阵，本地不因 commit/push 机械重跑刚通过且仍有效的检查；原 required Gate 不因此降级。
+
+复用记录须给出原证据、代码/输入/配置/Skill 摘要、命令选择、环境和仍成立的原因。基线合入、head 改变、配置/依赖/生成器或被测输入变化时重估失效范围；不能把不相关改动当作所有证据永久无效，也不能沿用旧 head 的完成结论。readiness、skipped、pending、环境失败和未运行分别报告。
+
+异步、资源、CI 或测试删除使用 下方 `<ref-common-rules-test-reliability>` 标签；失败后的状态和安全继续使用 下方 `<ref-common-rules-error-handling>` 标签。验证结果须关联真实退出、事件、文件或输出，不能只相信组件/Agent 自报。
+
+## 7. 特殊行为与文档证据
+
+纯文档使用可执行示例、链接、类型与生成一致性、源码语义核对；不适用代码 TDD/E2E时明确理由。prompt、工具定义、错误或 UI/CLI 字符串改变属于行为变化，检查真实模型/用户可见内容，不只检查 Markdown。UI 原型、mock、真实服务器演示分别标记；录制证据对应准确提交、环境、运行方式和片段，不能拼接不同运行冒充一次成功，也不强制无关任务录 GIF。
+
+性能测量必须有真实用户操作、可比较工作量/时钟/冷暖状态、原始样本与端到端结论；微基准改善不能代替整体收益。专业分支仅在原报告追加 下方 `<ref-common-rules-engineering-evidence>` 标签，结构通过不证明测量、翻译或工具执行真实。
+
+删除、合并测试的决定需记录旧行为/错误/兼容/回归到新用例的覆盖承接；无法证明就保留。新准入规则至少有一个从真实执行入口失败的反例，并在恢复基线后确认通过。
+
 </evidence-and-verification>
 
 <deviation-control>
@@ -2310,6 +2350,75 @@ node Speculo Node 校验器 \
 
 </ref-common-skills-plan-quality-review-skill>
 
+<ref-common-rules-error-handling>
+
+# 错误、状态保证与恢复
+
+在设计、实现或审查失败、重试、取消、后台任务和恢复时读取。此规则决定失败后的工程判断；既有授权、状态 owner 与远程操作协议仍分别拥有执行权，不在这里创建账本或更换恢复网关。
+
+## 先定义失败后仍成立的事实
+
+预期失败使用可区分的类型或稳定代码，保存必要原因和处理信息；不要解析展示文案来选择恢复分支。无法预期的缺陷可以作为异常报告，但不能被 catch 转成成功。对每个可能改变状态的操作，记录实际处理者、报告者、清理责任及失败后的保证：
+
+| 已知副作用 | 可以作出的判断 | 下一步 |
+|---|---|---|
+| 未开始或确认未发生 | 未产生本次效果 | 仍需核对授权、取消与重试条件 |
+| 已确认全部提交 | 效果已发生 | 回读结果，不能再次创建相同效果 |
+| 已确认部分发生 | 只有已核实部分可信 | 停止依赖完整结果的工作，按 owner 的补偿或继续协议处理 |
+| 结果未知 | 无法保证没发生或已成功 | 保留原操作标识，先对账；不能声称回滚或安全重试 |
+
+捕获异常不撤销已经发生的修改，记录日志不等于完成恢复。只有受影响状态的 owner 能证明后续操作的前置条件仍成立；否则停止依赖该状态的工作、弃用无效实例或升级处理。无关、独立且已授权工作仍可继续。
+
+## 重试、取消与无进展
+
+重试必须说明安全重复的依据、执行 owner、取消途径和预算。只读、可幂等重试和需要先确认副作用的操作分别处理；“发生了超时”本身不能证明可重复。持续监督需要可释放的生命周期和可见降级，不伪装为有限次数操作。
+
+同一输入、同一方法、同一失败且没有新证据时，不通过更换 Agent、清空 attempts 或重复问用户来制造进展。恢复既有 Goal/Ticket 时沿用原失败记录，由 Lead 说明新增证据或方法变化后再派发。远程对账与 marker 去重由 “请求分诊阶段” 路由到原远程协议；进入远程分支后再读取，不在普通错误审查中加载传输实现。
+
+取消只说明发出了取消请求，不保证远端副作用或子进程已经停止。传播 signal 后仍需等待属于本操作的完成信号；清理失败和业务失败分别报告，不能用后者隐藏前者。
+
+## 面向用户的结果
+
+最终说明必须指出受影响操作、已知影响、尚不确定的结果、系统当前处置和下一安全动作。失效状态持续存在时，提示也应持续可见；错误提示组件不能随已关闭的来源界面一起消失。保留有效数据，不为展示瞬时错误清空它。使用目标项目原有语言和诊断机制；敏感内部信息不进入公开文案。主要报告渠道失败时有独立的安全回退。
+
+S 把适用保证写成行为合同，T-tickets 指定验证，I 落实和记录，D 调查实际失败，C 追踪所有可达路径。验证应观察外部状态、文件、事件、退出或用户可见结果，不只断言异常被捕获。
+
+## 判断示例
+
+请求创建 PR 后超时，应先按稳定 marker 查询原目标；直接重发可能重复创建。读取无副作用的数据遇到临时网络错误，在预算、取消和环境允许时可以重试。这两个场景不能共享无条件 retry。
+
+方法参考：DeepSeek Harness 的错误处理标准，固定参考版本见 <Url>https://github.com/deepseek-ai/deepseek-harness/blob/d743267388641bc76f17c45ce8b4c231aed1d32c/.agents/skills/dsh-error-handling/SKILL.md</Url>；这里采用 SpecDev 原有 owner 和持久化，不导入其运行时实现。
+
+</ref-common-rules-error-handling>
+
+<ref-common-rules-agent-experience>
+
+# 面向 Agent 的工具与 Work 体验
+
+修改工具名称、描述、参数、返回、prompt、Work、Skill 或上下文加载时读取。Work 的具名入口 Markdown 就是本工作流的技能入口；保留原 ID 与文件名，不另建技能注册根，也不要求每个 Work 启动子 Agent。
+
+## 发现、加载与执行分开
+
+description 写真实触发时机、任务范围和相近但不适用的场景，不写“资深专家”式角色自述。先展示用途、可用动作和必要限制，再按模式加载正文或 reference。延后资源必须有可理解的描述、可靠定位和读取条件；不能为减少首轮内容把必要信息藏到不可发现的位置。
+
+已加载同版本正文的同一次任务不重复读取；输入范围、摘要或 owner 变化时重读受影响内容。首次选中只看到摘要时必须读正文，不能从名称推导步骤。实际执行记录继续遵守 下方 `<ref-common-rules-skill-invocation>` 标签；读过入口不是执行完成。
+
+## 工具描述与结果
+
+参数的范围、默认值、配对和使用条件写在参数定义中。工具说明描述行为与返回，避免复制其他工具或系统段已经拥有的规则。权限、破坏性副作用、不可重复操作和必需验证必须在动作之前可见；描述不是底层权限检查的替代。
+
+返回有界的结果摘要以及可回读的 ID、路径或游标，明确截断、遗漏、分页和证据完整性。包含少量当前动作确实需要的邻近上下文，不整页倒出日志，也不因过度裁剪迫使下一步反复搜索。缺少资源、格式无效和加载失败要能辨认，不伪造可用性。
+
+## 作为行为验证
+
+检查模型真正收到的工具 schema、prompt、结果和诊断，覆盖正常、失败、取消、权限不足、重复调用和恢复中的适用分支。用户直接调用已注入的 Work 不应再次重复加载同一正文。仅宿主支持时才依赖自动/显式调用元数据；文字字段本身不是安全控制。
+
+比较优化前后实际首轮输入、总读取、重复调用、误触发和任务结果。在没有同模型、同工具、同任务的实际使用记录时，只报告文件字符或字节变化，不能宣称 token、费用或配额节省。已有正反任务观察与结构检查分别报告。
+
+方法参考：<Url>https://github.com/deepseek-ai/deepseek-harness/blob/d743267388641bc76f17c45ce8b4c231aed1d32c/.agents/skills/agent-experience/SKILL.md</Url>。SpecDev 不因此获得 DSH 的运行时 Skill 加载器。
+
+</ref-common-rules-agent-experience>
+
 <ref-p-goal-plan-references-map-control>
 
 # 从 tickets-map 控制整个 Goal
@@ -2343,6 +2452,114 @@ Lead 将输出保存到调用方自己的既有 Evidence 位置；不创建独
 
 </ref-p-goal-plan-references-map-control>
 
+<ref-common-rules-engineering-evidence>
+
+# 专业分支的工程证据
+
+本规则只约束新运行的 R.performance、I.documentation 和 D.evidence-triage；既有工件与主持久化 schema 不升级。普通 Work 不要求额外记录。记录是某次 checkpoint 的观察，不拥有 Ticket/Goal/change 状态、授权或恢复锁；不能用它代替原 Evidence、诊断和验收。
+
+## 写入原 owner
+
+在原工件正文添加 `Engineering Evidence` 小节及一个标记为 `json specdev-engineering-evidence` 的代码围栏，里面是一个 JSON 对象。performance 位于 specdev/changes/{change}/architecture-review.md；incident 位于 specdev/changes/{change}/diagnosis.md；documentation 位于原本票 specdev/changes/{change}/evidence/T-NN.md 或原 specdev/changes/{change}/evidence/direct-spec.md。禁止写到另一模式的 owner，旧归档与旧完成证据不回填。
+
+公共字段：`version: 1`、`kind`、实际源码/输入的 `checkpoint`、非空 `evidence` 字符串数组。指针使用原 Path/来源定位约定，不写机器绝对路径、密钥或未脱敏数据。记录每次真实观察，恢复时追加新 checkpoint 的证据；不能更改旧事实来制造成功。
+
+## Performance
+
+`operation` 是用户操作，`outcome` 为 baseline、improved、no-gain 或 inconclusive，`uncertainty` 解释测量局限。没有样本时只能 inconclusive。baseline/candidate 各含实际 `checkpoint`、`entrypoint`、`environment`、`clock`、`workload`、64 位 `workload_digest`、`unit`（ms/bytes/ops/s）、`direction`（lower/higher）、`cache`（cold/warm/not-applicable）、`excluded_costs` 字符串数组和有限非负 `samples` 数组。
+
+普通 R 调查只记录 baseline 或 inconclusive；improved/no-gain 需已有可比较的 baseline 与 candidate。比较除源码 checkpoint 外的工作量、入口、环境、时钟、单位、方向、缓存与排除成本必须一致。improved 还需 `behavior_verification: passed`，并且样本算术均值沿目标方向改善。满足这些必要条件仍不证明超过噪声、具备统计显著性、内存可接受或测量真实，Lead 必须回读数据与行为证据。
+
+## Documentation
+
+记录 `owner_paths`（真实源指针数组）、`outcome`（verified/partial/blocked）、`visible_behavior_changed` 布尔值、`behavior_verification`（passed/failed/not-run/not-applicable），以及非空 `claims` 数组。每项 claim 有 subject、method（command/source/manual）、state（verified/unverified）和 evidence。未验证项必须写 reason；verified 的 command 项还必须有 command、`executed: true`、`exit_code: 0` 和非空 output 原始结果摘要数组。
+
+总体 verified 要求所有声明 verified；可见行为改变时必须有 passed 的行为证据。partial/blocked 是诚实的阶段结果，不授予 Ticket done。工具仍不能认证 Agent 自报，Lead 继续核对真实命令、输出和来源。
+
+## Incident
+
+记录非空 facts、unknowns、next_checks 字符串数组；`feedback_loop_ready: false` 与 `root_cause_confirmed: false` 必须明确。这是事件证据截面，不是根因结论。正式 diagnosis 的红灯、假设和状态仍由原诊断规则验证；未来获得红灯后保留原事件观察，转入正常 D 流程，不把旧观察改写成当时已确认。
+
+## 验证入口
+
+新分支分别执行现有校验器的 `--engineering performance`、`--engineering documentation` 或 `--stage diagnosis --engineering incident`，输入当前 change。可与原 `--repo` 和适用 `--stage` 结合。没有标记记录的历史工件继续按原规则验证；显式专业模式缺少记录会失败，已有标记记录在普通 change 校验中也会检查。
+
+代码块语法是 `json specdev-engineering-evidence`，不是新文件类型。校验器只读，无论成功、失败或不完整都不写状态、不创建缺失工件、不执行命令、不获取授权。源记录、结构校验、真实工具执行和宿主观察是不同证据，报告时分别说明。
+
+</ref-common-rules-engineering-evidence>
+
+<ref-common-rules-documentation-standard>
+
+# 开发文档的归属、保真与验证
+
+在 SpecDev 中新增、修改、审查或整理项目文档时读取。本规则负责开发文档的工程要求，不改写全局写作能力。注释继续使用 下方 `<ref-common-rules-code-commenting-rule>` 标签；工件冲突遵守 下方 `<artifact-contract>` 标签。
+
+## 一项事实的负责位置
+
+Work 入口说明如何执行；common 说明跨 Work 判断；项目源码、接口说明与 README 描述当前行为；change ADR 保存已经接受的决定和真实取舍；CONTEXT 保存本 change 已确认领域语义；LOG 保存讨论、待验证解释和被替代结论；Evidence 记录实际验证。永久知识仅经 A 晋升，archive 是只读历史。
+
+按读者与任务区分教程和查询参考。教程按前置知识与操作顺序组织，参考限定自身负责的主题。上层文档只说明下属职责并链接具体 owner，不复制整个子模块实现。用户不需要的内部过程不要挤进入口；详细信息需要可定位而不是被删掉。
+
+## 改写前保留完整命题
+
+逐项保留行动者、动作、条件、时间与顺序、必须/可以/禁止、例外、所有权、副作用、失败保证及后果。删掉这些词可能改变行为，不是简单精简。局部使用点仍要有安全调用所需的完整契约；长篇理由、历史和算法说明链接其 owner。参考或生成内容先改真实源，再重建派生文件，不手工改生成物。
+
+正文描述当前机制，不保留“本轮修改”“下一张 PR”“审查者已认可”或只有某次会话才能解释的编号。必要历史与事故证据留在 LOG/ADR/复盘中；真实 issue、公开规范和可定位历史引用不因出现编号就删除。未知理由保持未知，不补写想象中的设计史。
+
+## 运行声明与升级说明
+
+字段、默认值、命令和平台行为查 owning source，并在有执行条件时运行文档给出的实际操作。仅检查文字或链接不能证明命令成功。缺少网络、凭据、平台或权限时，明确未执行项、风险与验证 owner；不换成模拟后声称真实路径已验证。
+
+外部可感知的破坏性变更在引入时同步升级说明：受影响对象、旧新行为、精确迁移步骤、成功确认和真实恢复限制。用户数据已经发布就不是可随意覆盖的开发数据；预发布名称不解除兼容义务。使用目标项目已有升级文档位置，没有惯例时由当前任务批准的项目文档路径承载，不新建 SpecDev 永久 namespace。
+
+双语或多语仅在目标项目要求时同步。保留未改变的已审文本，核对条款含义、术语、代码及链接；哈希或结构一致不证明翻译正确。不要照搬 DSH 的双语三件套、行数对齐和字数配额。
+
+## 文档维护与可见行为
+
+纯文档可以使用链接、示例、类型片段、生成一致性和事实核对，不伪造 TDD 或 E2E。涉及工具说明、prompt、错误消息或 CLI/UI 输出时按行为变更处理，追加实际模型/用户可见证据或明确未验证。执行入口见 下方 `<ref-i-implement-references-documentation-procedure>` 标签；C 可仅审查，不获得写入权。
+
+方法参考：<Url>https://github.com/deepseek-ai/deepseek-harness/blob/d743267388641bc76f17c45ce8b4c231aed1d32c/.agents/skills/dsh-prose-standard/SKILL.md</Url> 与 <Url>https://github.com/deepseek-ai/deepseek-harness/blob/d743267388641bc76f17c45ce8b4c231aed1d32c/docs/AGENTS.md</Url>。
+
+</ref-common-rules-documentation-standard>
+
+<ref-common-rules-test-reliability>
+
+# 可重复的测试与有效反例
+
+新增、修改或调查异步、资源、时钟、并发、进程或 CI 易抖动测试时读取。检查选择和执行证据由 下方 `<evidence-and-verification>` 标签 拥有；本规则只规定测试怎样可靠地观察目标行为。
+
+## 按真实拓扑设计隔离
+
+从实际测试配置与 CI 定义确认同文件用例、不同 worker、不同测试进程和共享主机的 job 是否可能重叠。进程隔离不隔离端口、可预测目录、数据库、外部服务和继承的子进程。
+
+每个资源都有获取者、原子分配动作、可观察就绪、立即登记的清理和清理完成信号。测试服务器绑定 loopback 的系统分配端口后再读取地址，不先扫描“空闲端口”；目录使用独立临时根，数据库/会话使用独立 namespace。稳定录制 ID 与临时地址在 fixture 内映射，不强迫真实资源复用固定地址。仅作解析输入的 URL 或路径不属于已获取资源。
+
+不得为了掩盖一个 fixture 的冲突把整个套件串行化。共享资源修复涉及跨进程隔离时，使用独立并发进程证明隔离，而不只把同一文件中的测试顺序执行。
+
+## 全局变量、时钟与平台
+
+优先注入依赖而不是修改进程全局状态。必须修改 env、cwd、timer、locale、模块 mock 或 fetch 拦截时，保存“缺失/存在及原值”，立即登记恢复，并在最小作用域用 finally 恢复；必要时增加失败兜底。拦截只覆盖本 fixture 的精确请求。
+
+平台拥有的语义从真实读回结果确认。不要假定时间戳精度、环境变量大小写、信号、权限或文件句柄关闭语义跨平台相同；确实不适用的场景明确跳过并说明原因，不削弱所有平台断言。超时预算依据真实 lane 与被等待操作，setup/teardown 一并考虑。用例预算应明显大于被测试的超时。
+
+## 同步与彻底清理
+
+等待 readiness、handshake、状态、promise 或外部可观察条件；sleep 只可作为已经完成状态的展示停留，不作为正确性的依据。竞态使用 barrier/deferred 明确制造重叠，不靠随机重复碰运气。
+
+清理要停止新工作、解除监听、恢复全局修改，并等待子进程 exit、server close、worker termination 或等价信号。仅调用 abort/close/kill 不代表清理完成。测试需能在断言失败后仍清理，并在存在晚到回调时验证它不能污染下一个测试。
+
+## 有效 red、负向对照与测试删除
+
+有效 red 必须来自目标行为断言。编译错误、没选中测试、fixture 初始化失败、探针未执行、timeout 杀死子进程都不是目标回归证据。强制变异先证明修改落在真实执行路径，观察预期断言失败，再还原并复跑基线。
+
+新增静态或工件准入规则，要从实际顶层 runner 投入故意无效输入并观察预期拒绝；只单测未接入的辅助函数不算落实。对于普通回归，在实际可行且安全时观察修复前失败。无法重现的部分明确未验证。
+
+删除旧测试前逐项核对它所保护的行为、错误、兼容和历史回归在新测试中的承接位置与有效证据。新的公共接口测试存在，不证明旧测试全部冗余；缺失承接则保留或补齐。不要用 sleep、宽断言、吞错、重试、归一化或跳过来制造绿色。真实外部服务允许的有界重试须由该测试政策明确批准，并报告重试与跳过。
+
+方法参考：<Url>https://github.com/deepseek-ai/deepseek-harness/blob/d743267388641bc76f17c45ce8b4c231aed1d32c/.agents/skills/dsh-ci-test-reliability/SKILL.md</Url>。使用目标项目的框架和真实 CI，不照搬 DSH 的工具、覆盖率或超时常量。
+
+</ref-common-rules-test-reliability>
+
 <ref-common-skills-plan-quality-review-references-checklist>
 
 # 计划发布检查
@@ -2360,3 +2577,73 @@ Lead 将输出保存到调用方自己的既有 Evidence 位置；不创建独
 先利用代码、配置、测试和历史回答可发现事实；确有高影响取舍才回用户。不要为显得严格而制造与当前风险无关的关卡。用户要求全面审查时覆盖所有适用轴和所有票，不限制 finding 数量。
 
 </ref-common-skills-plan-quality-review-references-checklist>
+
+<ref-common-rules-code-commenting-rule>
+
+# Code Commenting Rule
+
+注释只用于记录**代码本身无法清晰表达，但对正确使用或安全修改至关重要的信息**。
+
+## Requirements
+
+- 优先通过命名、类型、结构、断言和测试表达意图；不要用注释掩盖复杂或含糊的代码。
+- 公共 API 应说明调用契约，包括重要的输入限制、返回语义、错误、副作用、并发、所有权和安全要求。
+- 内部实现仅在必要时解释非显然的：
+  - 设计原因与取舍；
+  - 不变量；
+  - 顺序约束；
+  - 安全或并发风险；
+  - 兼容、迁移或 workaround 的原因与退出条件。
+- 单位、时区、精度、哨兵值、生命周期等无法由类型或名称表达时必须说明。
+- TODO 必须包含可追踪标识、具体动作以及完成或删除条件。
+- 修改代码行为时，必须同步检查并更新相关注释。
+
+## Do Not
+
+- 不要为每个函数或方法机械添加注释。
+- 不要逐行复述代码。
+- 不要解释名称和类型已经表达的信息。
+- 不要保留注释掉的旧代码。
+- 不要记录修改历史或临时开发过程。
+- 不要猜测“为了性能”“为了兼容”等设计原因。
+- 不要使用注释数量或覆盖率衡量质量。
+
+## Decision Rule
+
+添加注释前确认：
+
+1. 这条信息是否无法由代码清晰表达？
+2. 缺少它是否可能导致错误使用或错误修改？
+3. 它是否在正常重构后仍然有效？
+
+只有答案均为“是”时才添加注释。
+
+> 公共接口记录 Contract；内部实现记录非显然的 Why、Invariant 和 Risk。
+
+</ref-common-rules-code-commenting-rule>
+
+<ref-i-implement-references-documentation-procedure>
+
+# 文档维护执行分支
+
+仅在已授权的 Ready documentation Ticket 或满足原条件的 Direct Spec 中使用；当前 Work 仍为 `specdev/implement`，权限、workspace、commit 和验收仍走 I。文档建议或审查请求不授权写入。入口预检和两轴审查不因选择本分支消失。
+
+## 定位事实与修改范围
+
+读取 下方 `<ref-common-rules-documentation-standard>` 标签，先定位项目的真实源码、当前接口说明、相关 README、生成器和适用写作规范。区分只改说明、修正示例以及改变 prompt/tool/CLI/UI 可见行为。按 Ticket 的获批写集维护项目文档；Evidence 留在原 change 的本票文件或 Direct Spec Evidence，不创建第二份文档状态。
+
+列出每条行为声明的 owner 与验证方法：源码、类型、实际命令、运行场景或人工核对。先修 owner，再同步相应派生物与项目要求的语言侧；禁止手改生成文件。保存行为、条件、否定、例外、失败与所有权，消除仅本会话可理解的叙述。
+
+## 验证与交付
+
+纯说明修改使用相关链接、类型片段、示例、生成一致性和语义核对，不伪造代码 red/green。写入命令实际运行后才记录对应成功结果；缺网络、平台、凭据或权限时保留未验证和责任人，不替换成 mock 后写“真实入口通过”。
+
+可见行为改变时，补充实际输出或目标项目的行为快照/场景证据，并在需要时读取 下方 `<ref-common-rules-agent-experience>` 标签。默认值、错误、兼容或数据格式变化与代码同改；外部破坏的升级说明在当前改动产生，写清旧新行为、受影响者、迁移验证与真实回退限制。
+
+在原 Evidence 记录 `Engineering Evidence`，kind 为 `documentation`；字段与校验见 下方 `<ref-common-rules-engineering-evidence>` 标签。每项声明为 verified 或 unverified；总体 partial/blocked 不等于 Ticket done。新分支使用 `--engineering documentation` 校验对应原工件，再完成 I 的适用项目验证、两轴审查、状态回读和交付。
+
+## 失败与恢复
+
+以原 Ticket/Spec、文档 owner、源摘要和已运行证据恢复；输入漂移使相应验证失效，不覆盖旧证据。上层行为合同冲突返回原 owner。required 验证未运行时不能以“只改文档”越过 Gate；不适用须说明原因。结果明确区分修改了什么、实际运行了什么、只核对了什么和仍待验证什么。
+
+</ref-i-implement-references-documentation-procedure>

package/template/canonical/canonical-specdev-wayfinder.md

@@ -31,6 +31,10 @@ W 位于 change 形成之前：Initiative → 候选 change → 各自 Grill →
 | 生成地图、问题与答案 | 下方 `<wayfinder-map-template>` 标签、下方 `<investigation-ticket-template>` 标签、下方 `<solution-comment-template>` 标签 |
 | 选定清晰 change 交给 Goal | 下方 `<ref-w-wayfinder-references-initiative-discovery>` 标签 的交接门禁 |
 
+## 调查的决策价值
+
+每张调查说明它影响的决定、已知事实、缺失证据、最小调查、结束条件和下一 owner。只对目的地相关的兼容、迁移、权限、故障、成本和部署约束展开，不把“全面研究”变成无限搜索。答案需有可回读来源；没有依据的候选继续未知，不能以调查完成代替产品完成。
+
 ## 必留纪律
 
 - 目的地约束所有调查；能精确陈述的问题成为调查票，尚不能陈述的留在战争迷雾，目标外内容不自动升级。
@@ -75,6 +79,10 @@ resolution: null
 
 <此 Ticket 要解决的一个决策、调查或解除阻塞工作。>
 
+## 调查价值
+
+本问题影响的决定、已经可查的事实、缺失证据、最小调查、结束条件与下一 owner。只展开与目的地相关的风险；research/prototype/task 不自动转生产实现。
+
 </investigation-ticket-template>
 
 <wayfinder-map-template>

package/template/workflows/learning/G-goal/probe-template.md

@@ -25,11 +25,11 @@ status: open
 
 ## Q3 假设与反例
 
-合格读者读完后仍说不出什么？
+合格读者读完后仍说不出什么？具体遗漏了哪个假设、边界或失败情境，为什么容易漏掉，忽略会改变什么判断？不要仅因材料未提到就断言学习者不理解。
 
 ## Q4 视角
 
-架构边或数据流边缺了哪一条？
+架构边或数据流边缺了哪一条？相关时检查重复执行、结果未知、恢复与无进展循环；说明处理责任层、所需证据和可观察的验证条件，不只列“重试/监控”。
 
 ## Q5 元问题
 
@@ -43,6 +43,8 @@ status: open
 | --- | --- | --- | --- |
 |  |  |  | mine-more / defer / re-dispatch-L / split-lesson |
 
+每个主要缺口在表后追加遗漏原因、触发/父问题、证据与待验证项；新的 b02 应带来增量，不重复 b01。
+
 Miner 只填表，不选择最终处置。
 
 ## split-proposal

package/template/workflows/learning/G-goal/references/coverage-bar.md

@@ -30,3 +30,7 @@ v1 只实现编程四轴。其他领域可同构为 units / properties / structu
 ## 挖掘扇出
 
 挖掘扇出上界是 `mine_unit_cap=15`，不是必须凑满。4 节的小项目按 4 节挖。切分规则读 `<Path>{roots.workflows}/learning/G-goal/references/mine-unit.md</Path>`。
+
+## 盲区发现与实际处置
+
+授课、miner 和覆盖验收读取 `<Path>{roots.workflows}/learning/common/rules/inquiry-depth-policy.md</Path>`；生产相关代码还读取 `<Path>{roots.workflows}/learning/common/rules/production-inquiry.md</Path>`。将相关发现映射回上述矩阵格子，记录遗漏原因、影响、源码证据和验证设计；不把假设情境写成已发生事故。共享方法不增加问题配额，不改变十问后拆课、unit 上限或计划/执行授权边界。

package/template/workflows/learning/INDEX.md

@@ -3,8 +3,8 @@ id: learning
 type: workflow
 workflow: learning
 name: Learning Workflow
-description: 以完整、通俗、多表示的课程，苏格拉底问答课、目标模式 Goal-Plan 编译（先教后挖）、单文件作业评审、可选延迟复习和带溯源的主题综合，持续建立个人 Markdown 知识库。
-keywords: [learning, 学习, 教学, 苏格拉底, 反问, goal, 目标模式, 作业, 复习, 综合, 知识, eli5]
+description: 以完整、通俗、多表示的课程，苏格拉底问答与主动探究、目标模式 Goal-Plan 编译（先教后挖）、单文件作业评审、可选延迟复习和带溯源的主题综合，持续建立个人 Markdown 知识库。
+keywords: [learning, 学习, 教学, 苏格拉底, 反问, goal, 目标模式, 作业, 复习, 综合, 知识, eli5, explore, 盲区, 主动挖掘]
 ---
 
 # Learning Index

package/template/workflows/learning/L-lesson/L-lesson.md

@@ -17,12 +17,14 @@ keywords: [lesson, 教学, eli5, 图文, explanation]
 
 读取 `<Path>{roots.workflows}/learning/common/rules/activation-and-memory.md</Path>`，按当前 Change、OBJ、主题与证据 ID 定位本轮输入；仅当前恢复或安全门要求时扩读。
 
+读取 `<Path>{roots.workflows}/learning/common/rules/inquiry-depth-policy.md</Path>`；只有工程、Agent 或外部工具主题读取 `<Path>{roots.workflows}/learning/common/rules/production-inquiry.md</Path>`。
+
 ## 流程
 
 1. 确认 Change 有 `course.md`、`background/foundation.md`、`baseline.md`、目标 OBJ 和 `sources.md`；缺失时返回 A-assess-and-plan。
 2. 用户指定 Lesson 主题、OBJ、期望效果和深度；读取精确背景和来源，不遍历无关 context。
 3. 生成一个完整的 `lessons/L-<NNN>-<slug>.md`，元数据包含 `lesson_id`、`objective_ids`、`estimated_minutes` 30–40、`time_budget`（各段可加总）、`expression_level`、`coverage_depth` 和 `source_ids`。
-4. 每个核心目标至少覆盖动机/宏观地图、通俗直觉、精确定义与英文术语、机制/因果链、ASCII/表格/可选外链图之一及文字等价物、正例、反例或边界、变式迁移、常见误区、总结和引用。允许章节顺序变化，不套用固定 5E 或单一路线。
+4. 每个核心目标至少覆盖动机/宏观地图、通俗直觉、精确定义与英文术语、机制/因果链、ASCII/表格/可选外链图之一及文字等价物、正例、反例或边界、变式迁移、常见误区、总结和引用。允许章节顺序变化，不套用固定 5E 或单一路线。主动解释相关潜在盲区、为何容易遗漏及现实检验；用讲解而非学习者答题呈现，保持本课活动预算。
 5. 可加入非评分 pause/self-check，但不写 Q/A、答案、verdict、分数或 mastered。更新 `lessons/INDEX.md` 与 `learning-log.md`，运行 validator，清空 current_work。
 
 ## 完成标准
@@ -36,3 +38,5 @@ keywords: [lesson, 教学, eli5, 图文, explanation]
 
 - Lesson 模板：`<Path>{roots.workflows}/learning/L-lesson/lesson-template.md</Path>`
 - 教学规则：`<Path>{roots.workflows}/learning/common/rules/teaching-policy.md</Path>`
+
+仅编译独立网页课程时读取 `<Path>{roots.workflows}/learning/common/rules/portable-learning-runtime.md</Path>`；本地仍保留 A 产物前置条件，不加载网页适配。

package/template/workflows/learning/L-lesson/lesson-template.md

@@ -40,6 +40,10 @@ source_ids: [S-001]
 
 ## 常见误区
 
+## 潜在盲区与现实检验
+
+选择与目标相关的主要遗漏，说明为何容易忽略、影响什么判断、反例/失败机制，以及处理边界和验证设计。区分潜在盲区与已证明的理解偏差；不生成学习者 Q/A，不声称执行了未运行的测试。
+
 ## 非评分暂停
 
 ## 总结、词汇表与下一步

package/template/workflows/learning/Q-question/Q-question.md

@@ -2,54 +2,46 @@
 id: learning/question
 type: workflow-entry
 workflow: learning
-name: 苏格拉底问答课
-description: 以一批约 5 题激活已知与未知，学习者作答后追加详细讲解、纠错与深化；一批生成一节 inquiry-lesson。无 Change 时可自行创建 lightweight inquiry Change。不自动串联 L/H/R。
-keywords: [反问, 苏格拉底, socratic, inquiry, 提问课, questioning, 激活, 问答课]
+name: 深度探究与苏格拉底问答课
+description: tutor 默认约 5 题、作答后讲解；explore 主动发现盲区并深入到处理与验证。无 Change 可创建轻量主题；两种模式不混写，不自动串联 L/H/R。
+keywords: [反问, 苏格拉底, socratic, inquiry, 提问课, questioning, 问答课, 主动挖掘, 盲区, 深度探究, explore]
 ---
 
-# 苏格拉底问答课
+# 深度探究与苏格拉底问答课
 
 > 激活本 Work 后，先读取 `<Path>{roots.workflows}/learning/README.md</Path>`。
 
 ## 读取范围
 
-当前步骤开始前，读取 `<Path>{roots.workflows}/learning/common/rules/artifact-layouts.md</Path>`；只加载本 Work 需要的领域合同。
+读取 `<Path>{roots.workflows}/learning/common/rules/artifact-layouts.md</Path>` 与 `<Path>{roots.workflows}/learning/common/rules/activation-and-memory.md</Path>`，按当前 Change、OBJ、主题和证据 ID 定位最小输入，不默认整读 context/archive。
 
-读取 `<Path>{roots.workflows}/learning/common/rules/activation-and-memory.md</Path>`，按当前 Change、OBJ、主题与证据 ID 定位本轮输入；仅当前恢复或安全门要求时扩读。
+两种模式均读取 `<Path>{roots.workflows}/learning/common/rules/inquiry-depth-policy.md</Path>` 与 `<Path>{roots.workflows}/learning/common/rules/question-map-contract.md</Path>`。只有工程、Agent 或外部工具主题读取 `<Path>{roots.workflows}/learning/common/rules/production-inquiry.md</Path>`。
 
-## 流程
+<!-- portable:question:start -->
+## 模式选择
 
-1. 解析 roots 与 Learning v2 状态。若尚无 `status.json` / `locations.json`，先按 I-init-setup 写入空状态骨架，不创建知识条目。
-2. 若没有可用 Change：根据用户主题创建 lightweight inquiry Change `YYYY-MM-DD-<kebab-topic>`，写入 `INDEX.md`、最小 `course.md`/`baseline.md`/`sources.md`、`inquiry/INDEX.md`、`learning-log.md` 和 `.status.json`（`phase=teaching`，`current_work=learning/question`）。不假装已完成 A-assess-and-plan 的完整课程地图。
-3. 若已有 Change：按 Activation 合同只读取对应 course/OBJ/Lesson/baseline/notes/inquiry 索引；不整读 archive 或其他 Change。
-4. 读取 `<Path>{roots.workflows}/learning/common/skills/socratic-questioning/SKILL.md</Path>` 与 `<Path>{roots.workflows}/learning/common/rules/questioning-policy.md</Path>`。按用户指定教法或默认 `socratic` 配方生成本批 n 题：用户指定正整数时使用该值，否则默认 5；不套用 G-goal 的 mine 十问上限。
-5. 创建 `inquiry/IQ-<NNN>-<slug>-batch-NN.md`：元数据（question_count=n）、Q1…Qn、空白 A1…An、`Response: pending`。更新 `inquiry/INDEX.md`。不得把答案写入题目。
-6. 学习者填写 A1…并写入精确行 `Response: ready` 后再次激活本 Work。校验回答原文与标记，冻结 Q/A。
-7. 只在同一文件末尾追加 `## Teaching` 与 `## Inquiry Lesson`。Teaching 逐题给出思路复原、`aligned|partial|off|uncertain`、中文详解、`Explain (English)`、纠错路径、先前未覆盖知识和来源锚点。Inquiry Lesson 把本批 n 题收成一节短课单元，并以 keep-alive 钩子指向下一批、缺失 OBJ、L、H 或 R。将 `Response:` 更新为 `closed`。
-8. 更新 `learning-log.md` 与 Change `.status.json`：`works_run` 追加 `learning/question`，清空 `current_work`。不写 mastered，不写入 `lessons/` 或 `homework/`，不自动激活其他 Work。重答必须新建 batch 文件并链接旧文件。
+`mode=tutor|explore` 与 `teaching_method` 是不同维度。显式 mode 优先；恢复时未指定则沿用当前工件模式；新任务要求“考我、让我先答、苏格拉底练习”时使用 tutor，要求“替我主动挖掘、找出未提出的问题、直接深入讲解”时使用 explore；其余默认 tutor。既希望深挖又希望自己回答时仍可用 tutor 加强内容深度，不必强制切换模式。
 
-## 当前批次验证
+tutor 保持先作答后讲解，一批默认 5 题，用户指定正整数 n 则生成 n 对连续 Q/A，不能截断或套用其他模式上限。explore 直接发现、解释和推演，不伪造学习者答案、提交状态或理解表现。两种方式都要解释重要发现的原因，并推进主要分支到证据与验证。
 
-生成新批次后，以实际用户数量 n（未指定则 5）运行：
+已有未提交问答批次时要求直接探索，另建探索记录并关联原问题，保留原始批次及提交状态；不能替学习者填 A、自动提交或原地改成自问自答。恢复请求没有提供可定位的权威工件时，先找本主题实际记录，不能虚构上次进度。
+<!-- portable:question:end -->
 
-```bash
-node <Path>{roots.workflows}/learning/Q-question/tools/validate-inquiry.mjs</Path> --change-dir <Path>{roots.state}/learning/changes/{change}</Path> --file <当前批次相对路径> --expected-count <n>
-```
+## 共同启动
 
-关闭前先在当前 change 内保留用户已提交的 `Response: ready` 原文快照，用候选 closed 文件和 `--before <ready快照相对路径>` 校验 Q/A 与元数据字节不变，再发布候选。快照作为当前批次证据，不新建状态树；归档或合并中的 change 通过稳定 ID 解析当前 locator，不把示例 changes 路径当永久位置。失败不更新 Response 或状态。工具只检查结构与所提供的原文字节，不认证回答作者或授课质量；旧历史不会被全局重写或自动迁移。
+1. 解析 roots 与 Learning v2 状态、stable Change ID、当前 locator 和根锁。缺少 status.json/locations.json 时按 I-init-setup 初始化空骨架；未知 schema、v1、锁冲突、越界或 parent cycle 按激活合同阻塞。任何状态写入仍须满足入口授权。
+2. 没有可用 Change 时，按用户主题创建 lightweight inquiry Change `YYYY-MM-DD-<kebab-topic>`：INDEX.md、最小 course.md/baseline.md/sources.md、inquiry/INDEX.md、learning-log.md 和 .status.json（phase=teaching，current_work=learning/question）。不假装完成完整课程设计。轻量模板读取 `<Path>{roots.workflows}/learning/Q-question/lightweight-course-template.md</Path>`。
+3. 已有 Change 时只取对应 course/OBJ/Lesson/baseline/notes 和 inquiry 索引相关项；问题地图首次使用才创建，不回填旧历史。恢复已关闭记录只读，后续建立新批次或探索。
+4. 按上方规则选模式并只加载对应分支。`mode=tutor` 读取 `<Path>{roots.workflows}/learning/Q-question/references/tutor-mode.md</Path>`；`mode=explore` 读取 `<Path>{roots.workflows}/learning/Q-question/references/exploration-mode.md</Path>`。不要同时执行两个分支。
 
-## 完成标准
+## 工件与完成边界
 
-- 一批默认 5 题；数量可由用户指定，但必须 Q/A 成对且连续编号；
-- `Response: pending|ready|closed` 状态可审计；ready 之前不得出现 Teaching / Inquiry Lesson；
-- Teaching 是授课讲解，不是 H 的评分 Review，不得使用 `Submission` 或 `verdict: correct|partial|incorrect` 字段名；
-- 本批全部题目生成一节 Inquiry Lesson；完整 30–40 分钟讲义仍归 L-lesson；
-- 无 Change 时本 Work 可自行创建 lightweight inquiry Change，不得因缺少 A 产物而拒绝开问；
-- 真新手或高元素交互时必须提供降级探针或建议先走 L-lesson。
+- tutor 使用 inquiry/IQ-*.md：Response: pending → ready → closed，冻结原 Q/A 后追加 Teaching 与 Inquiry Lesson；完整协议及 validate-inquiry 命令在 tutor 分支。
+- explore 使用 inquiry/explorations/EX-*.md 与 inquiry/question-map.json；独立结构验证，不送入 IQ 的提交状态机。
+- Q 只拥有当前 Change 的 inquiry/ 及已授权的索引、日志、状态更新；不写 lessons/、homework/、goal/、mastery 或永久 context，不自动激活 L/H/R/G。
+- 问题地图的 resolved 不表示 mastered；只有真实延迟复习证据才能由原 owner 更新 retention。结构验证不认证教学质量。
+- 先验证工件与引用、发布工件，再更新索引/日志和 Change 状态。失败保留候选与恢复证据，不提前清空 blocker 或推进完成。
 
-## 子文件
+## 网页适配
 
-- 问答课模板：`<Path>{roots.workflows}/learning/Q-question/inquiry-template.md</Path>`
-- 轻量课程模板：`<Path>{roots.workflows}/learning/Q-question/lightweight-course-template.md</Path>`
-- 提问政策：`<Path>{roots.workflows}/learning/common/rules/questioning-policy.md</Path>`
-- 提问引擎：`<Path>{roots.workflows}/learning/common/skills/socratic-questioning/SKILL.md</Path>`
+仅编译独立网页能力时读取 `<Path>{roots.workflows}/learning/common/rules/portable-learning-runtime.md</Path>`；工作区执行不加载该适配，不改变原 Response 精确行协议。

package/template/workflows/learning/Q-question/exploration-template.md

@@ -0,0 +1,28 @@
+---
+exploration_id: EX-001-topic
+mode: explore
+status: active
+question_ids: [P-001]
+---
+
+# 主动探究记录
+
+## Scope
+
+写明原问题、目标、材料范围、事实与假设；不把教学情境当成已经发生的故障。
+
+## Discovery
+
+按问题 ID 给出发现、为何容易遗漏、为什么重要，以及父问题/触发证据。只列相关方向，不凑配额。
+
+## Deep Dive
+
+主要分支讲清机制、反例、所需证据、方案与代价；工程问题说明处理责任层。
+
+## Verification
+
+区分验证设计、已取得证据、实际测试记录和仍未验证的结论。写出输入、可观察结果与通过条件。
+
+## Next
+
+记录停止原因、待证据/暂缓项和一个可选后续。不得把当前轮关闭等同于全部问题解决或学习者已掌握。

package/template/workflows/learning/Q-question/inquiry-template.md

@@ -22,6 +22,10 @@ created_at: <ISO-8601>
 - 教法：`socratic | 5e-recipe | feynman | productive-failure | custom`
 - Skill：`socratic-questioning`
 
+## 问题来源
+
+本批每题关联问题地图 ID、父问题或触发证据，简述为什么值得问但不泄露目标答案。新题来自相关盲区、前一批回答或新情境；复问注明理由。
+
 ## Questions
 
 ### Q1 — 澄清与定义

package/template/workflows/learning/Q-question/question-map-template.json

@@ -0,0 +1,4 @@
+{
+  "schema_version": 1,
+  "questions": []
+}