@blxzer/cursor-trellis 0.3.6 → 0.4.1

package/dist/templates/markdown/spec/guides/goal-release-regression-runbook.md.txt

@@ -0,0 +1,132 @@
+# Goal 发布回归 Runbook
+
+> **受众**：Root npm 闸、Parent 集成前自检、维护者。  
+> **范围**：`cstl goal` 回归 checklist — **不扩展 Goal 功能**，仅钉死 hardening 命令。  
+> **基线**：`cursor-trellis` `main`（A1/A2 合并后 tip）；harness 侧 `.cstl/spec/Trellis/framework/cstl-goal-*.md`。
+
+---
+
+## 1. 发布门语义
+
+| 项 | 说明 |
+| --- | --- |
+| **用途** | npm 发布前 Goal 回归闸；Parent `verify.md` 可链接本页 |
+| **非目标** | 不新增 runner/worker 能力；不替代 [cursor-trellis release runbook](./cursor-trellis-release-coexistence-guide.md) |
+| **通过标准** | Mock 路径全绿（§2）；Live 路径（§3）为可选加分项 |
+| **零功能 diff** | 本闸仅文档与命令；**不得**附带 `cursor-trellis/packages/cli/src/goal/*` 语义变更 |
+
+---
+
+## 2. Mock 路径（必须 — 无需 `CURSOR_API_KEY`）
+
+在 harness 根目录执行。CI / 新人 onboarding 至少跑完本节。
+
+### 2.1 全量 Goal 测试
+
+```powershell
+cd cursor-trellis/packages/cli
+pnpm test goal/
+```
+
+**期望：** 7 个 test files、32 tests 全部 PASS。
+
+### 2.2 Golden + 墙单元测试
+
+```powershell
+cd cursor-trellis/packages/cli
+pnpm exec vitest run test/goal/reviewer-golden.test.ts test/goal/walls.test.ts
+```
+
+**期望：**
+
+- `mis-allow gate is zero on hard-deny bucket` 通过
+- `walls.test.ts` 墙钟逻辑通过
+
+### 2.3 墙 smoke 脚本语法
+
+```powershell
+python -m py_compile .cstl/scripts/goal_wall_smoke.py
+```
+
+### 2.4 可选 — 墙钟 crash 可复现 smoke
+
+需已有 goal run 目录（`goal_id` 来自历史 hardening 或本地狗粮）：
+
+```powershell
+python ./.cstl/scripts/goal_wall_smoke.py <goal_id> --mode window --json
+```
+
+**期望：** JSON 中 `ok: true`；`audit.log` 含 `wall-clock reached`。
+
+---
+
+## 3. Live 路径（可选 — 需要 `CURSOR_API_KEY`）
+
+仅当维护者显式同意 live SDK 狗粮时执行。Cursor Agent shell **默认不继承** User 级环境变量，须先加载：
+
+```powershell
+$env:CURSOR_API_KEY = [Environment]::GetEnvironmentVariable('CURSOR_API_KEY','User')
+```
+
+### 3.1 Preflight → Accept → Run
+
+```powershell
+cstl goal preflight --goal "..." --json
+cstl goal accept <goal_id>
+cstl goal run <goal_id> --max-steps 1 --json
+```
+
+CI 风格可用 mock worker（无需 live SDK）：
+
+```powershell
+cstl goal run <goal_id> --mock-worker --max-steps 1 --json
+```
+
+若全局 `cstl` 未 link 最新 dist，改用本地 CLI：
+
+```powershell
+node cursor-trellis/packages/cli/dist/cli/index.js goal preflight --goal "..." --json
+```
+
+---
+
+## 4. 契约引用
+
+回归失败时对照合同，勿在发布闸中改语义：
+
+| 文档 | 路径 |
+| --- | --- |
+| cstl-goal 验收合同 | [`.cstl/spec/Trellis/framework/cstl-goal-contract.md`](../Trellis/framework/cstl-goal-contract.md) |
+| Action Packet | [`.cstl/spec/Trellis/framework/cstl-goal-action-packet.md`](../Trellis/framework/cstl-goal-action-packet.md) |
+| Golden 用例 | `cursor-trellis/packages/cli/test/fixtures/goal-reviewer-golden/cases.json` |
+
+---
+
+## 5. SDK 残余风险（须诚实记录）
+
+| 来源 | 结论 |
+| --- | --- |
+| `@cursor/sdk` `Agent.prompt` | `sdk-client.ts` 包装为**单次** `Promise`，**无** mid-run cancel / abort 参数 |
+| Goal SDK worker | `worker.ts` 仅外层 `withTimeout(..., ctx.timeoutMs)` |
+| smart-search docs 探针（2026-08-07） | 未发现官方 mid-run cancel API — **按 timeout-only 风险处理** |
+
+**实践建议：**
+
+- Live 回归控制 `--max-steps` 与 wall 配置
+- 长步无法保证 turn 中途取消；超时后进程可能仍占用资源直至 Promise  settle
+- 无 key 环境一律用 `--mock-worker` 或 §2 Mock 路径
+
+---
+
+## 6. 快速 Checklist
+
+- [ ] `pnpm test goal/` — 32 PASS
+- [ ] `reviewer-golden.test.ts` + `walls.test.ts` — PASS
+- [ ] `python -m py_compile .cstl/scripts/goal_wall_smoke.py` — OK
+- [ ] （可选）`goal_wall_smoke.py <goal_id> --mode window --json` — `ok: true`
+- [ ] （可选 live）`cstl goal preflight` / `accept` / `run --max-steps 1`
+- [ ] **无** `cursor-trellis/packages/cli/src/goal/*` 功能 diff
+
+---
+
+**来源：** `08-06-cstl-p2-goal-hardening/verify.md` · Parent `08-07-cstl-parent-orch-visibility` §5.2

package/dist/templates/markdown/spec/guides/index.md.txt

@@ -23,6 +23,9 @@ These guides help you **ask the right questions before coding**.
 |-------|---------|-------------|
 | [Durable Learning Decision Guide](./durable-learning-decision-guide.md) | Choose no-learning vs spec update vs learning artifact before archive | Finishing a task, parent review, or after `/cstl:break-loop` |
 | [Verification Strength Guide](./verification-strength-guide.md) | Graded verify depth (Lite/Full/Parent × verification_profile); false-green probes; **not** TDD | Phase 3.1, writing `verify.md`, choosing check depth, archive prep |
+| [Debug Loop Guide](./debug-loop-guide.md) | Debug discipline: tight red-capable feedback loop before hypotheses; six phases; `[DEBUG-xxx]` tags; Redact; PS7 HITL | User reports a hard bug / performance regression; diagnosis in progress (before `cstl-break-loop`) |
+| [Test Discipline Guide](./test-discipline-guide.md) | 测试写作纪律：pre-agreed seams、垂直切片、三反模式、mock 边界；**不是 TDD 要求** | Writing or reviewing tests; planning what to test; choosing mock boundaries |
+| [Prototype Guide](./prototype-guide.md) | 原型纪律：一次性代码回答设计问题；问题决定形态；LOGIC/Python 默认、UI 不适用；折叠重写不 mv、留证 + 清理 | A design question needs a runnable throwaway answer (mechanism / state model / algorithm); folding a verdict into design or real code |
 | [Injection Budget Guide](./injection-budget-guide.md) | Per-channel caps, jsonl manifest limits, Layer 2 defaults; matrix-aligned | Adding alwaysApply rules, curating jsonl, subagent dispatch |
 | [Code Reuse Thinking Guide](./code-reuse-thinking-guide.md) | Identify patterns and reduce duplication | When you notice repeated patterns |
 | [Cross-Layer Thinking Guide](./cross-layer-thinking-guide.md) | Think through data flow across layers | Features spanning multiple layers |
@@ -32,7 +35,15 @@ These guides help you **ask the right questions before coding**.
 | [Execution strategy](./execution-strategy.md) | `suggest-execution-strategy`, rules JSON, inline vs worker vs child-task | Writing `implement.md` contract, Phase 2 dispatch |
 | [Cursor context injection guide](./cursor-context-injection-guide.md) | Which Cursor channels reach the model (sessionStart bug, .cursor/rules, AGENTS.md) | "Agent ignored instructions" on Cursor, adding always-visible rules |
 | [Cursor native modes guide](./cursor-native-modes-guide.md) | Prefer Plan / Ask / Debug / Agent / Multitask × Trellis phases & artifacts | P1 mode routing, Parent/Multitask, Ask↔No Task, Plan↔Phase 1, Debug evidence |
+| [Artifact locale guide](./artifact-locale-guide.md) | Human-reviewed PRD/design/implement/verify/handoff language (zh \| en) | `task.py create`, planning skills, session context; not full CLI i18n |
 | [cursor-trellis release & coexistence](./cursor-trellis-release-coexistence-guide.md) | npm publish runbook, `cstl-v*` tags, upstream Trellis coexistence | Releasing cstl, scenario 2 init, migrate gate, uninstall AGENTS strip |
+| [Goal release regression runbook](./goal-release-regression-runbook.md) | Goal npm 发布前回归闸：mock/live 命令、契约路径、SDK timeout 残余风险 | Root npm 闸、Parent integrate 前 Goal 自检、hardening 后发布 |
+
+### When using `/cstl-goal` (optional long-horizon mode)
+
+- [ ] User explicitly invoked `/cstl-goal` — default cstl spine unchanged otherwise
+- [ ] Read [cstl-goal Contract](../Trellis/framework/cstl-goal-contract.md) §1 preflight + §3 hard deny before G1 self-drive
+- [ ] High-risk actions: pack per [Action Packet](../Trellis/framework/cstl-goal-action-packet.md) → reviewer seam; no bare execute
 
 ---
 
@@ -75,6 +86,32 @@ These guides help you **ask the right questions before coding**.
 
 **Verification rule**: Every CRITICAL/WARNING finding must be verified against the actual code before prioritizing. Budget ~35% false-positive rate for AI reviews.
 
+### When Debugging Hard Bugs or Performance Regressions
+
+- [ ] User reports something broken / throwing / failing / slow, and it is not obvious at a glance
+- [ ] You find yourself about to read code to form a theory before you have a runnable repro command
+- [ ] A fix attempt failed and you have no regression to prove the fix
+- [ ] You need a human-in-the-loop repro script (PowerShell 7)
+
+→ Read [Debug Loop Guide](./debug-loop-guide.md) (diagnosis in progress; run `cstl-break-loop` after the fix)
+
+### When Writing or Reviewing Tests
+
+- [ ] You're about to write tests for new or existing behavior
+- [ ] You're reviewing a test that breaks on refactor without a behavior change
+- [ ] You need to decide what to mock and where the seam is
+- [ ] Test expectations seem to restate the implementation
+
+→ Read [Test Discipline Guide](./test-discipline-guide.md)
+
+### When a Design Question Needs a Runnable Throwaway
+
+- [ ] 你在验证一个机制 / 状态模型 / 算法「感不感觉对」——不是 bug 调试，是设计验证
+- [ ] 结论要写回 design / prd / 真实代码，但想先跑起来看证据
+- [ ] 准备写一次性脚本回答「如果……会怎样」
+
+→ Read [Prototype Guide](./prototype-guide.md) (LOGIC/Python default; UI N/A; fold+evidence+cleanup)
+
 ---
 
 ## Pre-Modification Rule (CRITICAL)

package/dist/templates/markdown/spec/guides/prototype-guide.md.txt

@@ -0,0 +1,139 @@
+# Prototype Guide（原型纪律）
+
+> **Purpose**: 用一次性代码回答**设计问题**——先写清问题，再由问题决定原型形态；答案折叠进真实代码（**重写不 mv**），原型留证后清理，不留工作区腐烂。本 harness：**LOGIC / Python 默认，UI 不适用（N/A）**。
+
+---
+
+## 1. Purpose / When to use
+
+**原型是一次性代码，回答一个设计问题。** 什么时候用：
+
+- 要验证某个**机制 / 状态模型 / 算法**「感不感觉对」——在纸上难推演的 case，跑起来看证据。
+- 要在 design / prd 落结论前，先对「如果……会怎样」拿到可观察的事实。
+- 结论已知会写回真实代码，但想让实现者先摸一遍形状。
+
+原型唯一的产出是**答案**，不是代码。
+
+## 2. Non-goals
+
+- **不接真实 DB / 服务**：原型依赖一律假数据 / 内存 / 显式标记的临时本地文件。
+- **不直接升生产**：原型的代码路径不是生产代码的捷径；折叠时**重写**，不 `mv`。
+- **不做 UI（本 harness）**：本 harness 无 UI 面，UI 原型不适用（见 §6）。
+- **不替代测试 / 调试 / 需求发现**：见 §12 边界（单向链）。
+
+## 3. Hard rules
+
+1. **问题决定形态** — 先写设计问题，再选原型形态；问题写不清，先不写代码。
+2. **丢弃式（throwaway）** — 从第一天起就是一次性：不接真实 DB/服务；**不加测试、不泛化**（可跑即可）；默认**无持久化**（或仅临时本地文件且须清理）。
+3. **状态可见** — 每次 action 后打印/记录关键状态（print / 日志 / 简单 TUI），答案从可见状态里读出来。
+4. **答案折叠** — 结论写回 design / prd / 真实代码；原型代码本身**不提升**为生产代码，折叠时在真实 module 里**重写**，不 `mv`。
+5. **留证后可清理** — 答案折叠 + 留证完成后，删除工作区里的原型（§9 / §10），不留腐烂。
+
+## 4. Step 0 — Write the design question
+
+开始前写一句话，并放进原型文件头：
+
+> 这个原型要回答：____________
+
+回答不了这个问题，就说明原型还没开始对。
+
+## 5. Shape: LOGIC（Python）— default for this harness
+
+本 harness 的 LOGIC 默认形态（替代 Matt 单 HTML 默认；本仓库无 UI 面）：
+
+- **单个可运行脚本**，路径二选一：
+  - `.tmp/prototypes/<slug>/run.py`（工作区 scratch；**惰性创建，不预建空目录**）
+  - 任务 `research/prototype-<slug>.py`（工作位置即留证位置，见 §9）
+- **逻辑与 demo 入口分离**：文件内分两段——
+  - `# --- logic (portable) ---`：纯逻辑函数（无副作用、依赖从参数注入），折叠时可提起进真实代码
+  - `# --- demo entry ---`：构造输入、调用、打印状态，只服务于「跑起来看答案」
+- **运行**：`python run.py` 即得可观察输出，无额外步骤。
+- 最小骨架示例见 §13。
+
+## 6. Shape: UI — N/A for this harness
+
+**不适用 / N/A。** 本 harness 没有 UI 面（agent CLI + 文档工作流），**不写 UI 脚手架**、不做 UI 变体原型、不引入 UI 分支。若上游项目需要 UI 原型，那是上游项目自己的事，不进本 harness 主树。
+
+## 7. Visibility of state
+
+原型回答问题的机制必须**可观察**：
+
+- 每次 action 后打印完整相关状态，不省略中间态。
+- 关键分支打印路径标签；比较类问题打印两侧差异。
+- 输出讲不清 → 答案就落不进 design。
+
+## 8. Capture the answer → fold into real code
+
+原型结束后两件事：
+
+1. **折叠答案**：把结论（问题 + 判定 + 理由）写回 design / prd / 真实代码；代码折叠时在真实 module 里**重写** logic 段（贴合真实接口与错误处理），**不 `mv` 原型文件升生产**。
+2. **留证原型**（primary source，可回看「当时怎么答的」）——见 §9。
+
+## 9. Evidence（留证：throwaway 分支 / 路径快照）
+
+两层留证机制，**清理前必须确认留证已落**：
+
+| 层 | 手段 | 适用 |
+| --- | --- | --- |
+| A | git **throwaway 分支**提交（如 `proto/<slug>`，离开 main），留上下文指针 | git 仓库（如 cursor-trellis / smart-search） |
+| B | **路径快照**：复制到 `.cstl/tasks/<task>/research/prototype-<slug>.py`（或任务目录等价位置），并在 handoff.md / verify.md 记录路径 | **非 git 仓库——本 harness 根目录的默认手段** |
+
+- 工作位置本身是任务 `research/prototype-<slug>.py` 时，即工作即留证，无需再复制。
+- A / B 可并用。
+
+## 10. Cleanup / archive（清理：不留腐烂）
+
+- **何时**：答案已折叠 + 留证已落，原型不再需要。
+- **做什么**：删除 `.tmp/prototypes/<slug>/`——scratch 工作区不留腐烂；若原型躺在任务 `research/` 下，那本身就是留证，保留并按任务归档机制处理。
+- **不做**：把原型当长期分支 / 常驻目录养；在 main 上留下 throwaway 痕迹。
+
+## 11. Anti-patterns（反模式清单）
+
+| 反模式 | 信号 | 修正 |
+| --- | --- | --- |
+| 过早泛化 | 加参数 / 抽象 / 配置，问题还没回答完 | 回到最小：只够回答问题 |
+| 接生产依赖 | 连真实 DB / 服务 / 凭据 | 假数据 / 内存 / 显式临时文件 |
+| 当长期分支养 | 原型分支 / 目录持续叠加功能、迟迟不折叠 | 答案到手即折叠 + 清理 |
+| 在本项目启用 UI 分支 | 写 UI 脚手架 / UI 变体原型 | 本 harness UI N/A，直接不做 |
+| `mv` 升生产 | 原型文件直接改名 / 移入真实路径 | 折叠时重写进真实 module |
+| 答案不留证 | 跑完即删、结论没落任何地方 | §8 折叠 + §9 留证先行 |
+
+## 12. Relation to debug-loop / test-discipline / brainstorm（边界，单向链）
+
+- **Debug Loop Guide**：debug-loop 用 throwaway harness 回答「**为什么坏了**」（bug / 性能回归，诊断进行中）；原型回答「**这个设计 / 机制对不对**」（尚无 bug，设计前）。原型**不替代**调试纪律。
+- **Test Discipline Guide**：test-discipline 管生产测试写作（pre-agreed seams、反模式、mock 边界）；原型**不加测试**（可跑即可）。原型**不替代**测试纪律。
+- **brainstorm**：brainstorm 管需求发现（用户想要什么）；原型管设计验证（机制怎么实现才对）。原型**不替代** brainstorm。
+- 衔接点：原型的可运行骨架可能成为 debug-loop 反馈环的起点或真实测试的输入样例——那是**下游复用**，不是原型的职责。
+
+## 13. Minimal skeleton（LOGIC, Python）
+
+```python
+# prototype: <slug> — throwaway，回答：「________________」  （§4 设计问题）
+# 运行: python run.py；不接真实依赖；答案折叠后清理或留证（§9/§10）
+
+# --- logic (portable) ---
+def next_state(current: str, event: str) -> str:
+    transitions = {
+        ("idle", "start"): "running",
+        ("running", "stop"): "stopped",
+    }
+    return transitions.get((current, event), current)
+
+# --- demo entry ---
+if __name__ == "__main__":
+    state = "idle"
+    for event in ["start", "pause", "stop"]:
+        state = next_state(state, event)
+        print(f"{event:>8} -> {state}")   # 状态可见：每次 action 后打印
+```
+
+## 14. Checklist
+
+- [ ] §4 设计问题已写清（一句话，在文件头）
+- [ ] 形态：LOGIC / Python 单脚本；UI 不适用（未写 UI 脚手架）
+- [ ] 不接真实 DB / 服务；无持久化（或显式临时文件且会清理）
+- [ ] 无测试、无泛化——可跑即可
+- [ ] 状态可见：关键状态每次 action 后打印
+- [ ] 答案已折叠（写回 design / prd / 真实代码；**重写不 mv**）
+- [ ] 留证已落（git throwaway 分支，或非 git 路径快照到任务 `research/`）
+- [ ] 清理完成：`.tmp/prototypes/<slug>/` 已删，无工作区腐烂

package/dist/templates/markdown/spec/guides/retrieval-daily-guide.md.txt

@@ -20,6 +20,10 @@ Ask: *If this answer were wrong because the world or a third-party API moved, wo
 **NO examples:** symbol location / call chains; in-repo Trellis contracts; behavior of the code you are editing; pure rename/lint inside known files.  
 After search: persist under `{TASK}/research/` with a **provider label**; treat hits as candidates until corroborated (repo, test, or second source).
 
+## Primary source preference
+
+Prefer **primary sources** — official docs, source code, first-party API references, release notes, standards text. Mark blog posts, aggregators, and unverified second-hand summaries as **secondary** until corroborated against a primary source or the repo. This layers on top of "hits as candidates until corroborated": it ranks *which* candidates to trust first, and does not change the smart-search mandatory-first rule above.
+
 ## Prefer / Adapt / Own (code intelligence)
 
 | Need | **Prefer** (Cursor native) | **Adapt** | **Own** (codegraph / MCP) |

package/dist/templates/markdown/spec/guides/test-discipline-guide.md.txt

@@ -0,0 +1,138 @@
+# Test Discipline Guide（测试纪律）
+
+> **Purpose**: 测试写作纪律 —— pre-agreed seams、垂直切片、三反模式、mock 边界，让写出来的测试值得保留。**纪律不是 TDD 要求**；写测试、读测试、评审测试时都适用，与是否测试先行无关。
+
+---
+
+## 1. Purpose — discipline, not TDD
+
+本 guide 定义「测试写作纪律」：当测试存在时（新写、补写、评审、bug 回归落地），它们应当落在哪、验证什么、不做什么。纪律约束的是测试**质量**，不是测试**时序**：
+
+- **不要求 red-before-green**。可以先写测试（test-first 是可选的节奏），也可以实现后补测试——纪律在两种时序下同样适用。
+- **不强制 TDD 循环**。本 guide 不定义 red → green → refactor 流程；不设「每个函数必须单测」门槛。
+- 与 [Verification Strength Guide](./verification-strength-guide.md) 兼容：验证**强度**（任务 closeout 要验多深）≠ red-green 仪式；本 guide 管的是「测试怎么写才值得保留」。
+
+> 一句话：**先确认测点（seam），再写测试；测试验公共行为，不验实现。**
+
+## 2. Non-goals
+
+- **不是 TDD 手册**：不要求测试先行，不要求红-绿循环，不把 red-before-green 写成强制流程。
+- **不选型**：不规定 pytest 以外的框架，不做 mock 库选型。
+- **不替代 Verification Strength Guide**：验证强度（closeout 深度 / false-green 探针）由该 guide 管，本 guide 只管测试写作本身。
+- **不替代 Debug Loop Guide Phase 5**：bug 驱动的回归落地由 debug-loop 管，本 guide 只定义何为 good seam（见 §9）。
+
+## 3. What a good test is
+
+好测试的判据，对每次测试写作生效：
+
+- **通过公共 interface 验行为，不验实现细节**。module 可以完全重写，测试不该跟着改；测试关心调用者能获得什么行为，不关心内部怎么拼。
+- **读起来像规格**。测试名描述能力（「用户可以用有效购物车结账」），读者从测试就能看出 module 支持什么。
+- **耐重构**。重构后行为不变，测试仍绿；只有行为真正变化时才变红。
+- **期望值来自独立事实源**。已知字面量、手算样例、规格值——不是用实现同款方式重算（见 §6 tautological）。
+
+## 4. Seams（pre-agreed）
+
+**seam**（词汇与 CONTEXT.md architecture 段一致）：*不改动原处即可改变行为的位置*。测试在 seam 处通过 interface 观察行为，绝不伸手进内部。
+
+**只在 pre-agreed seam 写测试。** 写任何测试之前：
+
+1. **列出待测 seam 清单**：要测哪些 module 的哪个 interface、每条验什么行为。
+2. **与用户确认**。未确认的 seam 不写测试。
+3. 确认时按此排序：**优先既有 seam**（已有接口 / 既有测试点，不为测试新建结构）；**尽量高位 seam**（越接近用户行为越好——一条高位测试覆盖多个低位实现）；**少而精**（宁可一条高位测试，不要十条内部断言）。
+
+你不可能测完一切——预先同意 seam，是把测试力气花在关键路径和复杂逻辑上，而不是每个边角。
+
+> 问句：「公共 interface 是什么？我们要测哪些 seam？」——接口形状本身有疑问时（module 多深、seam 该在哪），先做设计，再定测点。
+
+## 5. Vertical slices（tracer bullets）
+
+**一测 → 一段最小实现 → 重复**：
+
+1. 一个 seam、一条测试（tracer bullet）。
+2. 只写让这条测试通过的最小实现。
+3. 重复，让每条新测试回应上一条循环学到的形状。
+
+**禁止 horizontal bulk**——先写完全部测试再实现。横向批量的危害：测试验证的是**想象的行为**（测的是形状而不是用户行为）、对真实变化不敏感、实现还没理解就锁死了测试结构。
+
+垂直切片在测试**写作**上同样成立：不要在动手前批量铺测试，一条一条来。
+
+## 6. Anti-patterns（三反模式）
+
+### Implementation-coupled（实现耦合）
+
+mock 内部协作对象、测私有方法、或旁路验证（绕过 interface 直接查库 / 读内部状态）。
+
+- 识别信号：重构后测试变红但行为没变；测试名描述 HOW 不描述 WHAT；断言调用次数 / 调用顺序。
+- 反例：`create_user` 后直接查库验入库——应通过 interface 验「创建后能取回」。
+- 修正：回到 §3——只通过公共 interface 观察行为。
+
+### Tautological（同义反复）
+
+期望值用与实现相同的方式重算，passes by construction——测试永远不可能与代码不一致，因为它复述了代码。
+
+- 识别信号：期望值是 reduce / 拼接 / 同式重算；快照由实现同款手工推出；常量断言等于它自己。
+- 反例：`expect(total([10, 5])).toBe(items.reduce(...))`——期望值就是实现。
+- 修正：期望值必须来自独立事实源——已知字面量（`expect(total([10, 5])).toBe(15)`）、手算样例、规格值。
+
+### Horizontal slicing（横向切片）
+
+先写全部测试再实现；按层横切而不是按用户行为竖切。
+
+- 识别信号：测试一次性铺满所有层级（API 层全部 → 服务层全部 → …）；测试对象是「形状」而非行为；实现未动时测试结构已锁定。
+- 修正：回到 §5 垂直切片。
+
+## 7. Mock boundaries
+
+**只在系统边界 mock**：
+
+- 外部 API（支付、邮件等）
+- DB（**优先用测试库**，mock DB 是退路）
+- 时间 / 随机性
+- 文件系统（视情况）
+
+**不 mock**：
+
+- 自己的 module / 内部协作对象
+- 任何我们控制的东西
+
+为可 mock 性设计接口：
+
+- **DI 优于内部 `new`**：外部依赖从参数传入，而不是在实现里创建：
+
+```python
+# 易 mock：依赖注入
+def process_payment(order, payment_client):
+    return payment_client.charge(order.total)
+
+# 难 mock：实现内部创建
+def process_payment(order):
+    client = PaymentClient(os.environ["PAYMENT_KEY"])
+    return client.charge(order.total)
+```
+
+- **SDK 式接口优于通用 fetcher**：每个外部操作用独立函数（`get_user(id)` / `create_order(data)`），而不是一个带条件分支的通用 `fetch(endpoint, opts)`。每个 mock 返回一种确定形状，测试设置里没有条件逻辑，也容易看出测试走了哪个端点。
+
+## 8. Relation to verification-strength-guide
+
+- Verification Strength Guide 管验证**强度**：任务 closeout 要验多深、false-green 探针，且明确 **not TDD**（§1 Non-goals：不产品化 red-green 仪式、无 per-function 单测门槛）。
+- 本 guide 管测试**写作质量**：测试存在时，落在 pre-agreed seam、验公共行为、避开三反模式。
+- 二者正交、兼容：按验证强度选验证深度；按本 guide 写测试。**验证强度 ≠ red-green 仪式。**
+
+## 9. Relation to debug-loop Phase 5（衔接不吞并）
+
+[Debug Loop Guide](./debug-loop-guide.md) Phase 5 的回归是 **bug 驱动**：把最小复现冻结成测试或可重复命令，且必须落在 **correct seam**（在真实调用点复现真实 bug 模式）。
+
+- **bug 回归走 debug-loop**：Phase 5 决定「把这个 bug 锁在哪个 seam」，本 guide 不接管闭环流程。
+- **通用测试写作走本 guide**：新功能、补测、评审由本 guide 管（pre-agreed seam、反模式、mock 边界）。
+- 衔接点：Phase 5 判定 correct seam 时，引用的正是本 guide 的 good seam 概念与反模式——**衔接不吞并**：bug 驱动回归 ≠ 通用测试写作，两者各有入口，互不替代。
+
+## 10. Checklist before writing tests
+
+写测试前确认：
+
+- [ ] seam 清单已列出并与用户确认（**未确认的 seam 不写测试**）
+- [ ] 优先既有 seam / 高位 seam / 少而精
+- [ ] 测试通过公共 interface 验行为（不是私有方法、不是内部协作对象）
+- [ ] 期望值来自独立事实源（已知字面量 / 样例 / 规格），不是实现同款重算
+- [ ] mock 只在系统边界；自己的 module 不 mock；依赖经 DI 注入
+- [ ] 一次一条垂直切片（一测 → 最小实现 → 重复），不做横向批量

package/dist/templates/markdown/spec/guides/verification-strength-guide.md.txt

@@ -9,6 +9,7 @@
 - **No TDD productization** — cstl does not require red-green-refactor loops, "write tests first" gates, or per-function unit test mandates.
 - **No per-task full-suite burden** — Lite tasks must not be forced through architecture review or whole-repo CI.
 - **No replacement for project test frameworks** — cstl validation checks **task evidence** in `verify.md` and configured quality gates; it does not run or replace your project's test runner.
+- **No test-writing mandate** — how to write good tests (pre-agreed seams, anti-patterns, mock boundaries) lives in the [Test Discipline Guide](./test-discipline-guide.md); verification strength is orthogonal to test-writing style.
 
 ---
 

package/dist/templates/trellis/CONTEXT.md

@@ -0,0 +1,53 @@
+# CONTEXT
+
+Project domain glossary — the single source of truth for project-specific terms used in this repository. Read **on demand** when project terms matter (e.g. before planning questions, PRD writing, or check reviews); **never always-inject** — this file stays out of the automatic session prompt budget.
+
+Only project-specific concepts belong here; generic programming concepts and framework terms already documented under `.cstl/` do not need entries. Each entry: term + one-line definition + `_Avoid_` aliases when a common synonym causes confusion. Language follows `artifact_locale` (en → English only; zh → Chinese terms with English gloss).
+
+## Framework domain seed (optional)
+
+Optional starting set — delete entries that do not apply to this project:
+
+**Task** (_task_):
+CSTL task, directory under `.cstl/tasks/`, lifecycle planning / in_progress / completed.
+_Avoid_: ticket, issue
+
+**PRD** (_product requirements document_):
+Task requirements artifact: Goal / User Stories / Requirements / Acceptance Criteria / Implementation Decisions.
+_Avoid_: spec sheet
+
+**Gate** (_gate_):
+Mandatory checkpoint at planning / execution / archive boundaries.
+_Avoid_: — 
+
+**Evidence** (_evidence_):
+Verification evidence in `verify.md` (command output, paths, acceptance).
+_Avoid_: report
+
+**Contract** (_contract_):
+Execution contract in `implement.md` (execution_mode / verification_profile / quality_gates).
+_Avoid_: plan
+
+**Child** (_child_):
+Independently verifiable deliverable under a Parent task tree.
+_Avoid_: sub-ticket
+
+**artifact_locale** (_artifact locale_):
+Project artifact language setting (en / zh).
+_Avoid_: locale
+
+**Task Ladder** (_task ladder_):
+Triage ladder: No Task / Micro-Grill / Lite / Full / Parent.
+_Avoid_: — 
+
+## Project glossary
+
+Add project-specific terms below (term + one-line definition + `_Avoid_` aliases):
+
+| Term | Definition | Avoid |
+| --- | --- | --- |
+| _TBD_ | | |
+
+## ADR
+
+Architecture decisions live in `docs/adr/` (lazy-created). Write an ADR only when **all three** conditions hold: hard to reverse · would surprise without context · real tradeoff. See `docs/adr/README.md` for the full boundary.

package/dist/templates/trellis/docs/adr/README.md

@@ -0,0 +1,21 @@
+# ADR — Architecture Decision Records
+
+`docs/adr/` records architecture decisions. **Lazy-created**: the directory and `0001-*.md` files appear only when a real decision needs recording — do not pre-create them.
+
+## When to write an ADR (all three conditions)
+
+Write an ADR only when **all three** hold:
+
+1. **Hard to reverse** — the decision is difficult or expensive to undo.
+2. **Would surprise without context** — a future reader would ask "why is it this way?" without background.
+3. **Real tradeoff** — there was a genuine choice between viable alternatives.
+
+A single paragraph is enough. Number sequentially: `0001-<slug>.md`, `0002-<slug>.md`, …
+
+## Three-layer boundary
+
+| Layer | Owns |
+| --- | --- |
+| Knowledge base (rejections) | Rejection reasons / why-not |
+| `docs/adr/` | Decision records / why-chosen |
+| `.cstl/spec/` | Coding guidelines / conventions |

package/dist/templates/trellis/index.d.ts

@@ -36,6 +36,8 @@ export declare const commonTaskContext: string;
 export declare const commonTaskStore: string;
 export declare const commonTaskDashboard: string;
 export declare const commonTaskGates: string;
+export declare const commonTaskDependencies: string;
+export declare const commonPoolStore: string;
 export declare const commonExecutionStrategy: string;
 export declare const executionStrategyRulesJson: string;
 export declare const commonTaskMap: string;
@@ -72,6 +74,8 @@ export declare const commonSafeCommit: string;
 export declare const getDeveloperScript: string;
 export declare const initDeveloperScript: string;
 export declare const taskScript: string;
+export declare const poolScript: string;
+export declare const verifyEvidenceProbeScript: string;
 export declare const getContextScript: string;
 export declare const addSessionScript: string;
 export declare const searchArtifactsScript: string;
@@ -84,6 +88,11 @@ export declare const codegraphSessionSmokeScript: string;
 export declare const workflowMdTemplate: string;
 export declare const configYamlTemplate: string;
 export declare const gitignoreTemplate: string;
+export declare const contextMdTemplate: string;
+export declare const adrReadmeTemplate: string;
+export declare const poolReadmeTemplate: string;
+export declare const poolPlanTemplate: string;
+export declare const poolItemsGitkeepTemplate: string;
 /**
  * Optional task artifact templates (under `.cstl/tasks/templates/`).
  * Not applied by `task.py create`; copy into a new task directory when starting
@@ -100,4 +109,9 @@ export declare const MAINTAINER_ONLY_SCRIPT_PATHS: Set<string>;
  * Init and update both use this as the single source of truth (no full-dir copy).
  */
 export declare function getAllScripts(): Map<string, string>;
+/**
+ * Review-pool skeleton files under `.cstl/pool/` (mechanism only).
+ * Init and update write these so users get pool CLI docs without sample items.
+ */
+export declare function getAllPoolSkeleton(): Map<string, string>;
 //# sourceMappingURL=index.d.ts.map

package/dist/templates/trellis/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/templates/trellis/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/templates/trellis/index.ts"],"names":[],"mappings":"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"}