@blxzer/cursor-trellis 0.3.5 → 0.4.0

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

@@ -0,0 +1,227 @@
+# Debug Loop Guide
+
+> **Purpose**: 调试纪律 —— 先建 tight、red-capable 反馈环，再假设、再修，一次到位找到并修对；与 `cstl-break-loop` 划界（诊断进行中 vs 修完后防再发），互不替代。
+
+---
+
+## 1. Purpose / Non-goals
+
+**Purpose.** Hard bugs and performance regressions are not solved by reading code — they are solved by building a **tight, red-capable feedback loop** first, then letting hypotheses consume it. This guide defines the discipline: build the loop → reproduce → hypothesise → probe one variable at a time → freeze the loop as a regression → clean up and hand off to prevention.
+
+**Non-goals**
+
+- **Not a mandate for every bug.** A lightweight bug (obvious at a glance, provable in a single step) may skip the full loop — but you must state **one sentence** explaining why the full cycle was skipped.
+- **Not a replacement for `cstl-break-loop`.** This guide owns *diagnosis in progress*; break-loop owns *post-fix root cause classification / prevention / knowledge capture* (see §2).
+- **No production instrumentation** unless the user explicitly permits it. If you cannot build a loop without instrumenting production, stop and ask (see Phase 1 "genuinely cannot build a loop").
+- **Not TDD ceremony.** Phase 5 freezes the loop as a test *or* a repeatable command — whichever is the correct seam.
+
+## 2. Boundary with cstl-break-loop
+
+| | **debug-loop-guide** (this guide) | **cstl-break-loop** |
+| --- | --- | --- |
+| 时机 | 诊断与修复**进行中**（建环 → 修） | 修复**完成后**（深分析） |
+| 目标 | 一次到位找到并修对（red 环、假设表、修复、清理） | 根因分类（A–E）、为何修失败、防再发机制、入 spec |
+| 输出 | 红环、3–5 假设排名、修复、回归、清理 | 5 维分析、prevention、knowledge capture 到 guides |
+| 触发 | 用户报 bug / 性能回归，进入诊断 | `/cstl:break-loop` 或修完后的任务收尾 |
+
+**二者不互相替代**：debug-loop-guide 结束时若只修完没做根因分类，同类 bug 会再发；cstl-break-loop 不帮你找到原因（它在修完之后才启动）。Phase 6 的 post-mortem 钩子负责把两者接起来。
+
+## 3. Hard rule: no red-capable loop → no hypotheses
+
+> **硬纪律：无 red-capable 反馈环，不得进入假设阶段；禁止先读代码猜原因。**
+
+A **red-capable** loop is **one command** that you have **already run at least once** (show the invocation and its redacted output), and that simultaneously:
+
+- **Drives the path of the user's symptom** — it exercises the actual bug code path, not "it didn't crash".
+- **Can go red and green** — it goes red on *this* bug and turns green once fixed.
+- **Is as deterministic, fast, and agent-runnable as possible** — seconds, unattended; a human in the loop only via the PowerShell HITL template (§12).
+
+If you catch yourself reading code to build a theory before this command exists — **stop**. Jumping straight to a hypothesis is the exact failure this discipline prevents. No red-capable command, no Phase 2.
+
+**If you genuinely cannot build a loop**: stop and say so explicitly. List what you tried. Ask the user for (a) access to the environment that reproduces it, (b) a redacted captured artifact (HAR file, log dump, core dump, screen recording with timestamps), or (c) **explicit permission** to add temporary production instrumentation. Do **not** proceed to hypothesise without a loop.
+
+## 4. Lightweight escape hatch
+
+A lightweight bug — one visible at a glance, provable in a single step (typo, obvious off-by-one, missing export) — may skip the full cycle. The only requirement: **one sentence explaining why the full loop was skipped** (e.g. "single-line typo, provable by one compile run; full loop skipped"). Hard bugs and performance regressions **default to the full loop**.
+
+## 5. Redact
+
+This guide makes you show commands, outputs and captured artifacts. **Redact every secret first** — write `<REDACTED>` in its place.
+
+- Build loops against **env vars** so credentials stay in the environment, never in what you show.
+- Captured artifacts carry auth headers: **quote only the lines that carry the signal**, not the whole blob.
+- If the redacted output is not enough to diagnose the bug, say so and ask the user — do not leak secrets to move faster.
+
+## 6. Phase 1 — Build a tight feedback loop
+
+**This is the phase.** Everything else is mechanical. If you have a **tight** pass/fail signal for the bug — one that goes red on *this* bug — you will find the cause; bisection, hypothesis-testing, and instrumentation just consume it. If you don't have one, no amount of staring at code will save you. Spend disproportionate effort here. **Be aggressive. Be creative. Refuse to give up.**
+
+### Ways to construct one — try them in roughly this order
+
+1. **Failing test** at whatever seam reaches the bug — unit, integration, e2e.
+2. **Curl / HTTP script** against a running dev server.
+3. **CLI invocation** with a fixture input, diffing stdout against a known-good snapshot.
+4. **Headless browser script** (Playwright / Puppeteer) — drives the UI, asserts on DOM/console/network.
+5. **Replay a captured trace.** Save a real network request / payload / event log to disk; replay it through the code path in isolation.
+6. **Throwaway harness.** Spin up a minimal subset of the system (one service, mocked deps) that exercises the bug code path with a single function call.
+7. **Property / fuzz loop.** If the bug is "sometimes wrong output", run 1000 random inputs and look for the failure mode.
+8. **Bisection harness.** If the bug appeared between two known states (commit, dataset, version), automate "boot at state X, check, repeat" so you can bisect it.
+9. **Differential loop.** Run the same input through old-version vs new-version (or two configs) and diff outputs.
+10. **HITL PowerShell script** (§12). Last resort. If a human must click, drive *them* with a structured loop so it is still a loop. Captured output feeds back to you.
+
+### Tighten the loop
+
+Treat the loop as a product. Once you have *a* loop, **tighten** it:
+
+- Can I make it **faster**? (Cache setup, skip unrelated init, narrow the test scope.)
+- Can I make the **signal sharper**? (Assert on the specific symptom, not "didn't crash".)
+- Can I make it **more deterministic**? (Pin time, seed RNG, isolate filesystem, freeze network.)
+
+A 30-second flaky loop is barely better than no loop; a 2-second deterministic one is a debugging superpower.
+
+### Non-deterministic bugs
+
+The goal is not a clean repro but a **higher reproduction rate**. Loop the trigger 100×, parallelise, add stress, narrow timing windows, inject sleeps. A 50%-flake bug is debuggable; 1% is not — keep raising the rate until it is debuggable.
+
+### Completion criterion — a tight loop that goes red
+
+Phase 1 is done when the loop is **tight** and **red-capable**: you can name **one command** — a script path, a test invocation, a curl — that you have **already run at least once** (show the invocation and its output, redacted), and that is:
+
+- [ ] **Red-capable** — drives the actual bug code path and asserts the **user's exact symptom**, so it can go red on this bug and green once fixed. Not "runs without erroring".
+- [ ] **Deterministic** — same verdict every run (flaky bugs: a pinned, high reproduction rate, per above).
+- [ ] **Fast** — seconds, not minutes.
+- [ ] **Agent-runnable** — unattended; a human in the loop only via the HITL template (§12).
+
+No red-capable command, no Phase 2.
+
+## 7. Phase 2 — Reproduce + minimise
+
+Run the loop. Watch it go red — the bug appears.
+
+Confirm:
+
+- [ ] The loop produces the failure mode the **user** described — not a different failure that happens to be nearby. Wrong bug = wrong fix.
+- [ ] The failure is reproducible across multiple runs (or, for non-deterministic bugs, reproducible at a high enough rate to debug against).
+- [ ] You have captured the exact symptom (error message, wrong output, slow timing) so later phases can verify the fix actually addresses it.
+
+### Minimise
+
+Once it is red, shrink the repro to the **smallest scenario that still goes red**. Cut inputs, callers, config, data, and steps **one at a time**, re-running the loop after each cut — keep only what is load-bearing for the failure. A minimal repro shrinks the Phase 3 hypothesis space (fewer moving parts to suspect) and becomes the clean Phase 5 regression. Done when **every remaining element is load-bearing** — removing any one of them makes the loop go green.
+
+Do not proceed until you have reproduced **and** minimised.
+
+## 8. Phase 3 — Ranked falsifiable hypotheses (show user)
+
+Generate **3–5 ranked hypotheses** before testing any of them. Single-hypothesis generation anchors on the first plausible idea.
+
+Each hypothesis must be **falsifiable**: state the prediction it makes.
+
+> Format: "If `<X>` is the cause, then `<changing Y>` will make the bug disappear / `<changing Z>` will make it worse."
+
+If you cannot state the prediction, the hypothesis is a vibe — discard or sharpen it.
+
+**Show the ranked list to the user before testing.** They often have domain knowledge that re-ranks instantly ("we just deployed a change to #3"), or know hypotheses they have already ruled out. Cheap checkpoint, big time saver. Don't block on it — proceed with your ranking if the user is AFK.
+
+## 9. Phase 4 — One-variable probes / instrumentation
+
+Each probe must map to a specific prediction from Phase 3. **Change one variable at a time.**
+
+Tool preference:
+
+1. **Debugger / REPL inspection** if the environment supports it. One breakpoint beats ten logs.
+2. **Targeted logs** at the boundaries that distinguish hypotheses.
+3. Never "log everything and grep".
+
+**Tag every debug log with a unique prefix**, e.g. `[DEBUG-a4f2]` (or any equivalent uniform prefix). Cleanup at the end becomes a **single grep**: `grep -rn "\[DEBUG-" .` / `rg "\[DEBUG-"` — every tagged line dies, untagged lines survive.
+
+**Perf branch.** For performance regressions, logs are usually wrong. Instead: establish a baseline measurement (timing harness, `performance.now()`, profiler, query plan), then bisect. Measure first, fix second.
+
+## 10. Phase 5 — Regression (freeze the loop)
+
+Freeze the loop as a test **or** a repeatable command — whichever has a **correct seam**.
+
+A correct seam is one where the test/command exercises the **real bug pattern** as it occurs at the call site. If the only available seam is too shallow (single-caller test when the bug needs multiple callers, unit test that cannot replicate the chain that triggered the bug), a regression there gives false confidence.
+
+**If no correct seam exists, that itself is the finding.** Note it — the architecture is preventing the bug from being locked down. Flag it for Phase 6 / break-loop.
+
+If a correct seam exists:
+
+1. Turn the minimised repro into a failing test (or a repeatable command) at that seam.
+2. Watch it fail.
+3. Apply the fix.
+4. Watch it pass.
+5. Re-run the Phase 1 feedback loop against the original (un-minimised) scenario.
+
+This phase hands off to the test-discipline scope (P08) without being absorbed by it: the loop here is bug-driven; test-discipline owns the general testing strategy.
+
+## 11. Phase 6 — Cleanup + post-mortem hook
+
+Required before declaring done:
+
+- [ ] Original repro no longer reproduces (re-run the Phase 1 loop)
+- [ ] Regression passes (or absence of seam is documented)
+- [ ] All `[DEBUG-...]` instrumentation removed — one grep, zero hits
+- [ ] Throwaway prototypes deleted (or moved to a clearly-marked debug location)
+- [ ] The hypothesis that turned out correct is stated in the commit / PR message — so the next debugger learns
+
+**Post-mortem hook:** then ask *what would have prevented this bug?* If the answer involves architectural change (no good test seam, tangled callers, hidden coupling), or the bug is worth classifying, run **`cstl-break-loop`** (root cause category A–E, why fixes failed, prevention mechanisms) and/or update the relevant spec/guide via **`cstl-update-spec`**. Make the recommendation **after** the fix is in, not before — you have more information now than when you started.
+
+## 12. PowerShell HITL template
+
+PowerShell 7 (user environment). Copy this file, edit the steps below, and run it. The agent runs the script; the user follows prompts in their terminal. Two helpers:
+
+- `Step "instruction"` → show instruction, wait for Enter
+- `$var = Capture "question"` → show question, read response; the returned value is echoed back, where the agent reads it — so capture observations, and leave signing in to the user as a `Step`
+
+At the end, captured values are printed as `KEY=VALUE` for the agent to parse.
+
+```powershell
+# Human-in-the-loop reproduction loop (PowerShell 7).
+# Usage:  ./hitl-loop.ps1
+# Edit the "--- edit below ---" section per bug, then run it.
+
+$ErrorActionPreference = 'Stop'
+
+function Step {
+    param([Parameter(Mandatory)][string]$Instruction)
+    Write-Host ''
+    Write-Host ">>> $Instruction" -ForegroundColor Cyan
+    [void](Read-Host "    [Enter when done] ")
+}
+
+function Capture {
+    param([Parameter(Mandatory)][string]$Question)
+    Write-Host ''
+    Write-Host ">>> $Question" -ForegroundColor Cyan
+    $answer = Read-Host "    > "
+    Write-Host "    (captured: $answer)"
+    return $answer
+}
+
+# --- edit below ---------------------------------------------------------
+
+Step "Open the app at http://localhost:3000 and sign in."
+
+$ERRORED = Capture "Click the 'Export' button. Did it throw an error? (y/n)"
+
+$ERROR_MSG = Capture "Paste the error message (or 'none'):"
+
+# --- edit above ---------------------------------------------------------
+
+Write-Host ''
+Write-Host '--- Captured ---' -ForegroundColor Green
+Write-Host "ERRORED=$ERRORED"
+Write-Host "ERROR_MSG=$ERROR_MSG"
+```
+
+Adaptation notes for the agent: keep the loop **agent-runnable** where possible (headless/HTTP/CLI first); HITL only when a human must click or sign in. Never ask the user to paste secrets into the loop output — capture observations, leave signing in to the user as a `Step`.
+
+## 13. Completion checklist
+
+- [ ] Phase 1 loop exists, ran at least once, red-capable, deterministic, fast, agent-runnable (or escape hatch justified in one sentence)
+- [ ] Phase 2: reproduced the user's exact symptom; repro minimised until every element is load-bearing
+- [ ] Phase 3: 3–5 ranked falsifiable hypotheses, each with a stated prediction; shown to user
+- [ ] Phase 4: one variable per probe; debug logs tagged `[DEBUG-...]`
+- [ ] Phase 5: loop frozen as test or repeatable command at a correct seam (or absence of seam documented)
+- [ ] Phase 6: original repro green, instrumentation removed (one grep, zero hits), post-mortem hook to `cstl-break-loop` / `cstl-update-spec` decided
+- [ ] Everything shown to the user redacted (`<REDACTED>`, credentials via env)

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

@@ -1,104 +1,144 @@
-# Thinking Guides
-
-> **Purpose**: Expand your thinking to catch things you might not have considered.
-
----
-
-## Why Thinking Guides?
-
-**Most bugs and tech debt come from "didn't think of that"**, not from lack of skill:
-
-- Didn't think about what happens at layer boundaries → cross-layer bugs
-- Didn't think about code patterns repeating → duplicated code everywhere
-- Didn't think about edge cases → runtime errors
-- Didn't think about future maintainers → unreadable code
-
-These guides help you **ask the right questions before coding**.
-
----
-
-## Available Guides
-
-| Guide | Purpose | When to Use |
-|-------|---------|-------------|
-| [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` |
-| [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 |
-| [Retrieval daily guide](./retrieval-daily-guide.md) | rg / codegraph / fast-context / smart-search / pack / router | Planning, research, finish verification |
-| [Cursor semantic compliance](./cursor-semantic-compliance.md) | Native planned vs executed semantic (`SemanticSearch`, classify_tool_calls) | Retrieval eval, OC-15 compliance runs, telemetry interpretation |
-| [Cursor subagent policy](./cursor-subagent-policy.md) | Task tool scenes, Agent mode, `model_policy: cursor-configured`, Cursor++ | Parent/Child dispatch, research/implement/check, parallel execution |
-| [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-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 |
-
----
-
-## Quick Reference: Thinking Triggers
-
-### When to Think About Cross-Layer Issues
-
-- [ ] Feature touches 3+ layers (API, Service, Component, Database)
-- [ ] Data format changes between layers
-- [ ] Multiple consumers need the same data
-- [ ] You're not sure where to put some logic
-- [ ] You are adding an event kind, JSONL record, RPC payload, or config field
-- [ ] UI / command code starts casting raw payload fields directly
-
-→ Read [Cross-Layer Thinking Guide](./cross-layer-thinking-guide.md)
-
-### When to Think About Code Reuse
-
-- [ ] You're writing similar code to something that exists
-- [ ] You see the same pattern repeated 3+ times
-- [ ] You're adding a new field to multiple places
-- [ ] **You're modifying any constant or config**
-- [ ] **You're creating a new utility/helper function** ← Search first!
-- [ ] Two files read the same untyped payload field with local casts
-- [ ] Multiple branches update the same derived state from `kind` / `action`
-
-→ Read [Code Reuse Thinking Guide](./code-reuse-thinking-guide.md)
-
-### When Verifying AI Cross-Review Results
-
-- [ ] Reviewer claims "user input can be malicious" → Check the actual data source (internal manifest? user config? external API?)
-- [ ] Reviewer flags "missing validation" → Is the data from a trusted internal source?
-- [ ] Reviewer says "behavior change" → Read the code comments — is it intentional design?
-- [ ] Reviewer identifies a "bug" in test → Mentally delete the feature being tested — does the test still pass? If yes → tautological test
-
-**Common AI reviewer false-positive patterns**:
-1. **Trust boundary confusion**: Treating internal data (bundled JSON manifests) as untrusted external input
-2. **Ignoring design comments**: Flagging intentional behavior documented in code comments as bugs
-3. **Variable misreading**: Not tracing a variable to its actual definition (e.g., Map keyed by path vs name)
-
-**Verification rule**: Every CRITICAL/WARNING finding must be verified against the actual code before prioritizing. Budget ~35% false-positive rate for AI reviews.
-
----
-
-## Pre-Modification Rule (CRITICAL)
-
-> **Before changing ANY value, ALWAYS search first!**
-
-```bash
-# Search for the value you're about to change
-grep -r "value_to_change" .
-```
-
-This single habit prevents most "forgot to update X" bugs.
-
----
-
-## How to Use This Directory
-
-1. **Before coding**: Skim the relevant thinking guide
-2. **During coding**: If something feels repetitive or complex, check the guides
-3. **After bugs**: Add new insights to the relevant guide (learn from mistakes)
-
----
-
-## Contributing
-
-Found a new "didn't think of that" moment? Add it to the relevant guide.
-
----
-
-**Core Principle**: 30 minutes of thinking saves 3 hours of debugging.
+# Thinking Guides
+
+> **Purpose**: Expand your thinking to catch things you might not have considered.
+
+---
+
+## Why Thinking Guides?
+
+**Most bugs and tech debt come from "didn't think of that"**, not from lack of skill:
+
+- Didn't think about what happens at layer boundaries → cross-layer bugs
+- Didn't think about code patterns repeating → duplicated code everywhere
+- Didn't think about edge cases → runtime errors
+- Didn't think about future maintainers → unreadable code
+
+These guides help you **ask the right questions before coding**.
+
+---
+
+## Available Guides
+
+| Guide | Purpose | When to Use |
+|-------|---------|-------------|
+| [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 |
+| [Retrieval daily guide](./retrieval-daily-guide.md) | rg / codegraph / fast-context / smart-search / pack / router | Planning, research, finish verification |
+| [Cursor semantic compliance](./cursor-semantic-compliance.md) | Native planned vs executed semantic (`SemanticSearch`, classify_tool_calls) | Retrieval eval, OC-15 compliance runs, telemetry interpretation |
+| [Cursor subagent policy](./cursor-subagent-policy.md) | Task tool scenes, Agent mode, `model_policy: cursor-configured`, Cursor++ | Parent/Child dispatch, research/implement/check, parallel execution |
+| [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
+
+---
+
+## Quick Reference: Thinking Triggers
+
+### When to Think About Cross-Layer Issues
+
+- [ ] Feature touches 3+ layers (API, Service, Component, Database)
+- [ ] Data format changes between layers
+- [ ] Multiple consumers need the same data
+- [ ] You're not sure where to put some logic
+- [ ] You are adding an event kind, JSONL record, RPC payload, or config field
+- [ ] UI / command code starts casting raw payload fields directly
+
+→ Read [Cross-Layer Thinking Guide](./cross-layer-thinking-guide.md)
+
+### When to Think About Code Reuse
+
+- [ ] You're writing similar code to something that exists
+- [ ] You see the same pattern repeated 3+ times
+- [ ] You're adding a new field to multiple places
+- [ ] **You're modifying any constant or config**
+- [ ] **You're creating a new utility/helper function** ← Search first!
+- [ ] Two files read the same untyped payload field with local casts
+- [ ] Multiple branches update the same derived state from `kind` / `action`
+
+→ Read [Code Reuse Thinking Guide](./code-reuse-thinking-guide.md)
+
+### When Verifying AI Cross-Review Results
+
+- [ ] Reviewer claims "user input can be malicious" → Check the actual data source (internal manifest? user config? external API?)
+- [ ] Reviewer flags "missing validation" → Is the data from a trusted internal source?
+- [ ] Reviewer says "behavior change" → Read the code comments — is it intentional design?
+- [ ] Reviewer identifies a "bug" in test → Mentally delete the feature being tested — does the test still pass? If yes → tautological test
+
+**Common AI reviewer false-positive patterns**:
+1. **Trust boundary confusion**: Treating internal data (bundled JSON manifests) as untrusted external input
+2. **Ignoring design comments**: Flagging intentional behavior documented in code comments as bugs
+3. **Variable misreading**: Not tracing a variable to its actual definition (e.g., Map keyed by path vs name)
+
+**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)
+
+> **Before changing ANY value, ALWAYS search first!**
+
+```bash
+# Search for the value you're about to change
+grep -r "value_to_change" .
+```
+
+This single habit prevents most "forgot to update X" bugs.
+
+---
+
+## How to Use This Directory
+
+1. **Before coding**: Skim the relevant thinking guide
+2. **During coding**: If something feels repetitive or complex, check the guides
+3. **After bugs**: Add new insights to the relevant guide (learn from mistakes)
+
+---
+
+## Contributing
+
+Found a new "didn't think of that" moment? Add it to the relevant guide.
+
+---
+
+**Core Principle**: 30 minutes of thinking saves 3 hours of debugging.