@blxzer/pactile 0.5.0

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

@@ -0,0 +1,239 @@
+# Cursor native modes — bind when native, degrade in one sentence
+
+> **Purpose**: This file is the **Cursor Adapter**. Kernel, Baseline module contracts, and host-agnostic CLI name **slots and capabilities** only. Cursor-specific nouns, probes, and UI drive live **here**. Prefer native; when a surface fails, say **one sentence** (what happened, where it landed) and keep going. Do **not** reimplement modes. Do **not** publish a “this version doesn’t support …” catalog.
+>
+> **Human lifecycle** (Kernel projection): Open → Define → Approve → Execute → Verify → Integrate? → Close. PACTILE shows up at those three gates and in `prd.md` / `verify.md`. Everywhere else the user should feel they are using Cursor.
+>
+> **Not a Pactile Task**: official `/goal` / `CreateGoal`. Do **not** restore `pactile-goal`.
+
+---
+
+## Core vs Adapter (zero host coupling)
+
+| Layer | Owns | Must not |
+| --- | --- | --- |
+| **Core** (Kernel / Baseline contracts / host-agnostic CLI) | Slots: Define, Execute, Evidence, typed worker, isolation, `exact` / `semantic` / `structural` / `external` | `SwitchMode`, `CreateGoal`, Multitask, Canvas, Bugbot, Cursor browser, `.cursor/` as SSOT, Build-probe events |
+| **This Adapter** | Evaluate each named Cursor surface; bind or write the one-sentence degrade; visible parallel | Fake a native surface; write those names into Kernel extras / Event Bridge / module contracts |
+
+Host bindings (typed Task names, Multitask, Plan, Goal) belong **only** in this guide. Do not write them back into `worker-orchestration` or Kernel schema.
+
+This guide is **on-demand**. It is not the always-on Bootstrap (`.cursor/rules/pactile-bootstrap.mdc`).
+
+---
+
+## Experience (Q11–Q14) — function first, invisible unless needed
+
+- **Q11.** The user is using Cursor. PACTILE is visible at Open / Execute / Finalize and on `prd.md` / `verify.md`. One **next native action** is allowed. Do **not** ask the user to type `python` or run CLI — the Agent is the hand.
+- **Q12.** Host surface failed → **one sentence**: what happened, and where work already landed. No catalog. No blaming the host.
+- **Q13 / Q16.** If a **visible** host parallel surface can open (Multitask / Build in Parallel), open it. There is **no** stable API to open that UI. Ask the user to open it and hand each worker pack. If they do not, `Task()` plus one Q12 sentence. **Do not block.** Same-session silent `Task()` is a degrade and must say so.
+- **Q14.** If function is unaffected, do not announce the framework. Must show: the three gates, a Q12 degrade, and (when a task is selected) one next action. **No** opening “loaded” probe. No task → answer directly.
+
+---
+
+## Q5 slot map (named surfaces → Adapt / Enhance / Supplement)
+
+| PACTILE slot or need | Cursor native | Adapt | Enhance | Supplement |
+| --- | --- | --- | --- | --- |
+| Task identity / lifecycle / gates / evidence | none | — | — | Kernel (minimum set) |
+| Pool / Profile / principles | none | — | — | `.pactile/pool` and related |
+| Define / AC | Plan | Full **must** try the host design surface once | Draft is not definition until it lands in `{TASK}/prd.md` | Fail → Agent writes artifacts + Q12 |
+| Approve | chat confirm | Do not invent a confirm UI | — | `start-execution --approved` |
+| Execute | Agent | Default; leave design surface for Agent | Stay inside the contract; isolatable units fan out | — |
+| Parallel / isolation | Multitask / `Task` / worktree | Visible surface first (Q13) | Worker pack; `serial_reason`; Parent `integrate-child` | No surface → inline + Q12 |
+| Verify | Debug | Use when runtime evidence is needed | Evidence → `verify.md` | — |
+| Extra review | Bugbot / Security Review | Call when callable | Appendix signal only | Contract Check (P06) is not replaced |
+| Verify visible Web UI | Browser | Use when a visible UI changed | Evidence → `verify.md` | Kernel does not name a browser |
+| In-window durable objective | `/goal` | Q4=A | `UpdateGoal`; ≠ Close Task | Do not restore `pactile-goal` |
+| Analysis / inventory deliverable | Canvas | Use for that class of deliverable | Does not replace task-artifact SSOT | No Kernel canvas slot |
+| Recurring / loop | Automations / Loop | **Unbound** | — | No new lifecycle slot |
+| Read-only Q&A | Ask | If the user is already on Ask, stay read-only | Agent **cannot** `SwitchMode` → Ask | No-task read-only |
+| Continue | chat history (weak) | Do not rebuild chat | — | `/pactile-continue` |
+| Handoff | no stable equivalent | — | — | `/pactile-handoff` |
+| Codebase retrieval | native semantic / search | Four intents prefer native | Do not bind tool names in Bootstrap | Intent router; Optional codegraph |
+| External knowledge | platform Web | Downgrade only | — | smart-search |
+| Hook / session pack | hooks | Event Bridge | Compile Session Pack | Kernel extras (events, not Build) |
+| User entry | `/`, official Skills | Three-piece escape hatch | Internal skills reachable, not in the `/` menu | — |
+| Check worker | typed Check worker | Dispatch when the enum exists | Dual-axis; honest self-review | No independent worker → main-session second pass |
+| Statusline / Share / SDK / other | product surfaces | **Unbound** | Do not grow Kernel | Write “no slot” |
+
+Unnamed native surfaces default to **unbound**. Binding sentences stay in this guide.
+
+---
+
+## Human phases ↔ Cursor modes
+
+| Human phase | Cursor binding | One-sentence fallback (Q12) |
+| --- | --- | --- |
+| **Open** | Stay in Agent (or Ask if the user is already there and the ask is read-only) | “No task yet — answered in chat.” No product writes |
+| **Define** | **Plan** — Full: `SwitchMode(plan)` immediately (Q15) | “Plan switch failed; definition is in `{TASK}/prd.md`.” |
+| **Approve** | Agent — request the Execute gate; `--check` is not approval | Same artifacts; do not start Execute |
+| **Execute** | **Agent** — `SwitchMode(agent)` when returning from Plan. Isolatable units: ask the user to open Multitask and hand worker packs; else `Task()` + Q12 (do not block) | Diff under the approved contract |
+| **Verify** | **Debug** when runtime evidence is needed; else Agent | Proof always lands in `verify.md` |
+| **Integrate?** | Serial Parent `integrate-child` (`merge_limit: 1`) | One-at-a-time merge; `parent_id` alone is not Parent |
+| **Close** | Agent + `UpdateGoal` complete or cancel (Q22) | `verify.md` coverage + `/pactile-finish-work`. Goal failure does not block Close |
+
+`Integrate?` is visible only when topology needs it (parent-child, or the task is already in Integrate). Lite single tasks skip it.
+
+---
+
+## Prefer / Adapt table (mode × lifecycle × artifacts)
+
+| Cursor mode | Prefer when | Task-driven Prefer | One-sentence pactile 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 read-only (no `task.py create` without consent) | None |
+| **Plan** | Scope / design / tradeoffs before code | Full Define: **`SwitchMode(plan)` immediately**. After review, `SwitchMode(agent)` or A′. **Save to workspace**, then map into `{TASK}/prd.md` | “Plan switch failed; wrote `{TASK}/prd.md`.” | Definition surfaces |
+| **Agent** | Approved build / verify / close | Default for **Execute** (and Approve / Close). `SwitchMode(agent)` when returning from Plan | — | Diff, `verify.md`, gates |
+| **Debug** | Repro / runtime / regressions | Prefer real Cursor Debug when reachable. Adapter does **not** own Debug UI docs | Evidence → `verify.md` | Notes / logs in `verify.md` |
+| **Multitask** | Independent write-sets after Execute is approved | Ask the user to open Multitask / Build in Parallel and hand worker packs. No API → `Task()` + Q12. **Not** a Pactile scheduler | Explicit `.pactile/tasks/<dir>` + Parent `integrate-child`; serial needs `serial_reason` | Child `verify` / `handoff`; Parent `task-map` |
+| **Canvas** | Analysis / inventory deliverable | Use for that class only. If unused, one sentence “not an analysis canvas deliverable” | Task artifacts remain SSOT | None in Kernel |
+| **Browser** | Visible Web UI changed | Capture evidence into `verify.md` | “UI changed; browser capture skipped — see `verify.md`.” | `verify.md` |
+| **Bugbot / Security Review** | Extra review wanted | Call when callable; appendix only | Contract Check still required | Appendix in `verify.md` |
+
+---
+
+## Mode-specific contracts
+
+### Ask ↔ no-task read-only
+
+- Official Ask does not edit files.
+- **Agent tools cannot `SwitchMode` into Ask.** If the user is not already on Ask, stay in Agent and keep the turn read-only.
+- Pure Q&A is no-task; no task creation without consent. Answer directly (Q14).
+- Side chats during Agent runs are still not Pactile artifacts.
+
+### Plan ↔ Define (Q15, Q23, Q24)
+
+- **Full Define:** `SwitchMode(plan)` immediately. Lite may stay in Agent.
+- Default plan save = **home directory** — **Save to workspace**, then the Agent maps into `{TASK}/prd.md` (and `design.md` / `implement.md` as the contract requires).
+- **Unlanded Plan must not map to Execute** (Q23).
+- Does **not** skip `start-execution --check` / Execute approval.
+- No product-code edits until Execute is approved (Q24). A human “start / Build” while still in Define is **A′**, not a skip.
+- If Plan switch or save fails: Q12 one sentence and author the same files in Agent.
+
+### Agent ↔ Execute
+
+- Default binding for **Execute**.
+- Stay inside the approved Definition / AC (and Full execution/verification contract).
+- Contract change → Return-to-Define, then the Execute gate again.
+- **Q19:** the main window collects worker **summaries**, conflicts, and gates — not full worker transcripts.
+
+### Debug ↔ evidence in `verify.md`
+
+- Prefer Cursor Debug instrumentation when reachable.
+- Always land proof in **`verify.md`**. Adapter does not ship Debug UI instructions.
+- Contract change → Return-to-Define. Implementation defect → back to Execute.
+
+### Visible parallel ↔ worker packs (Q13, Q16)
+
+There is **no** stable API to open Multitask / Build in Parallel.
+
+1. Ask the user to open the visible parallel surface and give each worker an explicit pack: `.pactile/tasks/<dir>` + contract slice. Never rely on `selected_task`.
+2. If they do not: `Task()` (typed `pactile-implement` / `pactile-check` / `pactile-research` when the enum exists) plus one Q12 sentence. **Do not block.**
+3. Silent same-session `Task()` without that sentence is a failed degrade.
+4. Pactile remains source of truth for status, gates, integration. This is **not** a Pactile-built parallel product.
+5. **Default parallel** when planning has ≥2 isolatable write-sets (Parent children with empty `depends_on`, or Full Task fan-out). Lite / single-file work is not forced into parallel agents.
+6. **Serial needs a written reason** (`serial_reason`): shared write-set / HITL or reviewer gate / `depends_on` unmet / user asked serial / conflict surface cannot isolate. HITL, `start-execution --approved`, reviewer gates, and `integrate-child` stay serial (`merge_limit: 1`).
+7. Parent alone `integrate-child`. Parallel-first declaration fields live in `.pactile/framework/parallel-first-execution.md` (core contract, host-agnostic).
+
+### Task API honest degrade (`generalPurpose`)
+
+This Cursor Task API may have **no** `pactile-implement` / `pactile-check` enum.
+
+- Dispatch workers as **`generalPurpose`**.
+- Do **not** label the run `true-independent`.
+- Do **not** nest further implement / check / research Task types from a child worker.
+- Parent retains `review-child` / `integrate-child`.
+
+Typed worker names above are **Adapter bindings**. Core contracts speak of typed implement / check / research workers, not these host strings.
+
+### Canvas / Bugbot / Browser / Automations
+
+- **Canvas (Q8):** analysis or inventory deliverables only. Not a second SSOT. No Kernel canvas slot.
+- **Bugbot / Security Review (Q7):** optional Verify appendix. Never a substitute for contract Check.
+- **Browser (Q10):** when a visible Web UI changed, capture evidence into `verify.md`. Kernel records Evidence, not a browser name.
+- **Automations / Loop (Q9):** unbound. Do not add a recurring lifecycle slot.
+
+---
+
+## Official `/goal` is not a Pactile Task (Q4, Q17, Q21, Q22, Q25)
+
+- Cursor **`/goal`** / **CreateGoal** is a durable **in-window** objective on the Cursor product.
+- It is **not** a Pactile task type, not Parent/Child, not `selected_task`, and does **not** skip Execute.
+- Do **not** restore `pactile-goal`. Continue / Finish-work / Handoff remain the `/pactile-*` escape hatches.
+- **Q17 / Q21:** when definition is already frozen, CreateGoal may drive **this window**. Slot clear → use it; inferring → ask. Goal text = one-line intent aligned with `prd.md` (Q25). Do not paste the PRD. Do not mirror Goal at Open.
+- **Q22:** on Close / Finalize, `UpdateGoal` complete or cancel plus one sentence. Goal failure **does not block** Close.
+- Definition change → `UpdateGoal`. Goal still does not replace gates or parallel.
+
+User-visible `/` escape hatches on agent-capable Cursor: **`/pactile-continue`**, **`/pactile-finish-work`**, **`/pactile-handoff`**. Internal skills (brainstorm, check, skill-creator, …) are **not** slash commands. `start` is filtered out on agent-capable Cursor.
+
+---
+
+## Build probe — Adapter dogfood, not Kernel (Q18, Q20, Q24)
+
+Probe the host design-surface **“start doing”** (Plan Build) **only in this Adapter**.
+
+- **Today (Native):** no Build tool. Hooks have no such event. BYOK `ExecutePlanAction` stays out of core.
+- **Current path = A′:** after `{TASK}/prd.md` is on disk and `start-execution --check` passes, Execute consent is `start-execution --approved` (or the equivalent human “start / Build” while still in Define — still A′, still the gate).
+- **Beta dogfood:** if a later Cursor build exposes a callable Build action, probe it. Landed contract + `--check` PASS → record Execute consent. Unstable / missing → A′ + Q12. Both paths are legal in the 0.5.x beta; the official default is decided before 0.5.0.
+- **Forbidden:** Build-probe fields in Kernel extras, Event Bridge default subscriptions, or module contracts. Core stores **approval**, not a host Build event.
+
+---
+
+## Callability (Agent tool table)
+
+| Surface | Plan | Agent | Ask | Debug | Parallel children |
+| --- | --- | --- | --- | --- | --- |
+| Agent `SwitchMode` | Yes → `plan` | Yes → `agent` | **No** | **No** | — |
+| Agent `Task` / Multitask UI | — | workers | — | — | Prefer **visible** surface; no API → ask user, else `Task()` + Q12 |
+| User / CLI modes | Plan UI / `/plan` | default | Ask UI / `/ask` | Debug UI | `/multitask`, Build in Parallel |
+| Plan Build (today) | **No tool** → A′ | — | — | — | — |
+
+If a cell is not callable here: Q12 one sentence, then the artifact path. Do not narrate an unsupported-mode catalog to the user.
+
+---
+
+## What pactile must not claim
+
+- Plans auto-save into `.pactile/tasks/`.
+- Multitask inherits `selected_task` or exposes a stable programmatic mode API.
+- Parallel agents cannot conflict without Pactile/worktree discipline.
+- `SwitchMode` can open Ask or Debug.
+- Shipping a parallel fake Plan/Ask/Debug product, or documenting gaps as product blame.
+- Replacing Cursor Multitask with a Pactile scheduler, queue, or new parallel CLI.
+- That a `generalPurpose` stand-in is `true-independent`.
+- That `/goal` / CreateGoal is a Pactile Task.
+- That an unlanded Plan, or a human “Build” before Execute approval, already is Execute.
+- That Bugbot / Security Review / Canvas replaced contract Check or task artifacts.
+- That a Build probe lives in Kernel extras or Event Bridge.
+
+---
+
+## Dogfood / probes
+
+| Mode | Minimum probe | Pass when |
+| --- | --- | --- |
+| **Plan** | Schema or live `SwitchMode(plan)` note in verify | Full Define tried once; Q12 + `{TASK}/prd.md` if unused |
+| **Ask / Debug** | Callability above | Artifact fallback; no unsupported-mode section |
+| **Multitask** | Ask user to open visible surface, or `Task()` + Q12 | Explicit child paths; default parallel; serial has `serial_reason`; Parent integrates |
+| **Agent** | Session implements under contract | Artifacts on disk |
+| **Task enum** | Missing `pactile-implement` / `pactile-check` | `generalPurpose` degrade; never `true-independent` |
+| **Plan Build** | No Native tool this cycle | A′ path documented; **not** in Kernel extras / Event Bridge |
+| **Goal** | CreateGoal when definition is frozen | One-line intent; `UpdateGoal` on Close; failure does not block |
+
+---
+
+## Rollback
+
+Docs + rules only:
+
+1. Delete `.pactile/framework/cursor-native-modes-guide.md` if reverting this Adapter map. Parallel-first **declaration** fields stay in `.pactile/framework/parallel-first-execution.md` (owned by the parallel-runtime slice).
+2. Drop related `guides/index.md` / `workflow.md` rows, or `pactile update` from pre-rewrite templates.
+3. **pactile**: revert this Child’s tip or delete mirrored template paths.
+4. Do **not** thicken `.cursor/rules/pactile-bootstrap.mdc` to replace this guide.
+
+---
+
+## Related
+
+- `.pactile/framework/cursor-subagent-policy.md`
+- `.pactile/framework/parallel-first-execution.md` (host-agnostic declaration; this guide binds the Cursor surface)
+- `.cursor/rules/pactile-bootstrap.mdc` (thin always-on pointer only)

package/dist/templates/markdown/framework/cursor-semantic-compliance.md.txt

@@ -0,0 +1,41 @@
+# Cursor semantic compliance (REC-06)
+
+## Plan vs exec
+
+| Layer | What counts |
+| --- | --- |
+| **Plan** | Router route `platform-semantic` (`platformNative: true`) or injected plan step「内置代码库语义搜索」 |
+| **Exec (Cursor)** | Tool log matches **platform semantic** patterns only — see `retrieval_tool_classification` |
+| **Not semantic exec on Cursor** | `fast_context_search`, pure Grep/Read/codegraph |
+
+## Classifying tool names from session logs
+
+Use the same patterns as telemetry:
+
+```powershell
+python -c "from common.retrieval_tool_classification import classify_tool_calls; print(classify_tool_calls(['Grep','codebase_search'], platform='cursor'))"
+```
+
+(Run from `.pactile/scripts` with `PYTHONPATH` set to that directory.)
+
+On **cursor**, `semantic_executed` = `platform_semantic_executed`. Track `fast_context_count` and `cursor_fast_context_misuse` separately.
+
+## Per-query checklist
+
+When `platform-semantic` is in the route list, verify in the session tool log:
+
+- `plan_block_in_prompt` — visible `## 代码库检索计划` (or equivalent) before code search
+- `tools_called` — verbatim tool names from Cursor
+- `platform_semantic_executed` / `fast_context_count` — from `classify_tool_calls(..., platform=cursor, cursor_env=...)`
+
+Plan-level presence does not imply execution-level use.
+
+## Agent instructions
+
+When `platform-semantic` is in the route list, `render_agent_instructions` appends **语义合规（Cursor）** requiring one built-in semantic search before Top-1 and logging the host tool name.
+
+## Native live proof (OC-15, 2026-07-02)
+
+Controlled main-session run (`07-02-child-oc15-semantic-proof`): 3/3 conceptual queries with router `platform-semantic` executed host tool **`SemanticSearch`** → `platform_semantic_executed=true` (`cursor_env=native`). See `research/native-semantic-execution-proof.md`.
+
+**Caveat:** Proves observability + compliant-agent behavior; does not guarantee all sessions follow the plan (historical evals show Grep-only gaps when agents skip semantic).

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

@@ -0,0 +1,90 @@
+# Cursor Subagent Policy
+
+> Current policy for dispatching Pactile research, implementation, and check
+> work through Cursor's supported native agent surfaces.
+
+## Invariants
+
+- Pactile never hardcodes vendor model identifiers in committed defaults.
+- The operator chooses the main-session model; a child inherits it unless the
+  native host surface provides an explicit supported override.
+- A child receives the smallest sufficient context pack and a concrete task.
+- The Parent owns decomposition, integration, and final acceptance.
+- A child does not recursively dispatch another Pactile child.
+- Model choice is not evidence. Source reads, diffs, tests, and receipts are.
+
+## Dispatch roles
+
+| Role | Purpose | Workspace access | Expected output |
+| --- | --- | --- | --- |
+| `pactile-research` | Answer a bounded repository question | Read-only | Findings in the assigned research path |
+| `pactile-implement` | Implement one frozen write set | Writable | Scoped changes plus focused verification |
+| `pactile-check` | Independently verify requirements and safety | Read-only by default | Verdict, evidence, and actionable findings |
+
+Use Cursor's built-in exploration surface for quick orientation that does not
+need a durable artifact. Use a Pactile research child when the result must be
+persisted, cited by a task, or kept separate from implementation context.
+
+## When to dispatch
+
+Dispatch only when the work is independently bounded and parallelism or
+context isolation materially helps. Keep work inline when it is a single small
+change, when every step touches the same write set, or when coordination would
+cost more than execution.
+
+Before dispatching:
+
+1. Freeze the child objective and write set in the Parent task map.
+2. Include `Selected task: <path>` as the first line of the child prompt.
+3. State whether the child is read-only or writable.
+4. State the required validation and stop conditions.
+5. Confirm dependency readiness and worktree ownership.
+
+## Model policy
+
+`model_policy: cursor-configured`
+
+Use only controls exposed by the current native Cursor surface. If no child
+override is available, inherit the Parent model and record that fact. Never
+edit generated agent files temporarily to smuggle a model identifier into a
+dispatch, and never mutate user settings as part of task execution.
+
+## Isolation and integration
+
+- Parallel writable children require disjoint worktrees or explicitly disjoint
+  write sets.
+- A shared worktree implies serial writable execution.
+- Research and check children may run concurrently when they are truly
+  read-only and do not compete for mutable generated state.
+- The Parent reviews each child diff before integration and re-runs the union
+  verification after all accepted changes are present.
+- Do not mark a check `true-independent` when it was performed by the same
+  writable execution context or by a generic child standing in for a missing
+  checker role.
+
+## Failure handling
+
+- Missing native child support: continue inline or open a separate user-owned
+  Agent chat only when the task contract permits it.
+- Busy or interrupted child: preserve its partial evidence, reclaim the lane,
+  and retry only the unfinished unit.
+- Write-set overlap: stop the conflicting child, reconcile ownership in the
+  Parent task map, then resume serially.
+- Unavailable model override: inherit the Parent model; do not block safe work.
+- Unverifiable result: treat it as orientation and reproduce the proof in the
+  Parent context.
+
+## Closeout
+
+The Parent records:
+
+- which role ran and whether it had write access;
+- the exact task/worktree and write-set boundary;
+- accepted or rejected findings;
+- focused validation from the child;
+- union validation after integration;
+- any degraded host capability or unresolved blocker.
+
+Historical client-specific routing experiments are intentionally absent from
+generated runtime guidance. They belong in versioned history, not in a fresh
+Pactile installation.

package/dist/templates/markdown/framework/dogfood-only-surfaces.md.txt

@@ -0,0 +1,28 @@
+# Dogfood-Only vs Default Install Surfaces
+
+> **Purpose**: An inventory of surfaces that exist in the **maintainer harness** (MyHarness) but are **not** shipped by a default `pactile init` / `pactile update`. Use it to avoid the false conclusion "the product feature disappeared" when comparing a consumer repo to the harness. A file missing from a consumer project is **by design**, not a regression — the CLI/script/guide surface still carries the capability.
+
+## Rule of thumb
+
+- **Shipped by default** = written by `pactile init --cursor` and refreshed by `pactile update` (workflow, `.pactile/framework/` docs, scripts, AGENTS.md PACTILE block, `.cursor/{commands,rules,agents,hooks}`). `.pactile/spec/` seeds are init-only and **never** refreshed — update never touches that directory.
+- **Dogfood-only / harness-only** = present only in the maintainer harness or after manual copy. Absence in a consumer repo is expected.
+
+## Inventory
+
+| Surface | Where it exists | Why dogfood-only | Decision |
+| --- | --- | --- | --- |
+| `.claude/skills/*` full suite | `.claude/skills/` in the harness | Cursor default install is **commands-only**; Claude skill files are for Claude platforms, not Cursor consumers | **non-Cursor** (not in Cursor default install) |
+| Private review-pool items / plan narratives | `.pactile/pool/items/`, `{TASK}/research/` in the harness | Personal or project-specific content; the pool **mechanism** ships, the items do not | **narrative not packaged** — mechanism ships, content stays local |
+| `.codegraph/`, `.worktrees/`, scratch/analysis files | Harness root | Per-machine index / tooling state | **local only** |
+
+## If a capability seems missing in a consumer repo
+
+1. Check the [internal-skills-cursor-reachability.md](./internal-skills-cursor-reachability.md) matrix — the capability's load channel (guide / script / agent / CLI) should be present.
+2. Check AGENTS.md `Invocation map (short)` — the intended entry point (`/pactile-handoff`, etc.).
+3. If the entry point is a harness-only file from the table above, the capability is intentionally **not** shipped to consumers — do not backfill it by copying harness files.
+
+## Related
+
+- [internal-skills-cursor-reachability.md](./internal-skills-cursor-reachability.md) — reachability of internal skill names.
+- [prd-grill-frontier.md](./prd-grill-frontier.md) — P11 grilling on-demand path.
+- AGENTS.md `Invocation map (short)` — session handoff = `/pactile-handoff`.

package/dist/templates/markdown/framework/execution-strategy.md.txt

@@ -0,0 +1,45 @@
+# Execution strategy (execution_mode / isolation)
+
+> **Purpose**: Suggest a Development Strategy Contract before you freeze `implement.md`, and align Phase 2 dispatch with the approved contract.
+
+This file answers **who** implements/checks and **where** files are edited. It is **not** a parallel scheduler. Parallel-first (default native parallel, serial needs `serial_reason`) lives in `workflow.md` and `cursor-native-modes-guide.md`; declaration fields in `parallel-first-execution.md`.
+
+---
+
+## Two orthogonal dimensions
+
+| Field | Question |
+| --- | --- |
+| `execution_mode` | **Who** implements and checks? (`inline` main session, `worker` pactile-implement/check agents, `child-task` Child worker) |
+| `isolation` | **Where** are files edited? (`main-worktree` vs `git-worktree` for Child) |
+
+Non-git repo roots do **not** force `inline` for code Full tasks; they only affect whether `git-worktree` / `prepare-child-worktree` is recommended.
+
+## Suggest (planning)
+
+```bash
+python3 ./.pactile/scripts/task.py suggest-execution-strategy <task-dir>
+python3 ./.pactile/scripts/task.py suggest-execution-strategy <task-dir> --json
+```
+
+Run during brainstorm / before finalizing the YAML block in `implement.md`. Reconcile suggestion with product intent; the contract in `implement.md` is authoritative after approval.
+
+## Default policy (v1)
+
+| Profile / signal | Suggested `execution_mode` | Suggested `isolation` |
+| --- | --- | --- |
+| Lite | (no contract) | — |
+| Full + touches code | `worker` | `main-worktree` |
+| Full + doc-only capabilities | `inline` | `main-worktree` |
+| Parent / has children | `inline` | `main-worktree` |
+| Child (`task.json` parent set) | `child-task` | `git-worktree` when git package root resolves; else `main-worktree` + WARN |
+
+`touches_code` is deterministic: code `optional_capabilities`, `package`/`scope` path segments (`src`, `packages`, `scripts`, …), or Full with `design.md` and non-doc-only capabilities. Rules live in `.pactile/config/execution-strategy-rules.json`.
+
+## Drift warning (preflight)
+
+`task.py start-execution <task> --check` prints `[execution-strategy] WARN` when the approved contract differs from a fresh suggestion. **Advisory only** — does not fail the gate.
+
+## Phase 2 alignment
+
+See `workflow.md` Phase 2.1 / 2.2 tables: spawn `pactile-implement` / `pactile-check` only when `execution_mode: worker`.

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

@@ -0,0 +1,31 @@
+# Framework Docs (`.pactile/framework/`)
+
+> **Ownership**: These files are **framework-managed**. `pactile update` refreshes them (with the same hash-conflict prompt as `workflow.md`). If you edit one, update will ask before overwriting — prefer putting project-specific norms in `.pactile/spec/` instead, which update never touches.
+
+Versioned framework and platform-adapter documentation. Project/team knowledge lives in `.pactile/spec/` (user-owned); this directory documents how the framework itself behaves.
+
+## Docs
+
+| Doc | What it covers |
+| --- | --- |
+| [prd-grill-frontier.md](./prd-grill-frontier.md) | On-demand path to the PRD grill and Frontier discipline (bundled `brainstorm` skill is SSOT) |
+| [internal-skills-cursor-reachability.md](./internal-skills-cursor-reachability.md) | How each internal workflow skill is reachable on Cursor (commands-only baseline) |
+| [dogfood-only-surfaces.md](./dogfood-only-surfaces.md) | Which surfaces ship by default vs exist only in the maintainer harness |
+| [cursor-subagent-policy.md](./cursor-subagent-policy.md) | When to spawn Pactile custom agents; model policy stays on the Cursor side |
+| [retrieval-daily-guide.md](./retrieval-daily-guide.md) | Daily retrieval tool routing (search vs retrieval-pack scoring; web-research gate) |
+| [cursor-native-modes-guide.md](./cursor-native-modes-guide.md) | Mapping Cursor Plan / Ask / Debug / Agent / Multitask onto Pactile phases |
+| [parallel-first-execution.md](./parallel-first-execution.md) | Parallel-first **product** principle + execution contract: native parallel default, `serial_reason`, task-map fields |
+| [middleware-protocol.md](./middleware-protocol.md) | Middleware Protocol v1: one ABI, overlay `.pactile/middleware/`, shipped providers (smart-search required; others optional), `update` never writes/deletes/hashes overlay |
+| [upgrade.md](./upgrade.md) | Terminal-user upgrade half-page: install package → `pactile update` → confirm → keep working |
+| [release-boundary.md](./release-boundary.md) | PACTILE this-batch ship vs independent pactile-byok ship; BYOK is not a PACTILE release gate |
+| [cursor-context-injection-guide.md](./cursor-context-injection-guide.md) | Which Cursor injection channels actually reach the model |
+| [cursor-semantic-compliance.md](./cursor-semantic-compliance.md) | Plan-vs-exec semantic compliance on Cursor |
+| [injection-budget-guide.md](./injection-budget-guide.md) | Context injection budget across reliable Cursor channels |
+| [execution-strategy.md](./execution-strategy.md) | Development Strategy Contract (`execution_mode` / isolation) |
+| [verification-strength-guide.md](./verification-strength-guide.md) | How deeply tasks must be verified before closeout, graded by task mode |
+| [artifact-locale-guide.md](./artifact-locale-guide.md) | How human-reviewed artifacts follow the user's language |
+
+## Related
+
+- `.pactile/workflow.md` — the workflow itself (also framework-managed)
+- `.pactile/spec/guides/` — project thinking guides (user-owned; update never modifies)

package/dist/templates/markdown/framework/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-pactile-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 active controls** — execution approval and retrieval policy remain enforced. Intake is handled by `intake-basic`; it has no `[Triage:]` line, and the removed `pactile-triage.mdc` is not an always-on gate.
+- **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 PACTILE block warn 4 KiB |
+| **Session once** | C03 sessionStart | New session | Keep the context-progressive Session pack 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: .pactile/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 ./.pactile/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 ./.pactile/scripts/injection_budget_probe.py --repo-root .
+
+# Task jsonl + dispatch size
+python ./.pactile/scripts/injection_budget_probe.py --repo-root . --task .pactile/tasks/<task-dir> --dispatch-role implement
+
+# CI / gate style (fail on WARN or rules >32KiB)
+python ./.pactile/scripts/injection_budget_probe.py --repo-root . --strict
+```
+
+Constants live in `.pactile/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/framework/internal-skills-cursor-reachability.md.txt

@@ -0,0 +1,45 @@
+# Internal Skills Cursor Reachability Matrix
+
+> **Purpose**: Every internal skill referenced by framework or task artifacts must have a documented **load channel** on a pure Cursor project. Root `AGENTS.md` is now a compact pointer block, not an invocation map. Internal workflow skills are **not** shipped to `.cursor/skills/` and have **no** default slash command — by design (commands-only). This matrix is the honest index: how each internal name is actually reachable on-demand, so an agent never claims a skill is loaded without a file read, and users never assume internal skills are slash commands.
+
+## Commands-only baseline
+
+- Default Cursor install writes only: `.cursor/commands/` (user slash commands), `.cursor/rules/*.mdc`, `.cursor/agents/*.md`, `.cursor/hooks`, and `.pactile/` (workflow, framework docs, scripts, spec/guides seeds).
+- Bundled skill **bodies** live in the npm package templates (`dist/templates/common/skills/`, `dist/templates/common/bundled-skills/`). They are **not** copied into a consumer project by `pactile init` on Cursor.
+- "Not in the project" ≠ "missing from the framework": the CLI/script/agent/guide surface below is the reachable carrier.
+
+## Matrix
+
+| Skill name | Package SSOT | Cursor load channel | Slash? |
+| --- | --- | --- | --- |
+| `pactile-brainstorm` (PRD Grill) | `common/skills/brainstorm.md` | **Read `./prd-grill-frontier.md`** (on-demand summary; full body in npm package) | no |
+| `pactile-micro-grill` | `bundled-skills/pactile-micro-grill/SKILL.md` | Before a Task, Intake comes from `.pactile/modules/intake-basic/contract.md`; after Open, **read `./prd-grill-frontier.md` §Micro-grill unresolved**. Full body remains in the npm package. | no |
+| `pactile-before-dev` | `common/skills/before-dev.md` | Read task artifacts → `get_context.py --mode packages` → spec indexes; full body in npm package | no |
+| `pactile-break-loop` | `common/skills/break-loop.md` | Activated `debug-recovery` module routes Debug → evidence → `pactile-break-loop`; full body in npm package; output pattern in `.pactile/spec/guides/debug-loop-guide.md` | no |
+| `pactile-update-spec` | `common/skills/update-spec.md` | `close-basic` emits the learning disposition; activated `spec-learning` owns `update-spec`. Full body remains in the npm package. | no |
+| `pactile-check` | `bundled-skills/pactile-check/SKILL.md` | **Agent form `.cursor/agents/pactile-check.md`** (Task tool, dual-axis) — prefer Agent when `execution_mode: worker` | no |
+| `pactile-meta` | `bundled-skills/pactile-meta/SKILL.md` | Maintainer skill; body in npm package; no Cursor project file (not routed in consumer workflows) | no |
+| `pactile-spec-bootstrap` | `bundled-skills/pactile-spec-bootstrap/SKILL.md` | One-shot scaffolding skill; body in npm package; not routed in steady-state consumer workflow | no |
+| `pactile-skill-creator` | `bundled-skills/pactile-skill-creator/SKILL.md` | **Authoring-time (mandatory for new / structural skill edits):** Read `pactile/packages/cli/src/templates/common/bundled-skills/pactile-skill-creator/SKILL.md` then `…/references/review-checklist.md`. Harness dogfood copy: `.claude/skills/pactile-skill-creator/SKILL.md` and `.claude/skills/pactile-skill-creator/references/review-checklist.md`. Installed npm: `dist/templates/common/bundled-skills/pactile-skill-creator/`. Not a slash command. Skip typo/link-only. Does **not** apply to Cursor product skills (`~/.cursor/skills-cursor/`). | no |
+| `smart-search-cli` | `bundled-skills/smart-search-cli/SKILL.md` | **`python ./.pactile/scripts/run_smart_search.py "<question>" --intent deep-research --json`** (shipped script); Cursor web tools are downgrade-only fallback | no |
+| `pactile-handoff` | `bundled-skills/pactile-handoff/SKILL.md` | **Slash `/pactile-handoff`** (writes session handoff to OS temp dir) | **yes** |
+| `pactile-continue` / `pactile-finish-work` / `pactile-start` | `common/commands/*.md` | **Slash `/pactile-continue`, `/pactile-finish-work`** (`pactile-start` filtered on agent-capable platforms) | **yes** |
+| `pactile-research` / `pactile-implement` / `pactile-check` (agents) | `packages/cli/src/templates/cursor/agents/*.md` | **`.cursor/agents/*.md`** — Agent (Task tool), dispatched via `generate_dispatch_prompt.py` (CLI Layer 2) | no |
+
+## Reading this matrix
+
+- **Reachable on-demand** (green path): brainstorm → frontier guide; micro-grill → `intake-basic` before Task or the frontier guide after Open; check → agent; smart-search → script; **skill authoring → Read `pactile-skill-creator/SKILL.md` + `review-checklist.md`** (paths in the matrix row).
+- **Body in npm package only**: the skill is real and shipped, but a pure Cursor project has no project-relative copy. Activated modules or task/interface artifacts route its **behavior**; the full body is discoverable under the installed package (`npm root -g` → `dist/templates/…`). Do not claim these are loaded without reading the actual body when the behavior matters.
+- **Maintainer-only** (`pactile-meta`, `pactile-spec-bootstrap`): documented here for framework completeness; not part of the consumer execution path. No extra consumer load path beyond the package body.
+- **Authoring-time mandatory** (`pactile-skill-creator`): not a consumer runtime path and not a slash command, but **must** be Read before creating or structurally changing Pactile / blaze-skills / harness skills. Cursor product skills are out of scope.
+
+## Honesty rule
+
+If a framework or task artifact names a skill, it must be reachable here. If a row ever becomes unreachable, add a project-relative carrier (guide/script/agent) or remove the stale reference. Root `AGENTS.md` remains a pointer block and need not enumerate internal skills. Never claim "skill loaded" without a file read.
+
+## Related
+
+- [prd-grill-frontier.md](./prd-grill-frontier.md) — P11: brainstorm/grill on-demand path.
+- [dogfood-only-surfaces.md](./dogfood-only-surfaces.md) — what ships only in the maintainer harness (goal_*.py, `.claude/skills`, local overlays).
+- Root `AGENTS.md` PACTILE block — compact pointers only; it is not an invocation map or skill inventory.
+- `./cursor-context-injection-guide.md` — which channels actually reach the Cursor model.