@blxzer/pactile 0.5.0 → 0.6.0-beta.2

package/dist/templates/markdown/framework/prd-grill-frontier.md.txt

@@ -1,105 +1,105 @@
-# PRD Grill & Frontier Discipline
-
-> **Purpose**: When the workflow routes to planning / PRD Grill, this is the on-demand path to the grill and Frontier discipline on Cursor. The full interview contract and Thinking Principles live in the bundled `brainstorm` skill (SSOT) — this guide is the Cursor loadable summary, not a second source of truth.
-
-## When to read this
-
-The workflow or AGENTS invocation map says planning / PRD Grill → **`Read ./prd-grill-frontier.md`** (this file) or the full bundled `common/skills/brainstorm.md` when another carrier is available. Read it **before** asking any user questions. Do **not** claim the grill discipline is loaded without a file read.
-
-## Optional brick — not a hard gate
-
-Grill is an **optional brick**（可选积木）, not a hard gate. The model chooses whether to run it; skipping grill is allowed. Do **not** restore a Claude-only `grill-me` forced subagent gate. When grill *is* used, keep the existing integration: document-surface checklist (grill-with-docs spirit), in-session frontier / micro-grill pacing, and Platform checklist row 10 (no independent `grill-me` / `grill-with-docs` subagent gate).
-
-## Front-anchor principle
-
-**Product principle:** high front-end completeness → backend process drift is tolerable（前端完成度高则后端漂移可容忍）. When the front-end grill nails requirements, later backend process drift remains acceptable.
-
-## Non-negotiable evidence rule
-
-If a question can be answered by exploring the codebase, explore the codebase instead — never ask the user to confirm facts the repo can answer. Read root `CONTEXT.md` (if present) before asking and use its glossary terms. Ask only for product intent, preference, scope, risk tolerance, or decisions that remain ambiguous after inspection.
-
-## PRD Grill (Phase B)
-
-Treat `prd.md` (+ existing `design.md` fragments) as the **only document surface**. Run this checklist and fix the PRD in place (no new subagent):
-
-| # | Check |
-| --- | --- |
-| 1 | **Goal & user value** — single clear statement |
-| 2 | **Confirmed facts vs assumptions** — repo facts not listed as assumptions |
-| 3 | **Testable acceptance criteria** |
-| 4 | **Out of scope** explicit |
-| 5 | **Dependencies & sequencing** |
-| 6 | **Parent/Child & deliverables** when applicable |
-| 7 | **Research & external facts** — smart-search or documented fallback |
-| 8 | **Execution gate & artifacts** — `design.md` / `implement.md` / `verify.md` expectations |
-| 9 | **Durable Learning** — Phase 3.3 will need `update-spec` \| `no-update` \| `unsure` |
-| 10 | **Platform** — Cursor-first; PRD Grill in-session (no legacy grill-me / grill-with-docs subagent gate) |
-| 11 | **Risk & rollback** for complex tasks |
-| 12 | **Open questions** — only **blocking** strategic/preference items remain |
-| 13 | **Root vs inherited assumptions** — every requirement traces to a user-facing root need; inherited assumptions flagged or removed (First Principles) |
-| 14 | **Minimal sufficient design** — simplest design that meets acceptance wins (Occam's Razor) |
-
-## Micro-grill unresolved
-
-For each **blocking** open question after the checklist, embed the `pactile-micro-grill` contract:
-
-- exactly **one** question per message
-- user-facing text in the project's human-review language (default Simplified Chinese)
-- recommended answer + trade-off
-- **update `prd.md` after every answer** before the next question
-
-Stop micro-grill when no blocking open questions remain. Do not ask process questions ("should I search?"); do not re-ask facts Discovery already confirmed.
-
-## Frontier rounds (question pacing)
-
-- **frontier** = all "prerequisite-decided" questions: their prerequisite decisions are resolved, so they can be asked now without guessing unheard answers.
-- Each round lists the current frontier at once, each question numbered (❓Q1/Q2/Q3…) with a recommended answer.
-- **≤3 questions per round**; split into more rounds beyond that to avoid information overload.
-- **Facts are the agent's job**: when a frontier question needs environment facts, dispatch a sub-agent to check; while exploration is pending it counts as an unresolved prerequisite that only blocks its downstream questions — ask the rest of the frontier anyway.
-- **Decisions are the user's job**: every decision waits for the user's answer; do not answer for them.
-- A user answer reshapes the design tree and the frontier extrapolates into the next round; **an empty frontier = the design tree is exhausted** — summarize the consensus and confirm before treating planning as done.
-
-> **Override note**: this pacing overrides the "Ask the questions one at a time" line in the Non-Negotiable Interview Contract — Phase B (PRD Grill) follows frontier rounds; `pactile-micro-grill` still defaults to one question at a time.
-
-## Question rules
-
-Each question must include: the decision needed, why it matters, your recommended answer, and the trade-off if the user chooses differently. Default recommendation = Occam's Razor: the **minimal sufficient** option that still satisfies the acceptance criteria. Only recommend a more complex option when you can cite evidence (a contract, a verified edge case, a repo constraint).
-
-## Artifact rules (summary)
-
-- `prd.md` records requirements + acceptance (goal, confirmed facts, requirements, acceptance criteria, out of scope, blocking open questions).
-- `design.md` records technical design for complex tasks (architecture, data flow, contracts, trade-offs, rollback).
-- `implement.md` records execution planning (ordered checklist, validation commands, Development Strategy Contract via `task.py suggest-execution-strategy`).
-- Complex tasks need all three before `start-execution --check`; lightweight tasks may be PRD-only.
-
-## Stop — AC ambiguity face = 0
-
-Do **not** measure grill completeness by question count（不能用提问次数度量）. No question-count KPI.
-
-Two stop conditions (D1c); both are model judgments, not machine counters:
-
-1. **需求侧** — every AC is in testable / acceptable wording and traces to a user-facing root need. Further questions that would not change any AC = 过度 grill — stop.
-2. **前锚有效性代理** — each AC's **歧义面 = 0** (AC ambiguity face = 0). Two mutually conflicting implementations must not both count as satisfying that AC.
-
-When these hold, stop grilling even if more questions could be asked.
-
-## Completion — PRD Grill done
-
-If grill was used, it is done when the **Stop — AC ambiguity face = 0** rule holds and **all** of the following hold. Grill remains an optional brick, not an execution hard gate.
-
-Planning is ready for the execution gate when **all** hold:
-
-- PRD Grill checklist satisfied or explicitly N/A with rationale in `prd.md`
-- **No blocking** open questions in `prd.md`
-- Acceptance criteria testable; out of scope explicit
-- If grill ran: stop rule met (**AC 歧义面 = 0**); not measured by question count
-- Complex tasks: `design.md` and `implement.md` present
-- User reviewed artifacts or explicitly approved proceeding
-
-Then proceed to Research (if needed), `task.py start-execution <task> --check`, and implementation **only after** explicit user execution approval. Do not start implementation until the user approves or asks for implementation.
-
-## Related
-
-- Full SSOT: bundled `brainstorm` skill (`common/skills/brainstorm.md`) — interview contract, First Principles, Occam's Razor.
-- Reachability: [internal-skills-cursor-reachability.md](./internal-skills-cursor-reachability.md).
-- Workflow routing: `.pactile/workflow.md` Phase 1 (Plan) and Active Task Routing.
+# PRD Grill & Frontier Discipline
+
+> **Purpose**: When the workflow routes to planning / PRD Grill, this is the on-demand path to the grill and Frontier discipline. The full interview contract and Thinking Principles live in the bundled `brainstorm` skill (SSOT); this guide is a summary, not a second source of truth.
+
+## When to read this
+
+The workflow or AGENTS invocation map says planning / PRD Grill → **`Read ./prd-grill-frontier.md`** (this file) or the full bundled `common/skills/brainstorm.md` when another carrier is available. Read it **before** asking any user questions. Do **not** claim the grill discipline is loaded without a file read.
+
+## Optional brick — not a hard gate
+
+Grill is an **optional brick**（可选积木）, not a hard gate. The model chooses whether to run it; skipping grill is allowed. Do **not** restore a Claude-only `grill-me` forced subagent gate. When grill *is* used, keep the existing integration: document-surface checklist (grill-with-docs spirit), in-session frontier / micro-grill pacing, and Platform checklist row 10 (no independent `grill-me` / `grill-with-docs` subagent gate).
+
+## Front-anchor principle
+
+**Product principle:** high front-end completeness → backend process drift is tolerable（前端完成度高则后端漂移可容忍）. When the front-end grill nails requirements, later backend process drift remains acceptable.
+
+## Non-negotiable evidence rule
+
+If a question can be answered by exploring the codebase, explore the codebase instead — never ask the user to confirm facts the repo can answer. Read root `CONTEXT.md` (if present) before asking and use its glossary terms. Ask only for product intent, preference, scope, risk tolerance, or decisions that remain ambiguous after inspection.
+
+## PRD Grill (Phase B)
+
+Treat `prd.md` (+ existing `design.md` fragments) as the **only document surface**. Run this checklist and fix the PRD in place (no new subagent):
+
+| # | Check |
+| --- | --- |
+| 1 | **Goal & user value** — single clear statement |
+| 2 | **Confirmed facts vs assumptions** — repo facts not listed as assumptions |
+| 3 | **Testable acceptance criteria** |
+| 4 | **Out of scope** explicit |
+| 5 | **Dependencies & sequencing** |
+| 6 | **Parent/Child & deliverables** when applicable |
+| 7 | **Research & external facts** — smart-search or documented fallback |
+| 8 | **Execution gate & artifacts** — `design.md` / `implement.md` / `verify.md` expectations |
+| 9 | **Durable Learning** — Phase 3.3 will need `update-spec` \| `no-update` \| `unsure` |
+| 10 | **Platform** — Codex project entry; PRD Grill stays in the current task |
+| 11 | **Risk & rollback** for complex tasks |
+| 12 | **Open questions** — only **blocking** strategic/preference items remain |
+| 13 | **Root vs inherited assumptions** — every requirement traces to a user-facing root need; inherited assumptions flagged or removed (First Principles) |
+| 14 | **Minimal sufficient design** — simplest design that meets acceptance wins (Occam's Razor) |
+
+## Micro-grill unresolved
+
+For each **blocking** open question after the checklist, embed the `pactile-micro-grill` contract:
+
+- exactly **one** question per message
+- user-facing text in the project's human-review language (default Simplified Chinese)
+- recommended answer + trade-off
+- **update `prd.md` after every answer** before the next question
+
+Stop micro-grill when no blocking open questions remain. Do not ask process questions ("should I search?"); do not re-ask facts Discovery already confirmed.
+
+## Frontier rounds (question pacing)
+
+- **frontier** = all "prerequisite-decided" questions: their prerequisite decisions are resolved, so they can be asked now without guessing unheard answers.
+- Each round lists the current frontier at once, each question numbered (❓Q1/Q2/Q3…) with a recommended answer.
+- **≤3 questions per round**; split into more rounds beyond that to avoid information overload.
+- **Facts are the agent's job**: when a frontier question needs environment facts, dispatch a sub-agent to check; while exploration is pending it counts as an unresolved prerequisite that only blocks its downstream questions — ask the rest of the frontier anyway.
+- **Decisions are the user's job**: every decision waits for the user's answer; do not answer for them.
+- A user answer reshapes the design tree and the frontier extrapolates into the next round; **an empty frontier = the design tree is exhausted** — summarize the consensus and confirm before treating planning as done.
+
+> **Override note**: this pacing overrides the "Ask the questions one at a time" line in the Non-Negotiable Interview Contract — Phase B (PRD Grill) follows frontier rounds; `pactile-micro-grill` still defaults to one question at a time.
+
+## Question rules
+
+Each question must include: the decision needed, why it matters, your recommended answer, and the trade-off if the user chooses differently. Default recommendation = Occam's Razor: the **minimal sufficient** option that still satisfies the acceptance criteria. Only recommend a more complex option when you can cite evidence (a contract, a verified edge case, a repo constraint).
+
+## Artifact rules (summary)
+
+- `prd.md` records requirements + acceptance (goal, confirmed facts, requirements, acceptance criteria, out of scope, blocking open questions).
+- `design.md` records technical design for complex tasks (architecture, data flow, contracts, trade-offs, rollback).
+- `implement.md` records execution planning (ordered checklist, validation commands, and Development Strategy Contract).
+- Complex tasks need all three before `start-execution --check`; lightweight tasks may be PRD-only.
+
+## Stop — AC ambiguity face = 0
+
+Do **not** measure grill completeness by question count（不能用提问次数度量）. No question-count KPI.
+
+Two stop conditions (D1c); both are model judgments, not machine counters:
+
+1. **需求侧** — every AC is in testable / acceptable wording and traces to a user-facing root need. Further questions that would not change any AC = 过度 grill — stop.
+2. **前锚有效性代理** — each AC's **歧义面 = 0** (AC ambiguity face = 0). Two mutually conflicting implementations must not both count as satisfying that AC.
+
+When these hold, stop grilling even if more questions could be asked.
+
+## Completion — PRD Grill done
+
+If grill was used, it is done when the **Stop — AC ambiguity face = 0** rule holds and **all** of the following hold. Grill remains an optional brick, not an execution hard gate.
+
+Planning is ready for the execution gate when **all** hold:
+
+- PRD Grill checklist satisfied or explicitly N/A with rationale in `prd.md`
+- **No blocking** open questions in `prd.md`
+- Acceptance criteria testable; out of scope explicit
+- If grill ran: stop rule met (**AC 歧义面 = 0**); not measured by question count
+- Complex tasks: `design.md` and `implement.md` present
+- User reviewed artifacts or explicitly approved proceeding
+
+Then proceed to Research (if needed), `pactile task start-execution <task> --check`, and implementation **only after** explicit user execution approval. Do not start implementation until the user approves or asks for implementation.
+
+## Related
+
+- Full SSOT: bundled `brainstorm` skill (`common/skills/brainstorm.md`) — interview contract, First Principles, Occam's Razor.
+- Reachability: inspect the installed `.agents/skills/` entry and current capability readiness.
+- Workflow routing: `.pactile/workflow.md` Phase 1 (Plan) and Active Task Routing.

package/dist/templates/markdown/framework/release-boundary.md.txt

@@ -1,30 +1,30 @@
-# 发布边界：PACTILE 与 pactile-byok
-
-PACTILE（pactile）本批带走**中间件协议**与**并行原则**，外加半页用户升级说明。**pactile-byok** 是另一条产品线、另一个仓库、另一次发布。两者可并行准备，互不门禁。
-
-## PACTILE 本批带走
-
-- Middleware Protocol v1（义务 + Manifest 样例 + `update` 不顶掉）。Overlay 路径写死为 `.pactile/middleware/`。
-- 并行第一原则（workflow / 池 / 规划模板）。强度是约定 + 审核指出，不是新 CLI gate。
-- 升级合同给终端用户看的半页：升包 → `pactile update` → 确认 → 接着干活。官方面可随 `update` 开迁；产物先双读；Contract 另批。
-- 池注意力刻度（`priority`）与可并行组说明。注意力排序不是串行锁。
-
-文档/约定即可。本批不强制写完安装器，不实现产物迁移器。
-
-## PACTILE 本批不带走
-
-- pactile-byok 建仓、分析、合成、npm/改名、Cursor patch 安装器。
-- 任何 BYOK 实现或可选安装器。全库 BYOK 盘点仍搁置。
-- 已退役的替代客户端入口不回默认安装面。
-
-未就绪的 BYOK **不是** PACTILE 发版硬依赖。成功标准看 PACTILE 自己的工作流轴，不用「BYOK 是否合成」当门禁。
-
-## 用户说明边界
-
-用户升级说明见 [upgrade.md](./upgrade.md)。那一页不写内部迁移地图，也不写维护者本机步骤。
-
-## 相关
-
-- [middleware-protocol.md](./middleware-protocol.md)
-- [upgrade.md](./upgrade.md)
-- [parallel-first-execution.md](./parallel-first-execution.md)
+# 发布边界：PACTILE 与 pactile-byok
+
+PACTILE（pactile）本批带走**中间件协议**与**并行原则**，外加半页用户升级说明。**pactile-byok** 是另一条产品线、另一个仓库、另一次发布。两者可并行准备，互不门禁。
+
+## PACTILE 本批带走
+
+- Middleware Protocol v1（义务 + Manifest 样例 + `update` 不顶掉）。Overlay 路径写死为 `.pactile/middleware/`。
+- 并行第一原则（workflow / 池 / 规划模板）。强度是约定 + 审核指出，不是新 CLI gate。
+- 升级合同给终端用户看的半页：升包 → `pactile update` → 确认 → 接着干活。官方面可随 `update` 开迁；产物先双读；Contract 另批。
+- 池注意力刻度（`priority`）与可并行组说明。注意力排序不是串行锁。
+
+文档/约定即可。本批不强制写完安装器，不实现产物迁移器。
+
+## PACTILE 本批不带走
+
+- pactile-byok 建仓、分析、合成、npm/改名、Cursor patch 安装器。
+- 任何 BYOK 实现或可选安装器。全库 BYOK 盘点仍搁置。
+- 已退役的替代客户端入口不回默认安装面。
+
+未就绪的 BYOK **不是** PACTILE 发版硬依赖。成功标准看 PACTILE 自己的工作流轴，不用「BYOK 是否合成」当门禁。
+
+## 用户说明边界
+
+用户升级说明见 [upgrade.md](./upgrade.md)。那一页不写内部迁移地图，也不写维护者本机步骤。
+
+## 相关
+
+- [middleware-protocol.md](./middleware-protocol.md)
+- [upgrade.md](./upgrade.md)
+- [parallel-first-execution.md](./parallel-first-execution.md)

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

@@ -1,199 +1,9 @@
-# Retrieval daily guide (Cursor-first)
-
-> **Purpose:** Choose the right tool; do not confuse **search** with **retrieval-pack scoring**.
-
-## Three-layer ABI (frozen)
-
-Subsequent retrieval optimization may change ranking features, pack schema, or Optional Providers. It must **not** merge these layers back into `workflow.md` or SessionStart.
-
-| Layer | Owner | Recognizes | Does not |
-| --- | --- | --- | --- |
-| Intent | `context-progressive` | `exact` / `semantic` / `structural` / `external` | tool names, scores, pack, per-turn plan injection |
-| Provider | Middleware | capability ready/degrade; default `external-knowledge` → smart-search | Kernel release lockstep; platform Web as equivalent |
-| Quality | `retrieval-extended` | score/pack **collected-evidence** (path + provider + optional freshness) | searching; standing in as Close / AC Evidence |
-
-`inject-retrieval-plan.py` is **telemetry-only**. Cursor `additional_context` often never reaches the model — a local log is not Prompt injection success. `research-end-retrieval-pack.py` no-ops (exit 0) when there are no research artifacts. `build_retrieval_pack.py` input role is `collected-evidence`; missing collection is empty + reason, never AC Evidence.
-
-## Web research rule (smart-search is mandatory first)
-
-For **external / current / web facts**, **smart-search** (`run_smart_search.py`) is the **mandatory first choice**. Platform built-in web tools (Cursor `WebSearch` / `WebFetch`) are **downgrade-only**: use them solely when smart-search is unavailable (`doctor` not ok, `not_configured` / `failed`, or timeout). Never reach for built-in web search while smart-search is healthy. This rule overrides any general "use available tools" instinct — web retrieval strength is routed inside Pactile, not left to the platform default.
-
-## External-knowledge gate (search-or-not)
-
-Ask: *If this answer were wrong because the world or a third-party API moved, would that matter?*
-
-| Decision | Action |
-| --- | --- |
-| **YES** (freshness / third-party surface) | Run `run_smart_search.py` — prefer `docs` / `official-source` / `broad-search` when cheap; use `deep-research` when multi-source or claim-risk is high |
-| **NO** (truth lives in this workspace) | Use rg / codegraph / `.pactile/spec` / task artifacts only — do **not** default to web |
-| **Ambiguous** | Prefer a **cheap** external probe over guessing; do not skip solely to save a call |
-
-**YES examples:** library/SDK current API or version; changelog / release notes; CVE / GitHub issue status; pricing / product status; live URLs; industry practice when designing policy.  
-**NO examples:** symbol location / call chains; in-repo Pactile contracts; behavior of the code you are editing; pure rename/lint inside known files.
-After search: persist under `{TASK}/research/` with a **provider label**; treat hits as candidates until corroborated (repo, test, or second source).
-
-## Primary source preference
-
-Prefer **primary sources** — official docs, source code, first-party API references, release notes, standards text. Mark blog posts, aggregators, and unverified second-hand summaries as **secondary** until corroborated against a primary source or the repo. This layers on top of "hits as candidates until corroborated": it ranks *which* candidates to trust first, and does not change the smart-search mandatory-first rule above.
-
-## Prefer / Adapt / Own (code intelligence)
-
-| Need | **Prefer** (Cursor native) | **Adapt** | **Own** (codegraph / MCP) |
-| --- | --- | --- | --- |
-| 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 |
-| 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** (BYOK env) | 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) |
-| Pactile 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 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)
-
-The planner emits **`platform-semantic`** only when current Adapter facts resolve an authorized and ready host capability:
-
-- **host native:** built-in `@codebase` / agent semantic search — **do not** use fast-context as Primary.
-- **declared Middleware Provider:** use the resolver-selected Provider only after manifest, authorization, and readiness checks pass.
-
-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
-
-Each route in the router output includes a `tokenEconomy` label:
-
-| Label | Meaning | Typical tools |
-| --- | --- | --- |
-| `high` | Low token cost per correct answer (~80-200 tokens) | codegraph callers/search, platform-semantic |
-| `medium` | Moderate token cost (~200-700 tokens) | codegraph explore, smart rg, fast-context |
-| `low` | High token cost per answer (~3000+ tokens) | naive rg (unconstrained output) |
-
-When `projectFileCount > 2000`, the router promotes structural (codegraph) routes ahead of rg routes for better token efficiency on large codebases.
-
-**Project file count default:** `route_codebase_retrieval.py` and `get_context.py --mode retrieval-pack` default `--project-file-count` to **`auto`** — they count files under the repo root (`git ls-files` when `.git` exists, else a bounded walk). Override with an integer (e.g. `5000`) for large non-git trees or eval fixtures.
-
-## Commands
-
-```powershell
-python ./.pactile/scripts/search_artifacts.py --query "<topic>" --json
-python ./.pactile/scripts/search_memory.py --query "<topic>" --json
-python ./.pactile/scripts/run_smart_search.py "<question>" --intent deep-research --json
-python ./.pactile/scripts/route_codebase_retrieval.py "<question>" --json
-python ./.pactile/scripts/route_codebase_retrieval.py "<question>" --instructions
-python ./.pactile/scripts/get_context.py --mode retrieval-pack --json --input evidence.json
-python ./.pactile/scripts/codegraph_session_smoke.py --json
-```
-
-## Codegraph session readiness (eval / dogfood)
-
-Before a **cold benchmark** or structural-heavy run:
-
-1. **MCP**: In Cursor project MCP settings, enable the **codegraph** server for the workspace (or eval checkout).
-2. **Index on disk**: Run `python ./.pactile/scripts/codegraph_session_smoke.py` (exit 0 = at least one `.codegraph/` under workspace root or a top-level subproject). Use `--root <eval-checkout>` when the agent root is not the harness.
-3. **Live MCP smoke** (manual): one `codegraph_search` with a known symbol in that repo; stale-index banner → re-read affected files.
-
-Paste into the **run report header** (markdown):
-
-| Field | Example |
-| --- | --- |
-| `codegraph_mcp` | `configured` / `off` / `unknown` |
-| `codegraph_index_path` | from smoke JSON `codegraph_index_paths[0]` |
-| `codegraph_smoke_at` | ISO8601 UTC |
-| `codegraph_smoke_ok` | `true` / `false` |
-
-## smart-search fallback
-
-When `smart-search doctor` is not ok or `run_smart_search.py` status is `not_configured` / `failed` (including **search timeout**), use **Cursor WebSearch/WebFetch**, then persist to `{TASK}/research/` with `source: cursor-web-fallback` in frontmatter. See `smart-search-cli` skill §4b.
-
-**CLI discovery (Cursor):** `PACTILE_SMART_SEARCH_COMMAND` / `smart_search.command` → PATH `smart-search` → project `node_modules/.bin/smart-search` (when installed as a dependency). Agent entrypoint is always `./.pactile/scripts/run_smart_search.py`.
-
-**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 |
-| --- | --- | --- |
-| `--locale-scope` | `cn`, `en`, `both` (CLI default) | Skip bilingual discovery when cost matters |
-| `--dry-run` | flag | Plan + routing preview only; no live providers |
-| `--progress` | flag | `[research]` stage logs to stderr |
-
-Research JSON may include `output_schema_version: 1` and structured `citations` (`id`, `source_type`, `verified`, `content_len`). Pactile manifests preserve those fields when present.
-
-**Cursor skill surface:** `smart-search-cli` is an internal workflow name — it is **not** installed under `.cursor/skills/` (commands-only policy). On Cursor, follow this guide + `run_smart_search.py`; bundled skill assets ship for Codex/Gemini via `.agents/skills/` only.
-
-## Router vs execution
-
-`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**, 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)
-
-After Grep/codegraph/semantic produce **path candidates**, reorder before choosing Top-1 / Top-5:
-
-| Intent | Rule |
-| --- | --- |
-| `caller-chain` | Expanded pool first; boost concrete call sites; demote facade/barrel/runtime/registry **assembly-only** files. |
-| `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` / `route_codebase_retrieval.py --instructions` append a **结果层排序** block when these intents appear.
-- **Offline reorder**: `python ./.pactile/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).
-
-Do **not** claim aggregate openclaw score gains from ranking alone without fresh telemetry (`candidate_pool_recall` vs final Top-K).
-
-### Structural-first routing (v2)
-
-For structural intents (caller-chain, trap-package-disambiguation, extension-shared-symbol), the router now suggests **codegraph before rg**. This reflects codegraph's superior token economy for structural queries (~80-150 tokens/answer vs rg's ~3557 for naive grep). The agent should still use rg to fill gaps codegraph misses (dynamic dispatch, string-based callsites).
-
-### Semantic routing on Cursor (plans)
-
-Envelopes include **`cursorEnv`**. `platform-semantic` uses **`platformNative: true`** on native and **`semanticBackend: fast-context-mcp`** on BYOK. Native: `@codebase` / built-in search; BYOK: `fast_context_search`.
-
-### Semantic dual metrics (openclaw / eval)
-
-| Metric | Meaning |
-| --- | --- |
-| `semantic_plan_rate` | Share of queries whose routing envelope lists a semantic route |
-| `semantic_exec_rate` | Share of queries with ≥1 semantic search tool call |
-
-On **Cursor**, `semantic_exec_rate` uses `classify_tool_calls(..., platform=cursor, cursor_env=...)`: **native** counts built-in semantic only; **byok** counts `fast_context_search` as semantic exec. `cursor_fast_context_misuse` applies only when **native** (or non-byok) uses fast-context while the plan has `platform-semantic`. See `cursor-semantic-compliance.md`.
-
-Plan-level presence does not imply execution-level use (see parent research `06-19` OQ-1 双轨).
-
-### Execution telemetry (schema v2)
-
-When recording eval or audit runs, store **one JSON object per query** in JSONL (`schema_version: 2`). Split scores:
-
-| Field | Owner | Meaning |
-| --- | --- | --- |
-| `answer_score` | Human rubric | Top-1 / Recall@5 / answer quality (0–6 per query in main-50) |
-| `compliance_score` | Derived | Plan vs exec layer compliance (0–1); structural/codegraph, semantic, read verify |
-
-Key exec fields (fill from session tool log): `tools_called`, `grep_count`, `read_count`, `codegraph_executed`, `semantic_executed`, `router_cli_invoked`, `plan_block_in_prompt`, `read_verification_done`. Classify tool names with `common/retrieval_tool_classification.py` (see `cursor-semantic-compliance.md`).
-
-## retrieval-pack
-
-Default `get_context.py --json` returns **retrievalGuide** only. Run `--mode retrieval-pack` after you have collected evidence JSON / smart-search manifests under `{TASK}/research/smart-search/`.
-
-## Adapters (optimization #9)
-
-Core: rg, task-artifacts, artifact-search, source-git-tests. Enhance: codegraph (structural-first), platform-semantic (Cursor `@codebase`), smart-search, session-memory. Placeholders: mcp/browser/network envelope only.
+# Retrieval and evidence
+
+Use `rg` for known text and symbols, then read the relevant source. Use a structural or semantic provider only when the task calls for it and the provider readiness probe succeeds. Record file paths, source versions, and observed results in the task's research or verification artifacts.
+
+For current external facts, run Smart Search when configured. If it is unavailable, record the fallback source and its limitations. A search result is a lead until the underlying file, page, or test confirms it.
+
+A retrieval plan describes the next search and its expected evidence. A retrieval pack scores already collected evidence; it does not perform a search. Never turn a provider's presence into a verified claim without a fresh probe and observable result.
+
+Cursor-specific routing, hooks, and semantic counters from older installations are historical compatibility data. They are not part of the active Codex projection.

package/dist/templates/markdown/framework/upgrade.md.txt

@@ -1,15 +1,15 @@
-# 升级 PACTILE
-
-给已经在用旧版 PACTILE 的仓库。不要重做 `init`，不要手搬任务目录。
-
-1. 按发布说明升级 PACTILE 包（或你原来的安装面）。
-2. 在项目根目录跑一次 **`pactile update`**。
-3. 看摘要：刷新了哪些官方文件、迁了哪些官方规则、哪些进行中的任务仍按旧形状可读、有没有 degraded。
-4. **确认一次。** 拒绝则项目保持原状，不会半写。`--force` / `--skip-all` / `--create-new` 会套官方文件，但不算这次确认，也不写停读旗标。
-5. 照常开对话或 `/pactile-continue`。进行中的任务还能做、还能收工。
-
-官方面（PACTILE 装进项目的指令与规则）能随这次 `update` 开迁。任务产物先双读，以后再写。确认后才会停读旧形状。从更老的版本一次升上来，也走同一条 `update`。
-
-你改过的官方文件会单独列出并保留。项目里的 **`.pactile/middleware/`** 是中间件 overlay：`pactile init` / `pactile update` **永不写入、不删除、不纳入 hash**。`init` / `update` 会把模块短契约装进 **`.pactile/modules/`**（仅 `index.json` 与各模块 `contract.md`，不含 `catalog.ts`）。默认只把 **smart-search** 标为 required；其余 shipped Provider 为 optional，`init` 不强制安装 MCP。只在 Cursor 里配了 MCP、没写成中间件的，PACTILE 不管。失败则回滚或维持双读，项目仍可用。
-
-团队其他人：拉代码即可。若这次只改了本地未提交文件，发布说明会写清谁跑 `update`、谁只要 pull。
+# 升级 PACTILE
+
+给已经在用旧版 PACTILE 的仓库。不要重做 `init`，不要手搬任务目录。
+
+1. 按发布说明升级 PACTILE 包（或你原来的安装面）。
+2. 在项目根目录跑一次 **`pactile update`**。
+3. 看摘要：刷新了哪些官方文件、迁了哪些官方规则、哪些进行中的任务仍按旧形状可读、有没有 degraded。
+4. **确认一次。** 拒绝则项目保持原状，不会半写。`--force` / `--skip-all` / `--create-new` 会套官方文件，但不算这次确认，也不写停读旗标。
+5. 照常开对话或 `/pactile-continue`。进行中的任务还能做、还能收工。
+
+官方面（PACTILE 装进项目的指令与规则）能随这次 `update` 开迁。任务产物先双读，以后再写。确认后才会停读旧形状。从更老的版本一次升上来，也走同一条 `update`。
+
+你改过的官方文件会单独列出并保留。项目里的 **`.pactile/middleware/`** 是中间件 overlay：`pactile init` / `pactile update` **永不写入、不删除、不纳入 hash**。`init` / `update` 会把模块短契约装进 **`.pactile/modules/`**（仅 `index.json` 与各模块 `contract.md`，不含 `catalog.ts`）。默认只把 **smart-search** 标为 required；其余 shipped Provider 为 optional，`init` 不强制安装 MCP。宿主私有 MCP 配置若没有声明为中间件，不进入 Pactile 健康表。失败则回滚或维持双读，项目仍可用。
+
+团队其他人：拉代码即可。若这次只改了本地未提交文件，发布说明会写清谁跑 `update`、谁只要 pull。