@blxzer/cursor-trellis 0.3.4 → 0.3.6

package/dist/templates/markdown/spec/guides/cursor-context-injection-guide.md.txt

@@ -4,29 +4,29 @@
 
 ---
 
-## The channel matrix (verified 2026-06-19)
+## The channel matrix (verified 2026-08-05, Cursor Native 3.8.x)
 
-Cursor has **four** channels that can put text in front of the model. They are **not** equally reliable:
+Cursor has **several** channels that can put text in front of the model. They are **not** equally reliable:
 
 | Channel | How it loads | Reliable on Cursor? | Trellis content here |
 |---|---|---|---|
-| `.cursor/rules/*.mdc` (`alwaysApply: true`) | Prepended before **every** prompt, independent path | ✅ **Yes** | `cstl-triage.mdc` (Request Triage hard gate) |
-| `beforeSubmitPrompt` hook → `additional_context` | Per user message; router emits `## 代码库检索计划` | ⚠️ **Verify on your Cursor build** (docs list field; forum reports vary) | `inject-retrieval-plan.py` + `retrieval-routing.mdc` enforcement |
-| `AGENTS.md` (repo root + nested) | Read automatically, treated as an always-on rule | ✅ **Yes** | smart-search-first rule, command surface, remote policy (the `<!-- TRELLIS:START -->` block) |
-| `sessionStart` hook → `additional_context` | Hook fires, JSON parsed... **but content never reaches the model's system context** | ❌ **No (confirmed bug)** | workflow.md Phase Index + Task Dashboard + first-reply notice |
+| `.cursor/rules/*.mdc` (`alwaysApply: true`) | Prepended before **every** prompt, independent path | ✅ **Yes** | `cstl-triage.mdc` (Request Triage hard gate), `retrieval-routing.mdc`, `cstl-cursor-modes.mdc` (Prefer native modes) |
+| `AGENTS.md` (repo root + nested) | Read automatically, treated as an always-on rule | ✅ **Yes** | smart-search-first rule, command surface (the `<!-- CSTL:START -->` block) |
+| `sessionStart` hook → `additional_context` | Once per session; delivered via `hooks_context` | ✅ **Yes** (fixed — verified 2026-08-05; was #158452) | Task Dashboard, workflow Phase Index summary, first-reply notice |
+| `beforeSubmitPrompt` hook → `additional_context` | Per user message; router would emit `## 代码库检索计划` | ❌ **No (telemetry-only since 2026-06-24)** | `inject-retrieval-plan.py` logs to `.cstl/.runtime/retrieval-plan-events.log`; **no injection** |
 | `.cstl/workflow.md` (read on demand) | Only if the agent explicitly runs `get_context.py` or reads the file | ⚠️ Depends on agent taking action | Full Request Triage section, Task Ladder, workflow-state breadcrumbs |
-| **`task.py generate-dispatch-prompt` → Task `prompt`** (CLI Layer 2) | Main session runs Trellis script before `Task(...)` | ✅ **Yes (primary for subagent task context on Cursor)** | Full embed: marker, `Selected task:`, prd/jsonl/spec bodies |
+| **`task.py generate-dispatch-prompt` → Task `prompt`** (CLI Layer 2) | Main session runs Trellis script before `Task(...)` | ✅ **Yes (primary for subagent task context on Cursor)** | Full embed: marker, `Selected task:`, prd/jsonl/spec bodies (budgeted — see [injection-budget-guide](./injection-budget-guide.md)) |
 
-**Key takeaway**: anything that must reach the model **every turn without the agent choosing to load it** must live in `.cursor/rules` or `AGENTS.md`. Subagent task context on Cursor uses **CLI Layer 2** before Task dispatch; `preToolUse` hook injection is best-effort only (see forum reports + 2026-06-22 spike). Anything in `workflow.md` that depends on `sessionStart` injection is **invisible to Cursor agents** until the bug is fixed.
+**Key takeaway**: anything that must reach the model **every turn** must live in `.cursor/rules` or `AGENTS.md`. `sessionStart` is reliable for **session-level** orientation (dashboard, workflow summary) but fires only once. Retrieval plans: use **Rules default tool order** or run `route_codebase_retrieval.py --instructions` on demand — do **not** rely on `beforeSubmitPrompt` injection. Subagent task context uses **CLI Layer 2** before Task dispatch.
 
 ---
 
-## The sessionStart bug (why this guide exists)
+## The sessionStart bug (#158452) — history and current status
 
-- **Bug**: Cursor forum #158452 — `sessionStart` hook `additional_context` is executed and JSON-parsed correctly, but the value is **never added to the agent's initial system context**.
-- **Status**: Confirmed by Cursor team (deanrie), internal bug filed, **no ETA** as of 2026-06-19.
-- **Scope**: Affects `sessionStart` and `postToolUse` `additional_context` on Cursor IDE. The `env` field of the same hook **does** work (separate storage path).
-- **Symptom**: hook runs (verifiable via side-channel log), valid JSON emitted, but the agent has zero awareness of the injected text (e.g. won't say a first-reply notice phrase).
+- **Bug**: Cursor forum #158452 — `sessionStart` hook `additional_context` was executed and JSON-parsed correctly, but the value was **not added to the agent's initial system context** (through ~2026-06).
+- **Status (2026-08-05)**: **Fixed** on Cursor Native 3.8.x — first-reply-notice probe passes; `hooks_context` contains full SessionStart payload. Re-verify after major Cursor upgrades.
+- **Historical scope**: Also affected `postToolUse` `additional_context` on some builds. The `env` field of the same hook uses a separate storage path.
+- **Routing implication**: Even with sessionStart working, **per-turn hard gates** (Triage, retrieval policy) stay in `.cursor/rules` — sessionStart fires only once per session.
 
 ### How to diagnose "is sessionStart injection actually reaching the model?"
 
@@ -38,23 +38,39 @@ Cursor has **four** channels that can put text in front of the model. They are *
 
 ## Trellis routing rules on Cursor
 
-Because of the bug, Trellis routes content by reliability on Cursor:
+Trellis routes content by reliability on Cursor:
 
 | Trellis content | Where it lives | Why |
 |---|---|---|
-| **Request Triage hard gate** (classify every turn, emit `[Triage: <Mode>]`) | `.cursor/rules/cstl-triage.mdc` (`alwaysApply: true`) | Must be visible every turn; sessionStart path is broken |
-| **smart-search-first web routing** | `AGENTS.md` (TRELLIS:START block) | AGENTS.md is a reliable always-on channel |
-| **Command surface** (what's user-invocable vs internal skill) | `AGENTS.md` (TRELLIS:START block) | Same |
-| **Workflow phases, Task Ladder, workflow-state breadcrumbs** | `.cstl/workflow.md` | Loaded on demand via `get_context.py` / `cstl-start` / `cstl-continue`; NOT auto-injected on Cursor |
+| **Request Triage hard gate** (classify every turn, emit `[Triage: <Mode>]`) | `.cursor/rules/cstl-triage.mdc` (`alwaysApply: true`) | Must be visible **every turn**; sessionStart is once-per-session |
+| **Codebase retrieval policy** | `.cursor/rules/retrieval-routing.mdc` + `route_codebase_retrieval.py` | `beforeSubmitPrompt` injection is telemetry-only; Rules + router CLI |
+| **Prefer Cursor native modes** (Plan/Ask/Debug/Agent/Multitask × Trellis) | `.cursor/rules/cstl-cursor-modes.mdc` + `cursor-native-modes-guide.md` | P1 orchestration; full table on demand in guide |
+| **smart-search-first web routing** | `AGENTS.md` (CSTL block) | AGENTS.md is a reliable always-on channel |
+| **Command surface** (what's user-invocable vs internal skill) | `AGENTS.md` (CSTL block) | Same |
+| **Session orientation** (dashboard, workflow summary, first-reply notice) | `sessionStart` hook → `additional_context` | Reliable on Cursor 3.8.x+; session-level only |
+| **Workflow phases, Task Ladder, workflow-state breadcrumbs** | `.cstl/workflow.md` + sessionStart summary | Full detail on demand via `get_context.py` / `cstl-continue` |
 
-**If a new "must-always-be-visible" rule is added to Trellis**: ship it as a `.cursor/rules/*.mdc` (Cursor) — do **not** rely on adding it to `workflow.md` and expecting sessionStart to deliver it.
+**If a new "must-always-be-visible" rule is added to Trellis**: ship it as a `.cursor/rules/*.mdc` (Cursor) — do **not** rely on `workflow.md` or sessionStart alone for per-turn enforcement. Run `injection_budget_probe.py` after adding rules (see [injection-budget-guide](./injection-budget-guide.md)).
+
+---
+
+## Injection budget (P0)
+
+Per-channel caps and jsonl/Layer 2 limits are defined in **[injection-budget-guide](./injection-budget-guide.md)**. Summary from channel matrix (2026-08-06):
+
+- **Per-turn:** C01 Rules + C02 AGENTS only (not C04).
+- **Session once:** C03 sessionStart dashboard/workflow.
+- **Subagent:** C06 Layer 2 with role `max_chars` + jsonl entry/file/total caps.
+- **Retrieval:** C16 Rules + router CLI on demand.
+
+Probe: `python ./.cstl/scripts/injection_budget_probe.py --repo-root .`
 
 ---
 
 ## When to update this guide
 
-- Cursor ships a fix for forum #158452 → mark the sessionStart row as "✅ Yes (fixed in version X)" and re-evaluate whether workflow.md content can move back to sessionStart-only.
-- A new Cursor injection channel appears (e.g. a working per-turn `beforeSubmitPrompt.additional_context`) → add a row to the matrix.
+- Cursor major upgrade → re-run sessionStart first-reply-notice probe and update the matrix date.
+- `beforeSubmitPrompt.additional_context` becomes reliable on a future build → re-enable injection in `inject-retrieval-plan.py` and update this guide.
 - Trellis adds a new `.cursor/rules/*.mdc` → add a row to the routing table.
 
 ---
@@ -62,6 +78,7 @@ Because of the bug, Trellis routes content by reliability on Cursor:
 ## Related
 
 - `cursor-subagent-policy.md` — Task tool scenes, model routing (this guide is about **context injection**, that one is about **subagent dispatch**).
+- `cursor-native-modes-guide.md` — Prefer Plan/Ask/Debug/Agent/Multitask; pairs with `cstl-cursor-modes.mdc`.
 - `.cstl/workflow.md` → `### Request Triage` — the full Triage decision tree (the rule in `.cursor/rules/cstl-triage.mdc` is the slim always-apply version pointing here).
 - Task `06-19-cursor-rules-triage` (archive) — the investigation that produced this guide.
 - Cursor forum thread: https://forum.cursor.com/t/sessionstart-hook-additional-context-is-never-injected-into-agents-initial-system-context/158452

package/dist/templates/markdown/spec/guides/cursor-native-modes-guide.md.txt

@@ -0,0 +1,125 @@
+# Cursor native modes — Prefer & orchestrate (don't replace)
+
+> **Purpose**: Task-drive Cursor **Plan / Ask / Debug / Agent / Multitask** into Trellis phases and artifacts. Prefer native when callable; **quietly** fall back to the cstl spine when not. Do **not** reimplement modes or publish an “unsupported mode” list.
+>
+> **Product anchor**: `.cstl/workspace/cursor-trellis-product-positioning.md` (P1).
+>
+> **Design lock**: Parent `research/task-driven-modes-design-lock-2026-08-06.md`.
+>
+> **Evidence**: `{TASK}/research/cursor-modes-external.md`, `{TASK}/research/modes-callability-matrix.md`.
+>
+> **Rollback**: [Rollback](#rollback).
+
+---
+
+## Principle
+
+| Layer | Duty |
+| --- | --- |
+| **Cursor native** | Plan / Ask / Debug / Agent / Multitask — **try task-driven use first** |
+| **cstl spine** | Triage / Phase / gates / artifacts / Parent integration — **quiet fallback** when native cannot be driven well |
+
+**Prefer native. Invent less.** Failures drop to existing cstl paths with little commentary — never a user-facing “本版本不适配某 mode” section.
+
+---
+
+## Prefer / Adapt table (mode × Trellis × artifacts)
+
+| Cursor mode | Prefer when | Task-driven Prefer | Quiet cstl fallback | Durable artifacts |
+| --- | --- | --- | --- | --- |
+| **Ask** | Explain / lookup; **no** durable change | Prefer Ask UI / side chat when the user is already there; Agent cannot `SwitchMode`→Ask | In-session **No Task** behavior (read-only, no `task.py create` without consent) | None |
+| **Plan** | Scope / design / tradeoffs before code | **Try `SwitchMode(plan)`**; after review, `SwitchMode(agent)` or Build; **Save to workspace** → map into task files | Keep writing `prd.md` / `design.md` / `implement.md` + `cstl-brainstorm` in Agent | Phase 1 files |
+| **Agent** | Approved build / verify | Default; `SwitchMode(agent)` when returning from Plan | — | Diff, `verify.md`, gates |
+| **Debug** | Repro / runtime / regressions | Prefer real Cursor Debug when the user/session can reach it | Evidence → `verify.md`; `cstl-break-loop` if looped | Notes / logs in `verify.md` |
+| **Multitask** | Independent Parent children post-approval | Prefer `/multitask` / Build in Parallel / Agent `Task` background workers **when useful** | Explicit `.cstl/tasks/<dir>` prompts + Parent `integrate-child` | Child `verify`/`handoff`; Parent `task-map` |
+
+### Phase quick map
+
+```
+Triage (No Task / Micro-Grill)  → Ask surface if present; else No Task in Agent
+Phase 1                         → SwitchMode(plan) when useful; else write artifacts in Agent
+Phase 2–3                       → Agent (+ workers when contracted)
+Stuck / repeat failure          → Debug when reachable; else verify.md + break-loop
+Parent parallel children        → Multitask / Task parallel when useful; Parent integrates
+```
+
+---
+
+## Mode-specific contracts
+
+### Ask ↔ No Task
+
+- Official Ask does not edit files. Agent tools cannot switch into Ask.
+- Classify **No Task** for pure Q&A; no task creation without consent.
+- Side chats (3.11) complement Ask during Agent runs — still not Trellis artifacts.
+
+### Plan ↔ Phase 1
+
+- Prefer **`SwitchMode(plan)`** for design-heavy Phase 1; care about switch-back quality.
+- Default plan save = **home directory** — **Save to workspace**, then map to `{TASK}/prd.md`, `design.md`, `implement.md`.
+- Does **not** skip `start-execution --check` / execution approval.
+- If Plan switch or save flow is poor: **quietly** author the same files in Agent.
+
+### Debug ↔ evidence
+
+- Prefer Cursor Debug instrumentation when reachable.
+- Always land proof in **`verify.md`**. Contract change → Return-to-Planning.
+
+### Multitask ↔ Parent/Child
+
+1. Trellis remains source of truth for status, gates, integration.
+2. Prefer native parallel surfaces to support independent Children when they help isolation/throughput.
+3. Every worker prompt includes **explicit `.cstl/tasks/<dir>`** — never rely on `selected_task`.
+4. Parent alone `integrate-child`; no collision guarantee without worktrees + review.
+
+---
+
+## Callability (Agent tool table)
+
+| Surface | Plan | Agent | Ask | Debug | Parallel Children |
+| --- | --- | --- | --- | --- | --- |
+| Agent `SwitchMode` | Yes → `plan` | Yes → `agent` | — | — | — |
+| Agent `Task` / Multitask | — | workers | — | — | Prefer when useful |
+| User / CLI modes | Plan UI / `/plan` | default | Ask UI / `/ask` | Debug UI | `/multitask`, Build in Parallel |
+
+Details: `research/modes-callability-matrix.md`.
+
+---
+
+## What cstl must not claim
+
+- Plans auto-save into `.cstl/tasks/`.
+- Multitask inherits `selected_task` or exposes a stable programmatic mode API.
+- Parallel agents cannot conflict without Trellis/worktree discipline.
+- `SwitchMode` can open Ask or Debug.
+- Shipping a parallel fake Plan/Ask/Debug product, or documenting gaps as “本版本不适配”.
+
+---
+
+## Dogfood / probes
+
+| Mode | Minimum probe | Pass when |
+| --- | --- | --- |
+| **Plan** | Schema or live `SwitchMode(plan)` note in verify | Prefer path documented; quiet Agent fallback if unused |
+| **Ask / Debug** | Callability matrix | Quiet spine behavior; no “不适配” section |
+| **Multitask** | Task parallel or doc contract | Explicit child paths; Parent integrates |
+| **Agent** | Session implements under contract | Artifacts on disk |
+
+---
+
+## Rollback
+
+Docs + rules only:
+
+1. Delete `.cursor/rules/cstl-cursor-modes.mdc` and `.cstl/spec/guides/cursor-native-modes-guide.md`.
+2. Drop related `guides/index.md` / `workflow.md` rows, or `cstl update` from pre-P1 templates.
+3. **cursor-trellis**: revert this Child’s tip or delete mirrored template paths.
+
+---
+
+## Related
+
+- `{TASK}/research/modes-callability-matrix.md`
+- `{TASK}/research/cursor-modes-external.md`
+- `.cursor/rules/cstl-cursor-modes.mdc`
+- `.cstl/spec/guides/cursor-subagent-policy.md`

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

@@ -1,104 +1,107 @@
-# 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 |
+| [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 |
+| [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.

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

@@ -0,0 +1,111 @@
+# Injection Budget Guide
+
+> **Purpose**: Allocate context injection across **reliable Cursor channels** with measurable caps —「完整 = 证据密度」, not unbounded prose.
+
+**Matrix input:** `08-06-cstl-p0-channel-baseline-matrix` → `research/channel-matrix.md` (C01–C04, C16).
+
+---
+
+## 1. Non-goals
+
+- **No `beforeSubmitPrompt` injection** — C04 stays telemetry-only until Cursor changelog proves otherwise.
+- **No black-box silent injection** — Layer 2 and jsonl loads emit stderr manifest lines.
+- **No weakening gates** — Triage (`cstl-triage.mdc`), execution approval, and retrieval policy remain always-on.
+- **No Auto-Trigger Skill as retrieval primary** — C16 stays Rules + `route_codebase_retrieval.py --instructions`.
+
+---
+
+## 2. Channel budget tiers
+
+| Tier | Channels | When | Budget |
+| --- | --- | --- | --- |
+| **Per-turn hard** | C01 Rules, C02 AGENTS | Every agent turn | Rules total warn 20 KiB / fail 32 KiB; AGENTS CSTL block warn 4 KiB |
+| **Session once** | C03 sessionStart | New session | Keep dashboard/workflow summary compact; not a substitute for per-turn rules |
+| **Zero** | C04 beforeSubmit | Every message | **0** — log only |
+| **Subagent only** | C06 Layer 2 | `generate_dispatch_prompt` → Task | Role default `max_chars` + jsonl caps (§3) |
+| **On demand** | C16 retrieval | When agent needs a plan | Rules default order or router CLI; no per-message plan block |
+
+---
+
+## 3. JSONL manifest budgets (implement / check)
+
+Curate **spec/research only** — never pre-register code paths you will edit.
+
+| Limit | Value | Enforcement |
+| --- | --- | --- |
+| Max entries | 8 | Skip excess at Layer 2 load; `task.py validate` WARN |
+| Max single expansion | 12,000 chars | Skip file/directory block |
+| Max total jsonl body | 48,000 chars | Skip when cumulative would exceed |
+
+**Curator rules:**
+
+1. Prefer **index + one layer spec** over whole package trees.
+2. Use `task.py add-context` with a one-line **reason** (replayable intent).
+3. Delete the seed `_example` row when adding real entries.
+4. Full task artifacts (`prd.md`, `design.md`, `implement.md`) are **always** embedded separately — do not duplicate them in jsonl.
+
+**Dispatch manifest (stderr):**
+
+```text
+[subagent-dispatch] injection-budget: .cstl/tasks/.../implement.jsonl loaded 2 entries (8421 chars): ...
+[subagent-dispatch] injection-budget: skipped path: total cap (...)
+```
+
+---
+
+## 4. Layer 2 role defaults
+
+When `--max-chars` is omitted, `generate_dispatch_prompt.py` uses:
+
+| Role | Default `max_chars` |
+| --- | --- |
+| implement | 96,000 |
+| check | 64,000 |
+| research | 48,000 |
+
+Override per dispatch when a task truly needs more — document the override in `implement.md` DSC and `verify.md`.
+
+Truncation order after jsonl budget: whole context string tail-truncated with `...[truncated]...` warning.
+
+---
+
+## 5. alwaysApply rule hygiene
+
+Before adding a new `.cursor/rules/*.mdc` with `alwaysApply: true`:
+
+1. Confirm the content **must** be visible **every turn** (see `cursor-context-injection-guide.md`).
+2. Run `python ./.cstl/scripts/injection_budget_probe.py --repo-root .`.
+3. If total alwaysApply exceeds **20 KiB**, trim or move detail to on-demand spec / `get_context.py`.
+
+**Rollback:** remove or scope the new rule; re-run probe.
+
+---
+
+## 6. Observability probe
+
+```powershell
+# Workspace surfaces
+python ./.cstl/scripts/injection_budget_probe.py --repo-root .
+
+# Task jsonl + dispatch size
+python ./.cstl/scripts/injection_budget_probe.py --repo-root . --task .cstl/tasks/<task-dir> --dispatch-role implement
+
+# CI / gate style (fail on WARN or rules >32KiB)
+python ./.cstl/scripts/injection_budget_probe.py --repo-root . --strict
+```
+
+Constants live in `.cstl/scripts/common/injection_budget.py` (single source).
+
+---
+
+## 7. Related
+
+- [Cursor context injection guide](./cursor-context-injection-guide.md) — channel reliability matrix
+- [Cursor subagent policy](./cursor-subagent-policy.md) — Layer 2 dispatch contract
+- [Verification strength guide](./verification-strength-guide.md) — evidence density for closeout (orthogonal axis)
+
+---
+
+## 8. Rollback
+
+Revert `injection_budget.py`, probe script, `subagent_dispatch` budget branch, validate WARNs, and this guide. Layer 2 returns to unbounded jsonl expansion; C04 remains telemetry-only.