@blxzer/cursor-trellis 0.3.5 → 0.3.6

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.

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

@@ -20,18 +20,36 @@ Ask: *If this answer were wrong because the world or a third-party API moved, wo
 **NO examples:** symbol location / call chains; in-repo Trellis contracts; behavior of the code you are editing; pure rename/lint inside known files.  
 After search: persist under `{TASK}/research/` with a **provider label**; treat hits as candidates until corroborated (repo, test, or second source).
 
+## Prefer / Adapt / Own (code intelligence)
+
+| Need | **Prefer** (Cursor native) | **Adapt** | **Own** (codegraph / MCP) |
+| --- | --- | --- | --- |
+| Exact literal / path | **Grep** (`rg`) | — | — |
+| Named-symbol definition | **Grep → Read** | Path hints from semantic when file unknown | codegraph when trap/overload/blast context |
+| IDE diagnostics | **ReadLints** | — | — |
+| Conceptual discovery | **@codebase** / built-in semantic (Native) | **fast_context_search** (BYOK) | — |
+| Caller chain / blast radius | Grep gap-fill | — | **codegraph** MCP |
+| Cross-package trap / extension | Grep scoped | — | **codegraph** MCP |
+| Raw LSP / GO_TO_DEFINITION | **Not in Agent tool table** — re-probe before claiming Prefer | — | codegraph product fallback |
+
+**Rollback:** restore pre-P1 codegraph-first definition rows in this guide + `.cursor/rules/retrieval-routing.mdc`; keep codegraph MCP enabled.
+
+**Evidence (2026-08-05):** `research/cursor-code-intel-external.md` — official Agent tools = search/read/edit (no LSP); semantic (@codebase) ≠ LSP; Agents Window LSP gap staff-confirmed on forum.
+
 ## Quick matrix
 
 | Need | Tool | Notes |
 | --- | --- | --- |
 | Exact string / path / log line | **rg** (Grep) | Fast literal match in repo |
-| Symbol, callers, edit blast radius | **codegraph** MCP | Structure-first for caller/trap/extension intents |
+| Named-symbol definition | **Grep → Read** (Prefer); **codegraph** when trap/blast | Native first; structure when ambiguous |
+| IDE diagnostics | **ReadLints** | Cursor-native linter/diagnostic surface |
+| Symbol, callers, edit blast radius | **codegraph** MCP | Own layer: structure-first for caller/trap/extension intents |
 | Unknown keywords, semantic discovery | **@codebase** (Cursor Native) / **fast-context** (Cursor++ BYOK) | Native: built-in semantic; BYOK: `fast_context_search` MCP (see `cursorEnv` in plans) |
 | External / current facts | **smart-search-cli** | **Mandatory first** — built-in web tools are downgrade-only (see rule above) |
 | Trellis durable docs | **artifact-search** | `search_artifacts.py` |
 | Past sessions | **session-memory** | Historical; verify against tasks/spec |
 | Intent hint for code questions | **router** | `route_codebase_retrieval.py` — plan JSON + `agentInstructions`; `--instructions` for steps only |
-| Agent follows plan on Cursor | **`beforeSubmitPrompt` → `inject-retrieval-plan.py`** + **`.cursor/rules/retrieval-routing.mdc`** | Per-turn plan block from router `--instructions`; Rules enforce execution; not `sessionStart` (#158452) |
+| Agent follows retrieval policy on Cursor | **`.cursor/rules/retrieval-routing.mdc`** + **`route_codebase_retrieval.py`** | Rules enforce default tool order; `beforeSubmitPrompt` hook is telemetry-only (no plan injection); sessionStart is session-level orientation |
 | Score collected evidence | **retrieval-pack** | `get_context.py --mode retrieval-pack` — does **not** search |
 
 ## Semantic routing (Cursor)
@@ -41,7 +59,7 @@ The planner emits **`platform-semantic`** with backend chosen by **`cursorEnv`**
 - **native:** built-in `@codebase` / agent semantic search — **do not** use fast-context as Primary.
 - **byok:** **fast-context MCP** (`fast_context_search`) — built-in semantic is not in the agent tool list.
 
-Definition / reference jumps: **codegraph** (not GO_TO_DEFINITION; Agent LSP unavailable).
+Definition / reference jumps (Agent): **Prefer Grep → Read** for named symbols; **codegraph** when trap/blast/ambiguity. **Not** raw LSP: `GO_TO_DEFINITION` absent from [Agent tool overview](https://cursor.com/docs/agent/overview.md) (2026-08-05). Semantic / `@codebase` is a separate Prefer path for concepts (embedding index), not LSP. IDE Editor F12 ≠ Agent tool routing.
 
 ## Token economy signals
 
@@ -92,7 +110,7 @@ When `smart-search doctor` is not ok or `run_smart_search.py` status is `not_con
 
 **CLI discovery (Cursor):** `TRELLIS_SMART_SEARCH_COMMAND` / `smart_search.command` → PATH `smart-search` → project `node_modules/.bin/smart-search` (when installed as a dependency). Agent entrypoint is always `./.cstl/scripts/run_smart_search.py`.
 
-**Research flags (smart-search ≥ 0.1.15):** pass through `run_smart_search.py` for `--intent deep-research`:
+**Research flags (smart-search ≥ 0.2.0; flags also on 0.1.15+):** pass through `run_smart_search.py` for `--intent deep-research`:
 
 | Flag | Values | Use |
 | --- | --- | --- |
@@ -108,7 +126,7 @@ Research JSON may include `output_schema_version: 1` and structured `citations`
 
 `route_codebase_retrieval.py` returns **intent + route suggestions** and **`agentInstructions`** (numbered steps with Cursor-native tool names). **codebase-evidence** is **candidate** until confirmed by Read/Git/tests.
 
-On **Cursor**, per-query plans come from **`beforeSubmitPrompt` → `inject-retrieval-plan.py`**; durable execution policy lives in **`.cursor/rules/retrieval-routing.mdc`** (`alwaysApply`). Do **not** rely on `sessionStart` hook injection (#158452) or end-of-turn **retrieval-pack** for plans — retrieval-pack **scores** collected evidence; it does not search.
+On **Cursor**, retrieval policy lives in **`.cursor/rules/retrieval-routing.mdc`** (`alwaysApply`) plus on-demand **`route_codebase_retrieval.py`**. The **`beforeSubmitPrompt`** hook is **telemetry-only** (no plan injection). `sessionStart` delivers session-level orientation (dashboard, workflow summary). Do **not** rely on end-of-turn **retrieval-pack** for plans — retrieval-pack **scores** collected evidence; it does not search.
 
 ### Result-layer ranking (B / E / D — REC-05)
 
@@ -120,7 +138,7 @@ After Grep/codegraph/semantic produce **path candidates**, reorder before choosi
 | `trap-package-disambiguation` | Demote snapshot/registry/`src/agents/` trap paths unless Read confirms the asked layer. |
 | `env-config-literal` | Prefer `scripts/`, `e2e/`, `bench/`, `test/` over generic `src/auth` / `src/paths`. |
 
-- **Agent plans**: `render_agent_instructions` / `inject-retrieval-plan.py` append a **结果层排序** block when these intents appear.
+- **Agent plans**: `render_agent_instructions` / `route_codebase_retrieval.py --instructions` append a **结果层排序** block when these intents appear.
 - **Offline reorder**: `python ./.cstl/scripts/rank_retrieval_candidates.py --candidates fixtures.json --intents caller-chain --top-k 5 --pretty`
 - **Library**: `common/retrieval_result_ranking.py` (Python mirror used by router and rank script).
 

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

@@ -0,0 +1,184 @@
+# Verification Strength Guide
+
+> **Purpose**: Define **how deeply** cstl tasks must be verified before closeout — graded by task risk (Lite / Full / Parent), **not** TDD ceremony.
+
+---
+
+## 1. Non-goals
+
+- **No TDD productization** — cstl does not require red-green-refactor loops, "write tests first" gates, or per-function unit test mandates.
+- **No per-task full-suite burden** — Lite tasks must not be forced through architecture review or whole-repo CI.
+- **No replacement for project test frameworks** — cstl validation checks **task evidence** in `verify.md` and configured quality gates; it does not run or replace your project's test runner.
+
+---
+
+## 2. Two-axis model (verification strength, not TDD)
+
+### Axis A — Task Ladder closeout profile
+
+Inferred by `task.py` from artifact presence and `task.json` meta. Determines **minimum evidence** before archive or child integration.
+
+| Closeout profile | Trigger (existing logic) | Minimum verification depth |
+| --- | --- | --- |
+| **lite** | No `design.md`+`implement.md`; or meta marks lite | PRD AC mapping + focused validation + acceptance + durable-learning decision |
+| **full** | Has `design.md` + `implement.md` | Lite depth + DSC validation + **check evidence** + **reviewed change-set** + configured reviewer gates |
+| **parent** | `task.json.children` non-empty | Each child integrated/cancelled + parent integration evidence + integration-review gate |
+
+**High-risk upgrade (normative):** scope touching framework semantics, cross-file workflow, `verification_profile`, or capabilities should **Lite → Full** per `workflow.md` Task Ladder rules.
+
+### Axis B — `verification_profile` (reviewer gate strictness)
+
+Declared in `implement.md` Development Strategy Contract. Guide narrative: **验证强度** — never "TDD tier".
+
+| Profile | Default enabled gates | Strength meaning |
+| --- | --- | --- |
+| **standard** | requirements-review, code-review | Default Full/Child: planning artifacts + change review + validation/check evidence |
+| **strict** | same as standard (reserved for stricter archive signals) | High-risk Full default this wave |
+| **architecture** | + architecture-review | Cross-layer / contract / template / runtime changes |
+
+Details: `task_gates.py` → `PROFILE_DEFAULT_GATES`.
+
+---
+
+## 3. Minimum validation checklist by closeout profile
+
+### Lite
+
+- [ ] Focused validation on **touched behavior** (command + result in `verify.md`)
+- [ ] `python ./.cstl/scripts/task.py validate <task>`
+- [ ] Final acceptance mapped to PRD AC
+- [ ] Durable-learning decision line (see [Durable Learning Decision Guide](./durable-learning-decision-guide.md))
+
+**Example `verify.md` lines:**
+
+```markdown
+Validation: `python -m py_compile src/foo.py` — exit 0
+Acceptance: prd AC 1–3 satisfied; typo fix verified in editor
+Durable learning decision: no durable learning — one-off content fix
+```
+
+### Full
+
+All Lite items, plus:
+
+- [ ] Validation commands from `implement.md` executed; results recorded
+- [ ] `Check evidence:` or `cstl-check evidence:` — inline skill or agent review completed
+- [ ] `Reviewed change-set:` or `Git diff ref:` — identity of reviewed diff
+- [ ] Required gates recorded via `task.py record-gate` when contract enables them
+
+**Example:**
+
+```markdown
+Validation: probe matrix 4/4 PASS (see research/probe-results.md)
+Check evidence: cstl-check skill — spec compliance + py_compile
+Reviewed change-set: git diff main..HEAD — 8 files in .cstl/spec + scripts
+Acceptance: prd AC 1–5 mapped below
+Durable learning decision: no durable learning
+```
+
+### Parent
+
+All structural children `integrated` or `cancelled`, plus:
+
+- [ ] `Integration evidence:` in parent `verify.md`
+- [ ] `integration-review` gate when parent contract requires it
+
+---
+
+## 4. Choosing `verification_profile`
+
+| Situation | Suggested profile |
+| --- | --- |
+| Single-file / local fix, Lite ladder | N/A (lite closeout; gates minimal) |
+| Full task, normal feature | `standard` |
+| High-risk Full (hooks, gates, templates, runtime) | `strict` or `architecture` |
+| Cross-layer contract / framework semantics | `architecture` |
+
+Set in `implement.md`:
+
+```yaml
+verification_profile: standard
+quality_gates:
+  mode: explicit
+  enabled: [requirements-review, code-review]
+```
+
+---
+
+## 5. `verify.md` signal line format (CLI-aligned)
+
+The CLI uses regex to detect **substantive** evidence. Placeholder values (`TBD`, `N/A`, `待定`, `-`, `...`) are rejected.
+
+| Signal | Example lines (any one match) |
+| --- | --- |
+| Validation | `Validation:`, `Validation commands:`, `Validation results:` |
+| Check evidence | `Check evidence:`, `cstl-check evidence:` |
+| Acceptance | `Acceptance:`, `Final acceptance:`, `Accepted by user:` |
+| Durable learning | `Durable learning decision:`, `no durable learning`, `Spec update evidence:` |
+| Integration | `Integration evidence:`, `Final integration:` |
+| Reviewed change-set | `Reviewed change-set:`, `Git diff ref:`, `Changeset:` |
+
+**Not sufficient alone:**
+
+- `python ./.cstl/scripts/task.py validate` passing JSONL schema — **does not** prove task acceptance
+- Long log dumps without structured signal lines
+- Checkbox ticks in PRD without `verify.md` validation mapping
+
+---
+
+## 6. False-green detection
+
+### Existing CLI guards
+
+| Failure mode | Mechanism |
+| --- | --- |
+| Placeholder validation | `PLACEHOLDER_VALUES_RE` in `task_gates.py` |
+| Missing archive signals | `verify_evidence_status()` at archive / `record-gate` |
+| PRD AC all placeholder | `_prd_requirements_review_errors` at start-execution |
+| Gate PASS without evidence | `record-gate` rejects substantive-missing verify |
+
+### Repeatable probe
+
+Run fixture matrix against shared logic (no second rule set):
+
+```powershell
+python ./.cstl/scripts/verify_evidence_probe.py --fixture <path> --profile lite|full|parent --expect pass|fail
+```
+
+Fixtures: `.cstl/tasks/08-06-cstl-p0-verify-capability/research/verification-probes/`
+
+| Fixture | Intent | lite | full |
+| --- | --- | --- | --- |
+| `shallow-placeholder.md` | Placeholder-only verify | FAIL | FAIL |
+| `lite-sufficient.md` | Minimal valid Lite | PASS | FAIL (missing check + changeset) |
+| `full-sufficient.md` | Valid Full closeout | PASS | PASS |
+| `overkill-noise.md` | Verbose logs, no signals | FAIL | FAIL |
+
+---
+
+## 7. Shallow vs overkill (quick reference)
+
+| Scenario | Too shallow (should block) | Overkill (non-goal) |
+| --- | --- | --- |
+| Lite typo fix | "Looks good" with no `Validation:` line | architecture-review + full-repo test suite |
+| Full hook change | `py_compile` only, no `Reviewed change-set:` | Mandate new unit test per function (TDD) |
+| Parent integrate child | Child verify still placeholder | Full E2E per child |
+
+---
+
+## 8. Integration with cstl-check / record-gate / archive
+
+```text
+Phase 2 Execute → cstl-check (skill/agent) → verify.md evidence
+Phase 3.1 Verify → record-gate (non-baseline) → archive --check
+```
+
+- **cstl-check**: review against spec + task artifacts; fix in-contract defects; write human-readable evidence **before** `record-gate`.
+- **record-gate**: machine state only; requires substantive `verify.md` for PASS/SKIPPED.
+- **archive**: `verify_evidence_status()` must pass for profile; Full also needs gate readiness.
+
+Workflow cross-ref: Phase 3.1 Quality verification in `workflow.md`.
+
+---
+
+**Core principle:** Match verification **strength** to task **risk** — enough to catch false greens, never enough to become TDD theater.

package/dist/templates/shared-hooks/session-start.py

@@ -656,6 +656,16 @@ def _build_compact_current_state(
     if spec_index_paths:
         lines.append(f"Spec indexes: {len(spec_index_paths)} available.")
 
+    try:
+        from common.artifact_locale import artifact_locale_summary  # type: ignore[import-not-found]
+
+        task_dir = None
+        if active.task_path:
+            task_dir = _resolve_task_dir(trellis_dir, active.task_path)
+        lines.append(artifact_locale_summary(repo_root, task_dir))
+    except Exception:
+        pass
+
     return "\n".join(lines)
 
 

package/dist/templates/trellis/config.yaml

@@ -32,6 +32,15 @@ max_journal_lines: 2000
 #
 # session_auto_commit: true
 
+#-------------------------------------------------------------------------------
+# Context injection (opt-in)
+#-------------------------------------------------------------------------------
+
+# Optional get_context enrichment. Default off — JOURNAL FILE stays metadata-only.
+#
+# context_injection:
+#   journal_snippet: false   # opt-in; inject ≤150 token recent journal summary in get_context
+
 #-------------------------------------------------------------------------------
 # Task Lifecycle Hooks
 #-------------------------------------------------------------------------------
@@ -76,6 +85,15 @@ max_journal_lines: 2000
 # Default package used when --package is not specified.
 # default_package: frontend
 
+#-------------------------------------------------------------------------------
+# Human-reviewed artifact locale (zh | en)
+#-------------------------------------------------------------------------------
+
+# Language for prd/design/implement/verify/handoff and task create seeds.
+# Does NOT translate CLI UI or existing archived tasks.
+#
+# artifact_locale: zh
+
 #-------------------------------------------------------------------------------
 # Smart Search CLI (optional per-machine override)
 #-------------------------------------------------------------------------------