@blxzer/cursor-trellis 0.3.6 → 0.4.1

package/dist/templates/cursor/commands/handoff.md

@@ -0,0 +1,99 @@
+# Session Handoff (cstl-handoff)
+
+Condense the current session into a **portable** handoff document (`cstl-handoff-{yyyyMMdd-HHmmss}-{slug}.md`), written to the **OS temp directory** (does not pollute the workspace), so a new agent can continue without the original session. This command is the Cursor invocation surface for the `cstl-handoff` skill — mirror of `common/bundled-skills/cstl-handoff/SKILL.md`; keep the two aligned when editing.
+
+---
+
+## When to use / when not
+
+At stage boundaries first ask: **does the work still continue in this session?**
+
+1. **Continue** — default preference: keep going in this session
+2. **Clear** — context can be dropped; clear and restart
+3. **Handoff** — the work needs to travel → this command
+4. **Subagent** — a side branch can run in parallel while the main session stays → dispatch a subagent (optionally with a handoff file)
+5. **Compact** — same harness, same directory, only intent compression needed → use the platform compact
+
+**Handoff only when the work needs to travel**: switch harness, switch directory / repo, hand to a colleague, or fork a side branch. Same harness + same directory continuation → compact / continue, not handoff.
+
+## How this differs from a task `handoff.md` (read first)
+
+| | This command (session handoff) | Task `handoff.md` |
+| --- | --- | --- |
+| What | Portable cross-session summary | Child-task integration / implementation-window **delivery evidence** |
+| Where | OS temp directory (volatile) | `.cstl/tasks/<task>/` (durable, archived with the task) |
+| Lifecycle | Single transfer; dead once the work lands | Kept with the task evidence for Parent / review traces |
+
+A task directory's `handoff.md` is the evidence file for `integrate-child` / `review-child`, **not** a session handoff document; the temp file this command produces is **not** task evidence.
+
+## Steps
+
+1. **Read the user argument**: the "next-session purpose" passed on invocation decides which whys to keep (trim key decision rationale by purpose — do not take everything verbatim).
+2. **Write the temp file** (path rules below).
+3. **Report the full absolute path** (required): temp paths are long and differ per OS; the user must get the path first.
+4. **Remind about volatility**: the temp file may be cleaned by the environment (Codex clears temp across sessions; `/private/tmp` is lost on reboot). For cross-hour / cross-harness continuation, ask the user to copy it to a durable location immediately.
+
+### Path rules
+
+```text
+$env:TEMP\cstl-handoff-{yyyyMMdd-HHmmss}-{slug}.md
+```
+
+- Windows: `$env:TEMP` (i.e. `%TEMP%`)
+- Linux / macOS: `$TMPDIR/cstl-handoff-{yyyyMMdd-HHmmss}-{slug}.md` (`/tmp` when `$TMPDIR` is unset)
+- Always report the **full absolute path** to the user after writing — never just the filename.
+
+## Content template (English skeleton)
+
+> Follow `artifact_locale` when the project uses it; English by default.
+
+```markdown
+# Session handoff — <work summary>
+
+> Generated by cstl-handoff at <time> · Next-session purpose: <user argument>
+
+## Goal
+<what the in-flight work is trying to achieve>
+
+## Done
+- <items>
+
+## Not done / Blocked
+- <items>
+
+## Next steps
+1. <ordered steps>
+
+## Key whys (trimmed by next-session purpose)
+- <decision + reason; whys unrelated to this purpose can be omitted>
+
+## Facts vs unverified beliefs
+- Facts: <verified>
+- Beliefs (unverified): <assumptions — never write them as facts>
+
+## Pointers (reference paths only, never copy bodies)
+- Task: `.cstl/tasks/<task>/` (prd.md / design.md / implement.md / verify.md)
+- Context: `CONTEXT.md` · Research: `<task>/research/`
+- Prototype evidence (if a prototype was involved): `<task>/research/prototype-<slug>.py` (see `.cstl/spec/guides/prototype-guide.md` §9)
+- Other: ADR / issue / commit / diff paths or URLs
+
+## Suggested skills (for the continuing agent)
+- <skill name list, e.g. cstl-brainstorm, cstl-check, cstl-continue>
+```
+
+## Rules
+
+- **Reference, don't copy**: anything already on disk (spec / PRD / ADR / issue / commit / diff) gets a path or URL only, never pasted verbatim.
+- **Redact**: API keys, tokens, passwords, PII → replace with `<REDACTED>` before writing; when unsure, write `<REDACTED>`.
+- **Facts vs beliefs**: unverified assumptions must be marked, never written as verified facts — the continuing agent will treat the document as a contract and will not re-check.
+- **Prototype evidence pointer**: when the session involved a prototype, list the prototype evidence path in the pointers section and confirm the evidence is captured before cleanup.
+- **Delivery**: have the new agent **read the file path**; do not stuff the summary into shell quotes to launch the new agent (backticks / `$(...)` get swallowed and silently truncated).
+
+## Anti-patterns
+
+- ❌ Treating handoff as a long-lived document: it is a transit document for a single transfer and dies once the work lands (long-term facts belong in `AGENTS.md` / spec, not handoff)
+- ❌ Pasting large spec / PRD / diff bodies (should reference paths only)
+- ❌ Stuffing the summary into shell quotes to launch the next agent (silent truncation risk)
+- ❌ Not reporting the full path / not reminding about temp volatility
+- ❌ Writing a handoff for same-harness same-directory continuation (should compact / continue)
+- ❌ Writing keys / tokens into the document

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

@@ -33,4 +33,10 @@ export declare const guidesCursorContextInjectionGuideContent: string;
 export declare const guidesCursorNativeModesGuideContent: string;
 export declare const guidesVerificationStrengthGuideContent: string;
 export declare const guidesInjectionBudgetGuideContent: string;
+export declare const guidesArtifactLocaleGuideContent: string;
+export declare const guidesDebugLoopGuideContent: string;
+export declare const guidesGoalReleaseRegressionRunbookContent: string;
+export declare const guidesPrototypeGuideContent: string;
+export declare const guidesTestDisciplineGuideContent: string;
+export declare const guidesCrossPlatformThinkingGuideContent: string;
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/templates/markdown/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAqBH,eAAO,MAAM,eAAe,EAAE,MAAuC,CAAC;AAGtE,eAAO,MAAM,qBAAqB,EAAE,MACK,CAAC;AAG1C,eAAO,MAAM,yBAAyB,QAAwB,CAAC;AAG/D,eAAO,MAAM,wBAAwB,EAAE,MACH,CAAC;AAQrC,eAAO,MAAM,mBAAmB,EAAE,MAEjC,CAAC;AACF,eAAO,MAAM,gCAAgC,EAAE,MAE9C,CAAC;AACF,eAAO,MAAM,gCAAgC,EAAE,MAE9C,CAAC;AACF,eAAO,MAAM,+BAA+B,EAAE,MAE7C,CAAC;AACF,eAAO,MAAM,+BAA+B,EAAE,MAE7C,CAAC;AACF,eAAO,MAAM,2BAA2B,EAAE,MAEzC,CAAC;AAGF,eAAO,MAAM,oBAAoB,EAAE,MAElC,CAAC;AACF,eAAO,MAAM,iCAAiC,EAAE,MAE/C,CAAC;AACF,eAAO,MAAM,yBAAyB,EAAE,MAEvC,CAAC;AACF,eAAO,MAAM,6BAA6B,EAAE,MAE3C,CAAC;AACF,eAAO,MAAM,kCAAkC,EAAE,MAEhD,CAAC;AACF,eAAO,MAAM,gCAAgC,EAAE,MAE9C,CAAC;AACF,eAAO,MAAM,8BAA8B,EAAE,MAE5C,CAAC;AAGF,eAAO,MAAM,kBAAkB,EAAE,MAEhC,CAAC;AACF,eAAO,MAAM,oCAAoC,EAAE,MAElD,CAAC;AACF,eAAO,MAAM,mCAAmC,EAAE,MAEjD,CAAC;AACF,eAAO,MAAM,yCAAyC,EAAE,MACiB,CAAC;AAC1E,eAAO,MAAM,gCAAgC,EAAE,MAE9C,CAAC;AACF,eAAO,MAAM,qCAAqC,EAAE,MAEnD,CAAC;AACF,eAAO,MAAM,iCAAiC,EAAE,MAE/C,CAAC;AACF,eAAO,MAAM,8BAA8B,EAAE,MAE5C,CAAC;AACF,eAAO,MAAM,wCAAwC,EAAE,MACiB,CAAC;AACzE,eAAO,MAAM,mCAAmC,EAAE,MAEjD,CAAC;AACF,eAAO,MAAM,sCAAsC,EAAE,MAEpD,CAAC;AACF,eAAO,MAAM,iCAAiC,EAAE,MAE/C,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/templates/markdown/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAqBH,eAAO,MAAM,eAAe,EAAE,MAAuC,CAAC;AAGtE,eAAO,MAAM,qBAAqB,EAAE,MACK,CAAC;AAG1C,eAAO,MAAM,yBAAyB,QAAwB,CAAC;AAG/D,eAAO,MAAM,wBAAwB,EAAE,MACH,CAAC;AAQrC,eAAO,MAAM,mBAAmB,EAAE,MAEjC,CAAC;AACF,eAAO,MAAM,gCAAgC,EAAE,MAE9C,CAAC;AACF,eAAO,MAAM,gCAAgC,EAAE,MAE9C,CAAC;AACF,eAAO,MAAM,+BAA+B,EAAE,MAE7C,CAAC;AACF,eAAO,MAAM,+BAA+B,EAAE,MAE7C,CAAC;AACF,eAAO,MAAM,2BAA2B,EAAE,MAEzC,CAAC;AAGF,eAAO,MAAM,oBAAoB,EAAE,MAElC,CAAC;AACF,eAAO,MAAM,iCAAiC,EAAE,MAE/C,CAAC;AACF,eAAO,MAAM,yBAAyB,EAAE,MAEvC,CAAC;AACF,eAAO,MAAM,6BAA6B,EAAE,MAE3C,CAAC;AACF,eAAO,MAAM,kCAAkC,EAAE,MAEhD,CAAC;AACF,eAAO,MAAM,gCAAgC,EAAE,MAE9C,CAAC;AACF,eAAO,MAAM,8BAA8B,EAAE,MAE5C,CAAC;AAGF,eAAO,MAAM,kBAAkB,EAAE,MAEhC,CAAC;AACF,eAAO,MAAM,oCAAoC,EAAE,MAElD,CAAC;AACF,eAAO,MAAM,mCAAmC,EAAE,MAEjD,CAAC;AACF,eAAO,MAAM,yCAAyC,EAAE,MACiB,CAAC;AAC1E,eAAO,MAAM,gCAAgC,EAAE,MAE9C,CAAC;AACF,eAAO,MAAM,qCAAqC,EAAE,MAEnD,CAAC;AACF,eAAO,MAAM,iCAAiC,EAAE,MAE/C,CAAC;AACF,eAAO,MAAM,8BAA8B,EAAE,MAE5C,CAAC;AACF,eAAO,MAAM,wCAAwC,EAAE,MACiB,CAAC;AACzE,eAAO,MAAM,mCAAmC,EAAE,MAEjD,CAAC;AACF,eAAO,MAAM,sCAAsC,EAAE,MAEpD,CAAC;AACF,eAAO,MAAM,iCAAiC,EAAE,MAE/C,CAAC;AACF,eAAO,MAAM,gCAAgC,EAAE,MAE9C,CAAC;AACF,eAAO,MAAM,2BAA2B,EAAE,MAEzC,CAAC;AACF,eAAO,MAAM,yCAAyC,EAAE,MACiB,CAAC;AAC1E,eAAO,MAAM,2BAA2B,EAAE,MAEzC,CAAC;AACF,eAAO,MAAM,gCAAgC,EAAE,MAE9C,CAAC;AACF,eAAO,MAAM,uCAAuC,EAAE,MACiB,CAAC"}

package/dist/templates/markdown/index.js

@@ -58,4 +58,10 @@ export const guidesCursorContextInjectionGuideContent = readLocalTemplate("spec/
 export const guidesCursorNativeModesGuideContent = readLocalTemplate("spec/guides/cursor-native-modes-guide.md.txt");
 export const guidesVerificationStrengthGuideContent = readLocalTemplate("spec/guides/verification-strength-guide.md.txt");
 export const guidesInjectionBudgetGuideContent = readLocalTemplate("spec/guides/injection-budget-guide.md.txt");
+export const guidesArtifactLocaleGuideContent = readLocalTemplate("spec/guides/artifact-locale-guide.md.txt");
+export const guidesDebugLoopGuideContent = readLocalTemplate("spec/guides/debug-loop-guide.md.txt");
+export const guidesGoalReleaseRegressionRunbookContent = readLocalTemplate("spec/guides/goal-release-regression-runbook.md.txt");
+export const guidesPrototypeGuideContent = readLocalTemplate("spec/guides/prototype-guide.md.txt");
+export const guidesTestDisciplineGuideContent = readLocalTemplate("spec/guides/test-discipline-guide.md.txt");
+export const guidesCrossPlatformThinkingGuideContent = readLocalTemplate("spec/guides/cross-platform-thinking-guide.md.txt");
 //# sourceMappingURL=index.js.map

package/dist/templates/markdown/index.js.map

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

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

@@ -0,0 +1,93 @@
+# Human-Reviewed Artifact Locale Guide
+
+> **Purpose:** Let PRD / DESIGN / IMPLEMENT / VERIFY / HANDOFF follow the user's language (Chinese or English) without turning Trellis into a full i18n product.
+
+---
+
+## 1. Non-goals
+
+| In scope | Out of scope |
+| --- | --- |
+| Workspace / task `artifact_locale` | Full CLI `--help` / stderr i18n |
+| `task.py create` PRD seed language | Auto-translating archived tasks |
+| Session / planning hints for artifact language | Bilingual mirrors of `workflow.md` or `.cursor/rules` |
+| `prd.md` / `design.md` / `implement.md` / `verify.md` / `handoff.md` | `task.json` field names or gate enums |
+
+**Rollback:** `python ./.cstl/scripts/task.py artifact-locale set zh` or remove `artifact_locale` from `.cstl/config.yaml`. For a single task, delete `task.json` → `meta.artifact_locale`.
+
+---
+
+## 2. Configuration
+
+### Workspace default (`.cstl/config.yaml`)
+
+```yaml
+# Human-reviewed artifact locale (zh | en)
+artifact_locale: zh
+```
+
+Default when unset: **`zh`** (matches current dogfood and User Rules for Simplified Chinese replies).
+
+### CLI
+
+```powershell
+# Resolved locale (workspace default)
+python ./.cstl/scripts/task.py artifact-locale get
+
+# Resolved locale for one task (includes task override)
+python ./.cstl/scripts/task.py artifact-locale get --task .cstl/tasks/<dir>
+
+# Workspace default
+python ./.cstl/scripts/task.py artifact-locale set en
+python ./.cstl/scripts/task.py artifact-locale set zh
+
+# Per-task override
+python ./.cstl/scripts/task.py artifact-locale set zh --task .cstl/tasks/<dir>
+```
+
+Invalid values print a warning and fall back to the next layer (`task` → `workspace` → `zh`).
+
+---
+
+## 3. What respects locale
+
+| Artifact | Mechanism |
+| --- | --- |
+| `prd.md` on `task.py create` | Locale template under `.cstl/tasks/locale/{zh,en}/default-prd.md` |
+| `design.md` / `implement.md` | Agent planning (session context + `cstl-brainstorm`) |
+| `verify.md` / `handoff.md` | Agent execution / finish (same session hint) |
+| Optional `tasks/templates/*` copies | Agent follows guide; English paths stay canonical |
+
+**Does not change:** existing files in a task directory, CLI diagnostics, hooks, or machine gate names.
+
+---
+
+## 4. Dogfood checklist
+
+1. `artifact-locale set en` → `task.py create "Locale EN" --slug locale-dogfood-en` → `prd.md` uses `## Goal`, `## Requirements`.
+2. `artifact-locale set zh` → `task.py create "Locale ZH" --slug locale-dogfood-zh` → `prd.md` uses `## 目标`, `## 需求`.
+3. With workspace `en`, `artifact-locale set zh --task <dir>` → next create for that task only uses Chinese if `meta.artifact_locale` was set before create (override applies to resolved locale for that task).
+
+---
+
+## 5. Orthogonal `locale` settings
+
+| Setting | Purpose |
+| --- | --- |
+| **`artifact_locale`** (this guide) | Human-reviewed task artifacts |
+| Retrieval / semantic `locale` | Code search ranking and plan language |
+| smart-search `locale-scope` | External research evidence language |
+
+Do not merge these keys; they solve different problems.
+
+---
+
+## 6. Rollback
+
+1. `artifact-locale set zh` (workspace).
+2. Remove `meta.artifact_locale` from any task that should follow workspace only.
+3. Revert code/templates if needed — default `zh` keeps dogfood behavior without config.
+
+---
+
+**Core principle:** Product language follows the user for artifacts they review; infrastructure stays English unless explicitly scoped.

package/dist/templates/markdown/spec/guides/cross-platform-thinking-guide.md.txt

@@ -40,7 +40,7 @@ print("Run: script.py <args>")
 
 # GOOD - Platform-aware wording
 print("Usage: python on Windows, python3 elsewhere")
-print("Run: {{PYTHON_CMD}} ./.cstl/scripts/task.py <args>")
+print("Run: {{PYTHON_CMD}} ./.trellis/scripts/task.py <args>")
 ```
 
 **Rule 2**: When generating config files at init time, use placeholder + platform detection:
@@ -281,7 +281,7 @@ make the intended decision. Otherwise a transient sandbox/network failure hides
 the hint for the rest of the session.
 
 **Rule 2**: If a local command can provide the needed value, try it with a short
-timeout and captured output. For example, `cstl --version` already runs the
+timeout and captured output. For example, `trellis --version` already runs the
 CLI's version comparison logic and can support an actionable update prompt
 without duplicating npm registry parsing.
 
@@ -356,7 +356,7 @@ When making platform-related changes, check **all these locations**:
 
 ### Code Locations
 - [ ] `src/templates/` - Template files for new projects
-- [ ] `.cstl/scripts/` - Project's own scripts (if self-hosting)
+- [ ] `.trellis/scripts/` - Project's own scripts (if self-hosting)
 - [ ] `dist/` - Built output (rebuild after changes)
 
 ### Search Pattern
@@ -530,7 +530,7 @@ subprocess.run(["./script.py"])  # FileNotFoundError
 
 ```
 src/templates/script.py  ← Updated
-.cstl/scripts/script.py  ← Forgot to sync!
+.trellis/scripts/script.py  ← Forgot to sync!
 ```
 
 ### 4. "Python 3 is always python3"
@@ -606,8 +606,8 @@ included with Trellis, verify the whole distribution path:
 - [ ] `pnpm build` copies the asset into `dist/templates/**`.
 - [ ] `npm pack --dry-run --json` includes the expected `dist/**` path.
 - [ ] The built binary installs the asset in a fresh temp repository.
-- [ ] `.cstl/.template-hashes.json` tracks the generated asset path.
-- [ ] `cstl update --dry-run` reports `Already up to date!` in that temp
+- [ ] `.trellis/.template-hashes.json` tracks the generated asset path.
+- [ ] `trellis update --dry-run` reports `Already up to date!` in that temp
   repository.
 
 **Why this matters**: docs/changelog text can move independently from the code
@@ -628,7 +628,7 @@ git -C "$tmpdir" init -q
   cd "$tmpdir"
   node /path/to/Trellis/packages/cli/bin/trellis.js init -u smoke --yes --cursor
   test -f .cursor/skills/<skill>/SKILL.md
-  grep -q '<skill>' .cstl/.template-hashes.json
+  grep -q '<skill>' .trellis/.template-hashes.json
   node /path/to/Trellis/packages/cli/bin/trellis.js update --dry-run
 )
 ```

package/dist/templates/markdown/spec/guides/cursor-subagent-policy.md.txt

@@ -96,19 +96,21 @@ When research is purely **codebase exploration** (no external web search, no fil
 
 ### Method 2.5: Cursor++ BYOK proxy map (publishable bundle)
 
-**What it is:** A reversible patch to Cursor++ `extension.js` resolver `WPeLc8` that maps `subagentType` → BYOK catalog **slug** (`model-xxxxx`), evaluated **before** the inherit-parent branch. Verified 2026-06-18 (Cursor++ v0.0.11).
+**What it is:** A reversible patch to Cursor++ `extension.js` **subagent model resolver** that maps `subagentType` → BYOK catalog **slug** (`model-xxxxx`), evaluated **before** the inherit-parent branch. Obfuscated symbol names change per build (historical `WPeLc8`; 2026-08+ profile `ZiKp4I`). Script uses multi-profile detection.
 
-**Trellis ships (every `cstl init` / `cstl update`, strategy C):** `.cstl/local/cursor2plus/` — `patch_wpelc8.py`, `README.md`, `config.local.json.example`. Native Cursor API users can ignore this directory.
+**Trellis ships (every `cstl init` / `cstl update`, strategy C):** `.cstl/local/cursor2plus/` — `patch_wpelc8.py`, `README.md`, **`UPGRADE-NOTE.md`** (upgrade re-apply), `config.local.json.example`. Native Cursor API users can ignore this directory.
 
 **Operator workflow (Cursor++ BYOK only):**
 
-1. Fill **`~/.ccursor/trellis-task-models.json`** (user-wide) with `subagent_type` → slug from **`~/.ccursor/providers.json`** `id` fields.
-2. Optionally override per repo: **`.cstl/local/subagent-models.json`** (project wins on same key).
+1. Fill **`~/.ccursor/trellis-task-models.json5`** (user-wide) with `subagent_type` → displayName/apiModel from **`~/.ccursor/providers.json`**.
+2. Optionally override per repo: **`.cstl/local/subagent-models.json5`** (project wins on same key).
 3. If paths are not auto-detected: copy `config.local.json.example` → `config.local.json`, or run `python patch_wpelc8.py --bootstrap`, or set `TRELLIS_CCURSOR_HOME` / `TRELLIS_CURSOR2PLUS_EXTENSION`.
-4. From `.cstl/local/cursor2plus/`: `python patch_wpelc8.py --print-map` → `python patch_wpelc8.py` → **Developer: Reload Window**.
-5. **Verify:** `taskToolCall dispatching` → `resolvedModelId` matches slug.
+4. From `.cstl/local/cursor2plus/`: `python patch_wpelc8.py --check-compat` → `--print-map` → `--apply --approve` → **Developer: Reload Window**.
+5. **Verify:** A≠B probe (parent model ≠ map target) or `resolvedModelId` matches slug.
 
-**Revert:** `python patch_wpelc8.py --revert`; Reload Window. Re-run patch after Cursor / Cursor++ upgrades.
+**Revert:** `python patch_wpelc8.py --revert`; Reload Window.
+
+**After any Cursor / Cursor++ upgrade:** assume patch is stale — follow **`.cstl/local/cursor2plus/UPGRADE-NOTE.md`** (`--check-compat`, re-apply, or add a new resolver profile if symbols moved).
 
 **Cursor++ sidebar / Cursor Settings:** Do **not** wire `cstl-*` BYOK routing; use JSON + patch.
 
@@ -203,7 +205,7 @@ When a dispatch is imminent:
 
 ### Technical note
 
-Client layer still only builds override rows for built-in types such as `explore`. Cursor Settings entries for custom agent **names** do not reach the BYOK proxy override list for `cstl-*`. **Method 2.5** patches Cursor++ `WPeLc8` so `taskToolCall` sets `resolvedModelId` from a local `subagentType → slug` table before inherit-parent. **Method 3** bypasses Task routing (user picks model in a new chat).
+Client layer still only builds override rows for built-in types such as `explore`. Cursor Settings entries for custom agent **names** do not reach the BYOK proxy override list for `cstl-*`. **Method 2.5** patches Cursor++ subagent model resolver (profile-bound; see `UPGRADE-NOTE.md`) so `taskToolCall` sets `resolvedModelId` from a local `subagentType → slug` table before inherit-parent. **Method 3** bypasses Task routing (user picks model in a new chat).
 
 ---
 

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)