@blxzer/cursor-trellis 0.2.7 → 0.2.8

package/dist/commands/validate-rules.js

@@ -0,0 +1,33 @@
+import chalk from "chalk";
+import { assertCursorRulesValid, formatRuleValidationErrors, validateRulesDir, validateTemplateRules, } from "../utils/validate-rules.js";
+export async function runValidateRules(cwd, options = {}) {
+    if (options.dir) {
+        const result = validateRulesDir(options.dir);
+        if (!result.ok) {
+            console.error(chalk.red("Cursor rules validation failed:"));
+            console.error(formatRuleValidationErrors(result));
+            process.exit(1);
+        }
+        console.log(chalk.green(`✓ Cursor rules valid (${options.dir})`));
+        return;
+    }
+    const templateResult = validateTemplateRules();
+    if (!templateResult.ok) {
+        console.error(chalk.red("Cursor rules template validation failed:"));
+        console.error(formatRuleValidationErrors(templateResult));
+        process.exit(1);
+    }
+    console.log(chalk.green("✓ Cursor rules templates valid"));
+    if (options.templatesOnly) {
+        return;
+    }
+    try {
+        assertCursorRulesValid(cwd);
+        console.log(chalk.green(`✓ Cursor rules installation valid (${cwd})`));
+    }
+    catch (error) {
+        console.error(chalk.red("Error:"), error instanceof Error ? error.message : error);
+        process.exit(1);
+    }
+}
+//# sourceMappingURL=validate-rules.js.map

package/dist/commands/validate-rules.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate-rules.js","sourceRoot":"","sources":["../../src/commands/validate-rules.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,OAAO,CAAC;AAE1B,OAAO,EACL,sBAAsB,EACtB,0BAA0B,EAC1B,gBAAgB,EAChB,qBAAqB,GACtB,MAAM,4BAA4B,CAAC;AAOpC,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,GAAW,EACX,UAAgC,EAAE;IAElC,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC;QAChB,MAAM,MAAM,GAAG,gBAAgB,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QAC7C,IAAI,CAAC,MAAM,CAAC,EAAE,EAAE,CAAC;YACf,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,iCAAiC,CAAC,CAAC,CAAC;YAC5D,OAAO,CAAC,KAAK,CAAC,0BAA0B,CAAC,MAAM,CAAC,CAAC,CAAC;YAClD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAClB,CAAC;QACD,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,yBAAyB,OAAO,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC;QAClE,OAAO;IACT,CAAC;IAED,MAAM,cAAc,GAAG,qBAAqB,EAAE,CAAC;IAC/C,IAAI,CAAC,cAAc,CAAC,EAAE,EAAE,CAAC;QACvB,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,0CAA0C,CAAC,CAAC,CAAC;QACrE,OAAO,CAAC,KAAK,CAAC,0BAA0B,CAAC,cAAc,CAAC,CAAC,CAAC;QAC1D,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;IACD,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,gCAAgC,CAAC,CAAC,CAAC;IAE3D,IAAI,OAAO,CAAC,aAAa,EAAE,CAAC;QAC1B,OAAO;IACT,CAAC;IAED,IAAI,CAAC;QACH,sBAAsB,CAAC,GAAG,CAAC,CAAC;QAC5B,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,sCAAsC,GAAG,GAAG,CAAC,CAAC,CAAC;IACzE,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO,CAAC,KAAK,CACX,KAAK,CAAC,GAAG,CAAC,QAAQ,CAAC,EACnB,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,CAC/C,CAAC;QACF,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;AACH,CAAC"}

package/dist/configurators/cursor2plus-local.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cursor2plus-local.d.ts","sourceRoot":"","sources":["../../src/configurators/cursor2plus-local.ts"],"names":[],"mappings":"AAYA;;;GAGG;AACH,wBAAsB,2BAA2B,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAwB5E"}
+{"version":3,"file":"cursor2plus-local.d.ts","sourceRoot":"","sources":["../../src/configurators/cursor2plus-local.ts"],"names":[],"mappings":"AAaA;;;GAGG;AACH,wBAAsB,2BAA2B,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAyB5E"}

package/dist/configurators/cursor2plus-local.js

@@ -1,7 +1,7 @@
 import path from "node:path";
 import { DIR_NAMES } from "../constants/paths.js";
 import { ensureDir, writeFile } from "../utils/file-writer.js";
-import { cursor2plusPatchScript, cursor2plusReadme, cursor2plusConfigExample, subagentModelsExample, trellisTaskModelsJson5Example, trellisTaskModelsConfigPy, } from "../templates/trellis/local/index.js";
+import { cursor2plusPatchScript, cursor2plusReadme, cursor2plusSmokeScript, cursor2plusConfigExample, subagentModelsExample, trellisTaskModelsJson5Example, trellisTaskModelsConfigPy, } from "../templates/trellis/local/index.js";
 /**
  * Materialize Cursor++ BYOK local operator bundle (strategy C).
  * Native Cursor API users can ignore. Never overwrites config.local.json.
@@ -12,6 +12,7 @@ export async function writeCursor2plusLocalBundle(cwd) {
     ensureDir(bundleDir);
     await writeFile(path.join(bundleDir, "patch_wpelc8.py"), cursor2plusPatchScript);
     await writeFile(path.join(bundleDir, "trellis_task_models_config.py"), trellisTaskModelsConfigPy);
+    await writeFile(path.join(bundleDir, "smoke.py"), cursor2plusSmokeScript);
     await writeFile(path.join(bundleDir, "README.md"), cursor2plusReadme);
     await writeFile(path.join(bundleDir, "config.local.json.example"), cursor2plusConfigExample);
     await writeFile(path.join(localRoot, "subagent-models.json.example"), subagentModelsExample);

package/dist/configurators/cursor2plus-local.js.map

@@ -1 +1 @@
-{"version":3,"file":"cursor2plus-local.js","sourceRoot":"","sources":["../../src/configurators/cursor2plus-local.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAClD,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AAC/D,OAAO,EACL,sBAAsB,EACtB,iBAAiB,EACjB,wBAAwB,EACxB,qBAAqB,EACrB,6BAA6B,EAC7B,yBAAyB,GAC1B,MAAM,qCAAqC,CAAC;AAE7C;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,2BAA2B,CAAC,GAAW;IAC3D,MAAM,SAAS,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,SAAS,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;IAC9D,MAAM,SAAS,GAAG,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,aAAa,CAAC,CAAC;IACtD,SAAS,CAAC,SAAS,CAAC,CAAC;IAErB,MAAM,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,iBAAiB,CAAC,EAAE,sBAAsB,CAAC,CAAC;IACjF,MAAM,SAAS,CACb,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,+BAA+B,CAAC,EACrD,yBAAyB,CAC1B,CAAC;IACF,MAAM,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,WAAW,CAAC,EAAE,iBAAiB,CAAC,CAAC;IACtE,MAAM,SAAS,CACb,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,2BAA2B,CAAC,EACjD,wBAAwB,CACzB,CAAC;IAEF,MAAM,SAAS,CACb,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,8BAA8B,CAAC,EACpD,qBAAqB,CACtB,CAAC;IACF,MAAM,SAAS,CACb,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,mCAAmC,CAAC,EACzD,6BAA6B,CAC9B,CAAC;AACJ,CAAC"}
+{"version":3,"file":"cursor2plus-local.js","sourceRoot":"","sources":["../../src/configurators/cursor2plus-local.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAClD,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AAC/D,OAAO,EACL,sBAAsB,EACtB,iBAAiB,EACjB,sBAAsB,EACtB,wBAAwB,EACxB,qBAAqB,EACrB,6BAA6B,EAC7B,yBAAyB,GAC1B,MAAM,qCAAqC,CAAC;AAE7C;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,2BAA2B,CAAC,GAAW;IAC3D,MAAM,SAAS,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,SAAS,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;IAC9D,MAAM,SAAS,GAAG,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,aAAa,CAAC,CAAC;IACtD,SAAS,CAAC,SAAS,CAAC,CAAC;IAErB,MAAM,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,iBAAiB,CAAC,EAAE,sBAAsB,CAAC,CAAC;IACjF,MAAM,SAAS,CACb,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,+BAA+B,CAAC,EACrD,yBAAyB,CAC1B,CAAC;IACF,MAAM,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,UAAU,CAAC,EAAE,sBAAsB,CAAC,CAAC;IAC1E,MAAM,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,WAAW,CAAC,EAAE,iBAAiB,CAAC,CAAC;IACtE,MAAM,SAAS,CACb,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,2BAA2B,CAAC,EACjD,wBAAwB,CACzB,CAAC;IAEF,MAAM,SAAS,CACb,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,8BAA8B,CAAC,EACpD,qBAAqB,CACtB,CAAC;IACF,MAAM,SAAS,CACb,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,mCAAmC,CAAC,EACzD,6BAA6B,CAC9B,CAAC;AACJ,CAAC"}

package/dist/migrations/manifests/0.2.2.json

@@ -1,9 +1,9 @@
-{
-  "version": "0.2.2",
-  "description": "v0.2.2 — smart-search wrapper path fix (backfilled manifest).",
-  "breaking": false,
-  "recommendMigrate": false,
-  "changelog": "**@blxzer/cursor-trellis 0.2.2 / @blxzer/cursor-trellis-core 0.2.2**\n\n### Fixed\n- fix: smart-search wrapper path resolution\n\n### Upgrade\n```bash\nnpm install -g @blxzer/cursor-trellis@0.2.2\ntrellis update\n```",
-  "migrations": [],
-  "notes": "Manifest backfilled for npm continuity; shipped without repo manifest."
+{
+  "version": "0.2.2",
+  "description": "v0.2.2 — smart-search wrapper path fix (backfilled manifest).",
+  "breaking": false,
+  "recommendMigrate": false,
+  "changelog": "**@blxzer/cursor-trellis 0.2.2 / @blxzer/cursor-trellis-core 0.2.2**\n\n### Fixed\n- fix: smart-search wrapper path resolution\n\n### Upgrade\n```bash\nnpm install -g @blxzer/cursor-trellis@0.2.2\ntrellis update\n```",
+  "migrations": [],
+  "notes": "Manifest backfilled for npm continuity; shipped without repo manifest."
 }

package/dist/migrations/manifests/0.2.4.json

@@ -1,9 +1,9 @@
-{
-  "version": "0.2.4",
-  "description": "v0.2.4 — aligned core/cli publish (backfilled manifest).",
-  "breaking": false,
-  "recommendMigrate": false,
-  "changelog": "**@blxzer/cursor-trellis 0.2.4 / @blxzer/cursor-trellis-core 0.2.4**\n\n### Changed\n- chore: synchronized @blxzer/cursor-trellis-core with CLI release line\n\n### Upgrade\n```bash\nnpm install -g @blxzer/cursor-trellis@0.2.4\ntrellis update\n```",
-  "migrations": [],
-  "notes": "Manifest backfilled for npm continuity."
+{
+  "version": "0.2.4",
+  "description": "v0.2.4 — aligned core/cli publish (backfilled manifest).",
+  "breaking": false,
+  "recommendMigrate": false,
+  "changelog": "**@blxzer/cursor-trellis 0.2.4 / @blxzer/cursor-trellis-core 0.2.4**\n\n### Changed\n- chore: synchronized @blxzer/cursor-trellis-core with CLI release line\n\n### Upgrade\n```bash\nnpm install -g @blxzer/cursor-trellis@0.2.4\ntrellis update\n```",
+  "migrations": [],
+  "notes": "Manifest backfilled for npm continuity."
 }

package/dist/migrations/manifests/0.2.5.json

@@ -1,9 +1,9 @@
-{
-  "version": "0.2.5",
-  "description": "v0.2.5 — smart-search bin wrapper path fix.",
-  "breaking": false,
-  "recommendMigrate": false,
-  "changelog": "**@blxzer/cursor-trellis 0.2.5 / @blxzer/cursor-trellis-core 0.2.5**\n\n### Fixed\n- fix(bin): smart-search wrapper path under npm/bin/\n\n### Upgrade\n```bash\nnpm install -g @blxzer/cursor-trellis@0.2.5\ntrellis update\n```",
-  "migrations": [],
-  "notes": "Matches chore(release): 0.2.5 on main."
+{
+  "version": "0.2.5",
+  "description": "v0.2.5 — smart-search bin wrapper path fix.",
+  "breaking": false,
+  "recommendMigrate": false,
+  "changelog": "**@blxzer/cursor-trellis 0.2.5 / @blxzer/cursor-trellis-core 0.2.5**\n\n### Fixed\n- fix(bin): smart-search wrapper path under npm/bin/\n\n### Upgrade\n```bash\nnpm install -g @blxzer/cursor-trellis@0.2.5\ntrellis update\n```",
+  "migrations": [],
+  "notes": "Matches chore(release): 0.2.5 on main."
 }

package/dist/migrations/manifests/0.2.6.json

@@ -1,9 +1,9 @@
-{
-  "version": "0.2.6",
-  "description": "v0.2.6 — public docs expansion (skills, subagents, task-system).",
-  "breaking": false,
-  "recommendMigrate": false,
-  "changelog": "**@blxzer/cursor-trellis 0.2.6 / @blxzer/cursor-trellis-core 0.2.6**\n\n### Changed\n- docs: GitHub docs — workflow, retrieval, skills, subagents, task-system, spec-system\n- docs(community): Linux.do release companion doc\n\n### Upgrade\n```bash\nnpm install -g @blxzer/cursor-trellis@0.2.6\ntrellis update\n```",
-  "migrations": [],
-  "notes": "Published at 0.2.6; manifest added in 0.2.7 release train."
+{
+  "version": "0.2.6",
+  "description": "v0.2.6 — public docs expansion (skills, subagents, task-system).",
+  "breaking": false,
+  "recommendMigrate": false,
+  "changelog": "**@blxzer/cursor-trellis 0.2.6 / @blxzer/cursor-trellis-core 0.2.6**\n\n### Changed\n- docs: GitHub docs — workflow, retrieval, skills, subagents, task-system, spec-system\n- docs(community): Linux.do release companion doc\n\n### Upgrade\n```bash\nnpm install -g @blxzer/cursor-trellis@0.2.6\ntrellis update\n```",
+  "migrations": [],
+  "notes": "Published at 0.2.6; manifest added in 0.2.7 release train."
 }

package/dist/migrations/manifests/0.2.7.json

@@ -1,9 +1,9 @@
-{
-  "version": "0.2.7",
-  "description": "v0.2.7 — execution strategy suggest + contract-aware workflow dispatch.",
-  "breaking": false,
-  "recommendMigrate": false,
-  "changelog": "**@blxzer/cursor-trellis 0.2.7 / @blxzer/cursor-trellis-core 0.2.7**\n\n### Added\n- feat(task): `suggest-execution-strategy`, `execution-strategy-rules.json`, drift WARN on `start-execution --check`\n- docs: `execution-strategy.md` guide; backfilled manifests 0.2.2–0.2.6\n\n### Changed\n- workflow: Phase 2 dispatch follows `execution_mode` (`worker` vs `inline` vs `child-task`)\n\nRun `trellis update` in each project.",
-  "migrations": [],
-  "notes": "Full code-touching tasks default-suggest worker + main-worktree; contract in implement.md remains authoritative."
+{
+  "version": "0.2.7",
+  "description": "v0.2.7 — execution strategy suggest + contract-aware workflow dispatch.",
+  "breaking": false,
+  "recommendMigrate": false,
+  "changelog": "**@blxzer/cursor-trellis 0.2.7 / @blxzer/cursor-trellis-core 0.2.7**\n\n### Added\n- feat(task): `suggest-execution-strategy`, `execution-strategy-rules.json`, drift WARN on `start-execution --check`\n- docs: `execution-strategy.md` guide; backfilled manifests 0.2.2–0.2.6\n\n### Changed\n- workflow: Phase 2 dispatch follows `execution_mode` (`worker` vs `inline` vs `child-task`)\n\nRun `trellis update` in each project.",
+  "migrations": [],
+  "notes": "Full code-touching tasks default-suggest worker + main-worktree; contract in implement.md remains authoritative."
 }

package/dist/migrations/manifests/0.2.8.json

@@ -0,0 +1,9 @@
+{
+  "version": "0.2.8",
+  "description": "v0.2.8 — Cursor platform adaptation Phase 0 + Phase 1+2: validate-rules gate, agent entry-points, cursor2plus safety, retrieval compliance, evidence pack, task path fallback.",
+  "breaking": false,
+  "recommendMigrate": false,
+  "changelog": "**@blxzer/cursor-trellis 0.2.8 / @blxzer/cursor-trellis-core 0.2.8**\n\n### Added\n- feat(cursor): `trellis validate-rules` hard gate + `pnpm mirror-check` for rules/agents templates\n- feat(cursor): agent templates open with Entry points + Context source (Layer 2 PRIMARY)\n- feat(cursor2plus): Method 2.5 safety gate (`--approve`, `--check-compat`, `smoke.py`, Native safe-to-ignore)\n- feat(retrieval): BYOK/Native compliance, `unknown` conservative, LSP caveat, telemetry planned/executed split\n- feat(cli): task.py select fallback tip + `generate_dispatch_prompt.py --task` primary fallback\n- feat(retrieval): evidence pack integration (finish/check cite pack) + research prompt provider caveats\n\n### Changed\n- agent templates now open with Entry points / Context source sections\n- retrieval router: LSP/GO_TO_DEFINITION → codegraph + Read + caveat\n- `patch_wpelc8.py` bare invocation no longer implicit writes\n\nRun `trellis update` in each project.",
+  "migrations": [],
+  "notes": "init/update now run assertCursorRulesValid(); Cursor++ patch requires --approve; unknown cursorEnv routes conservatively to BYOK + warning."
+}

package/dist/templates/common/bundled-skills/trellis-cursor2plus-setup/SKILL.md

@@ -20,7 +20,7 @@ Do **not** ask the user to hand-edit slugs (`model-xxxxx`) unless they prefer it
 - User says they use **Cursor++ BYOK** and want per–subagent-type models.
 - After Cursor++ **providers** change: re-list, adjust fallbacks, re-patch.
 
-Native **Cursor API** (no Cursor++): **stop** — frontmatter `model:` works; this skill does not apply.
+Native **Cursor API** (no Cursor++): **stop** — frontmatter `model:` works; this skill does not apply. Tell the user: **`.trellis/local/cursor2plus/` is safe to ignore or delete** unless they use Cursor++ BYOK.
 
 ## Workflow
 
@@ -40,7 +40,7 @@ Native **Cursor API** (no Cursor++): **stop** — frontmatter `model:` works; th
 5. Run:
    ```bash
    python ./.trellis/local/cursor2plus/patch_wpelc8.py --print-map
-   python ./.trellis/local/cursor2plus/patch_wpelc8.py
+   python ./.trellis/local/cursor2plus/patch_wpelc8.py --apply --approve
    ```
 6. Tell user: **Developer: Reload Window** in Cursor (once per patch).
 7. If stderr shows `WARN ... using fallback`, explain that primary was missing from current `providers.json` and fallback was used — suggest updating primary/fallback names, not panicking.

package/dist/templates/common/commands/finish-work.md

@@ -4,6 +4,18 @@ Wrap up the current session: archive the selected task (and any other completed-
 
 Before archive, confirm `verify.md` includes Phase 3.3 **Learning decision** (`update-spec` | `no-update` | `unsure`) and gate-compatible evidence per `.trellis/spec/guides/durable-learning-decision-guide.md`. Run `task.py archive <task> --check` when unsure.
 
+## Evidence pack reference (optional — graceful skip)
+
+When the selected task has `{TASK}/research/retrieval-pack-latest.json` (written by the research-end `stop` hook via `get_context --mode retrieval-pack`, or by an explicit pack run during Phase 3.1):
+
+1. Read the JSON; note top `contextPack.selected` items (`title`, `source`, `reference`, `score`) and `collection` counts.
+2. Ensure `verify.md` includes an `## Evidence pack reference` section citing those ranked sources or documenting explicit gaps.
+3. If the section is missing, add it before proceeding to archive.
+
+If the file does not exist: **skip silently** — no error, no user prompt. Pack absence is normal when the task did not use research/smart-search.
+
+Pack format: `version`, `source` (`retrieval-pack-orchestrator`), `contextPack.selected[]`, `scoredEvidence`, `collection`. Smart-search manifests that feed scoring live under `{TASK}/research/smart-search/<run-id>/` (from `run_smart_search.py`).
+
 ## Step 1: Survey current state
 
 ```bash

package/dist/templates/common/skills/check.md

@@ -70,6 +70,10 @@ Run the project's lint, type-check, and test commands. Fix any failures before p
 - [ ] **`verify.md` lists unresolved retrieval gaps** — external facts still unverified, missing `research/` or `research/smart-search/` evidence, or claims without source/Git/test corroboration
 - [ ] If `{TASK}/research/retrieval-pack-latest.json` exists, top `contextPack.selected` items are cited or gaps are explicitly noted in `verify.md`
 
+**Evidence pack (graceful):** Path `{TASK}/research/retrieval-pack-latest.json`. If absent, skip — no error.
+
+When present, Read the pack and ensure `verify.md` has `## Evidence pack reference` citing `contextPack.selected` (`title`, `source`, `reference`, `score`) or explicit gaps. Empty `selected` with existing `research/` → note stale pack or scoring failure in `verify.md`.
+
 ## Step 5: Cross-Layer Dimensions (if applicable)
 
 Skip this step if your change is confined to a single layer.

package/dist/templates/cursor/agents/trellis-check.md

@@ -3,6 +3,17 @@ name: trellis-check
 description: Trellis quality check agent. Use this exact agent for Trellis task verification, check.jsonl context injection, and self-fixing code review. Do not use generic/default/generalPurpose agents for Trellis checks.
 tools: Read, Write, Edit, Bash, Glob, Grep, mcp__exa__web_search_exa, mcp__exa__get_code_context_exa
 ---
+
+## Entry points
+
+- **Agent session:** Open this agent file manually in a new chat — context from this file + your main-session prompt.
+- **Task dispatch:** Run `python ./.trellis/scripts/generate_dispatch_prompt.py --agent check` → pass stdout as `Task(..., prompt=...)` — context from the Layer 2 prompt.
+
+## Context source
+
+- **Layer 2 prompt = PRIMARY (guaranteed)** — always generate via CLI before `Task(trellis-check)`.
+- **Hook `additional_context` = best-effort only** — Cursor #158452: not guaranteed to reach the model; optimization / fallback only.
+
 # Check Agent
 
 You are the Check Agent in the Trellis workflow.
@@ -107,6 +118,27 @@ If failed, fix issues and re-run.
 - [ ] **`verify.md` lists unresolved retrieval gaps** (unverified external facts, missing `research/` or `research/smart-search/` evidence, claims without source/Git/test proof)
 - [ ] If `{TASK}/research/retrieval-pack-latest.json` exists (research-end hook), cite top ranked items or document gaps in `verify.md`
 
+**Evidence pack (graceful):** Pack path is `{TASK}/research/retrieval-pack-latest.json`. If missing, skip this block — no error.
+
+When the pack exists:
+
+```bash
+# Optional: confirm path from selected task
+python ./.trellis/scripts/task.py selected --source
+```
+
+Read `{TASK}/research/retrieval-pack-latest.json` and use `contextPack.selected` (top items: `title`, `source`, `reference`, `score`). Add or update `verify.md` with:
+
+```markdown
+## Evidence pack reference
+
+- Pack: `{TASK}/research/retrieval-pack-latest.json` (contextPack.selected=N, artifacts=M, smart-search=K)
+- Cited: <title> — <source> — <reference>
+- Gaps: <any high-score omitted items or unverified external claims>
+```
+
+If `contextPack.selected` is empty but research artifacts exist, document why (budget, failed manifests, or stale pack) instead of silently ignoring the pack.
+
 ---
 
 ## Report Format

package/dist/templates/cursor/agents/trellis-implement.md

@@ -3,6 +3,17 @@ name: trellis-implement
 description: Trellis implementation agent. Use this exact agent for Trellis task implementation, implement.jsonl context injection, and hook-injection tests. Do not use generic/default/generalPurpose agents for Trellis implementation. No git commit allowed.
 tools: Read, Write, Edit, Bash, Glob, Grep, mcp__exa__web_search_exa, mcp__exa__get_code_context_exa
 ---
+
+## Entry points
+
+- **Agent session:** Open this agent file manually in a new chat — context from this file + your main-session prompt.
+- **Task dispatch:** Run `python ./.trellis/scripts/generate_dispatch_prompt.py --agent implement` → pass stdout as `Task(..., prompt=...)` — context from the Layer 2 prompt.
+
+## Context source
+
+- **Layer 2 prompt = PRIMARY (guaranteed)** — always generate via CLI before `Task(trellis-implement)`.
+- **Hook `additional_context` = best-effort only** — Cursor #158452: not guaranteed to reach the model; optimization / fallback only.
+
 # Implement Agent
 
 You are the Implement Agent in the Trellis workflow.

package/dist/templates/cursor/agents/trellis-research.md

@@ -3,6 +3,17 @@ name: trellis-research
 description: Trellis research agent. Use this exact agent for Trellis task research and research/ persistence. Do not use generic/default/generalPurpose agents for Trellis research.
 tools: Read, Write, Glob, Grep, Bash, WebSearch, WebFetch, mcp__exa__web_search_exa, mcp__exa__get_code_context_exa, Skill, mcp__chrome-devtools__*
 ---
+
+## Entry points
+
+- **Agent session:** Open this agent file manually in a new chat — context from this file + your main-session prompt.
+- **Task dispatch:** Run `python ./.trellis/scripts/generate_dispatch_prompt.py --agent research` → pass stdout as `Task(..., prompt=...)` — context from the Layer 2 prompt.
+
+## Context source
+
+- **Layer 2 prompt = PRIMARY (guaranteed)** — always generate via CLI before `Task(trellis-research)`.
+- **Hook `additional_context` = best-effort only** — Cursor #158452: not guaranteed to reach the model; optimization / fallback only.
+
 # Research Agent
 
 You are the Research Agent in the Trellis workflow.
@@ -55,6 +66,24 @@ Classify: internal / external / mixed. Determine scope (global / specific direct
 
 Run independent searches in parallel (Glob + Grep + smart-search CLI for external topics) for efficiency.
 
+#### External search — provider relevance caveats
+
+- **Context7** and generic third-party library docs are often **irrelevant** to Trellis/Cursor platform questions. Prefer **Cursor / Cursor++ official documentation**, `docs.cursor.com`, and **local `.trellis/spec/`** before trusting Context7 hits.
+- Every smart-search result you persist must **label the provider source** (e.g. `exa`, `context7`, `cursor-docs`, `tavily`) in the research file — in frontmatter or per bullet — so downstream check/finish can audit provenance.
+- Trellis harness facts: `./.trellis/scripts/run_smart_search.py` writes manifests under `{TASK}/research/smart-search/<run-id>/`; scored pack output (when built) is `{TASK}/research/retrieval-pack-latest.json`.
+
+#### External search — manual query refinement
+
+When the first smart-search pass returns irrelevant results, **refine before falling back** to Cursor web tools:
+
+1. Add site scope: `site:cursor.com`, `site:docs.cursor.com`, or `site:github.com/cursor-ide`
+2. Add product scope: `+Trellis`, `+cursor-trellis`, or the exact API/hook name
+3. Switch route: `--intent official-source --include-domain cursor.com` or `--intent docs` for API reference
+4. Narrow time or topic: shorter query, version number, or feature name from local spec
+5. Re-run: `python ./.trellis/scripts/run_smart_search.py "<refined query>" --intent deep-research --json`
+
+Only use Cursor WebSearch/WebFetch when smart-search is unavailable (`not_configured` / `failed` / timeout) — then persist with `source: cursor-web-fallback`.
+
 ### Step 4: Persist Each Topic
 
 For each distinct research topic, Write a markdown file at `{TASK_DIR}/research/<topic-slug>.md`. Use the File Format below.

package/dist/templates/cursor/fixtures/expected-rules.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Expected Cursor rules manifest for validate-rules hard gate.
+ * Update alongside rule content changes in templates/cursor/rules/.
+ */
+export interface ExpectedRule {
+    /** Filename including .mdc extension, e.g. "trellis-triage.mdc" */
+    filename: string;
+    /** Substrings that must appear in rule body (case-sensitive) */
+    requiredSections: string[];
+    /** Minimum byte length of normalized rule content */
+    minBytes: number;
+}
+export declare const expectedRules: ExpectedRule[];
+//# sourceMappingURL=expected-rules.d.ts.map

package/dist/templates/cursor/fixtures/expected-rules.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"expected-rules.d.ts","sourceRoot":"","sources":["../../../../src/templates/cursor/fixtures/expected-rules.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,WAAW,YAAY;IAC3B,mEAAmE;IACnE,QAAQ,EAAE,MAAM,CAAC;IACjB,gEAAgE;IAChE,gBAAgB,EAAE,MAAM,EAAE,CAAC;IAC3B,qDAAqD;IACrD,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,eAAO,MAAM,aAAa,EAAE,YAAY,EAoBvC,CAAC"}

package/dist/templates/cursor/fixtures/expected-rules.js

@@ -0,0 +1,26 @@
+/**
+ * Expected Cursor rules manifest for validate-rules hard gate.
+ * Update alongside rule content changes in templates/cursor/rules/.
+ */
+export const expectedRules = [
+    {
+        filename: "trellis-triage.mdc",
+        requiredSections: [
+            "Decision tree",
+            "Classification mark",
+            "Consent gate",
+        ],
+        minBytes: 500,
+    },
+    {
+        filename: "trellis-subagent-dispatch.mdc",
+        requiredSections: ["Layer 2", "generate_dispatch_prompt", "CLI"],
+        minBytes: 400,
+    },
+    {
+        filename: "retrieval-routing.mdc",
+        requiredSections: ["Native", "BYOK", "codegraph", "smart-search"],
+        minBytes: 600,
+    },
+];
+//# sourceMappingURL=expected-rules.js.map

package/dist/templates/cursor/fixtures/expected-rules.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"expected-rules.js","sourceRoot":"","sources":["../../../../src/templates/cursor/fixtures/expected-rules.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAWH,MAAM,CAAC,MAAM,aAAa,GAAmB;IAC3C;QACE,QAAQ,EAAE,oBAAoB;QAC9B,gBAAgB,EAAE;YAChB,eAAe;YACf,qBAAqB;YACrB,cAAc;SACf;QACD,QAAQ,EAAE,GAAG;KACd;IACD;QACE,QAAQ,EAAE,+BAA+B;QACzC,gBAAgB,EAAE,CAAC,SAAS,EAAE,0BAA0B,EAAE,KAAK,CAAC;QAChE,QAAQ,EAAE,GAAG;KACd;IACD;QACE,QAAQ,EAAE,uBAAuB;QACjC,gBAAgB,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,WAAW,EAAE,cAAc,CAAC;QACjE,QAAQ,EAAE,GAAG;KACd;CACF,CAAC"}

package/dist/templates/cursor/rules/trellis-subagent-dispatch.mdc

@@ -0,0 +1,34 @@
+---
+description: "Trellis subagent dispatch — generate dispatch prompt via CLI before Task tool (hook injection is broken in Cursor 3.8.22; this rule is the D-1 workaround)"
+alwaysApply: true
+---
+
+# Trellis Subagent Dispatch (CLI Layer 2 — MANDATORY)
+
+**CLI Layer 2 is the primary Cursor path.** The `preToolUse` hook does NOT fire for the Task tool in Cursor 3.8.22. Agent definition body does NOT enter subagent system prompt. The ONLY reliable context channel is the `Task` tool's `prompt` parameter.
+
+## Rule
+
+Before calling `Task(subagent_type="trellis-research|trellis-implement|trellis-check", ...)` you MUST:
+
+1. Generate a complete dispatch prompt via CLI:
+
+   ```powershell
+   python ./.trellis/scripts/generate_dispatch_prompt.py --agent <research|implement|check> --task "<task-path>" --repo-root "<repo-root>"
+   ```
+
+2. Use the CLI output as the `prompt` parameter value for `Task(...)`.
+
+3. Append any additional user instructions AFTER the generated prompt, separated by `\n\n---\n\n`.
+
+## Why
+
+The generated prompt carries role identity ("You are the Trellis Research/Implement/Check Agent"), write scope constraints, recursion guard, and dynamic context (prd.md, design.md, implement.md, spec tree, jsonl files). Without this, the subagent receives only a bare user instruction with no Trellis context.
+
+## Auto-detection
+
+If `--task` is omitted, the script resolves the currently selected task. If `--repo-root` is omitted, it auto-detects via `.trellis` or `.git` upward search.
+
+## Exception
+
+This rule does NOT apply to `generalPurpose`, `explore`, `shell`, or other non-Trellis subagent types. Only `trellis-research`, `trellis-implement`, `trellis-check` require CLI-generated prompts.

package/dist/templates/markdown/spec/guides/execution-strategy.md.txt

@@ -1,43 +1,43 @@
-# 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.
-
----
-
-## Two orthogonal dimensions
-
-| Field | Question |
-| --- | --- |
-| `execution_mode` | **Who** implements and checks? (`inline` main session, `worker` trellis-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 ./.trellis/scripts/task.py suggest-execution-strategy <task-dir>
-python3 ./.trellis/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 `.trellis/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
-
+# 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.
+
+---
+
+## Two orthogonal dimensions
+
+| Field | Question |
+| --- | --- |
+| `execution_mode` | **Who** implements and checks? (`inline` main session, `worker` trellis-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 ./.trellis/scripts/task.py suggest-execution-strategy <task-dir>
+python3 ./.trellis/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 `.trellis/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 `trellis-implement` / `trellis-check` only when `execution_mode: worker`.

package/dist/templates/trellis/config/execution-strategy-rules.json

@@ -1,31 +1,31 @@
-{
-  "version": 1,
-  "doc_only_capabilities": [
-    "markdown-documentation"
-  ],
-  "code_capabilities": [
-    "cli-templates",
-    "python-task-scripts",
-    "vitest-integration",
-    "typescript",
-    "python"
-  ],
-  "code_path_segments": [
-    "src",
-    "packages",
-    "scripts",
-    "lib"
-  ],
-  "pair_warnings": [
-    {
-      "execution_mode": "worker",
-      "isolation": "git-worktree",
-      "message": "worker usually runs in main-worktree; git-worktree is rare for trellis-implement"
-    },
-    {
-      "execution_mode": "inline",
-      "isolation": "git-worktree",
-      "message": "inline + git-worktree is unusual; consider child-task if isolation is intentional"
-    }
-  ]
+{
+  "version": 1,
+  "doc_only_capabilities": [
+    "markdown-documentation"
+  ],
+  "code_capabilities": [
+    "cli-templates",
+    "python-task-scripts",
+    "vitest-integration",
+    "typescript",
+    "python"
+  ],
+  "code_path_segments": [
+    "src",
+    "packages",
+    "scripts",
+    "lib"
+  ],
+  "pair_warnings": [
+    {
+      "execution_mode": "worker",
+      "isolation": "git-worktree",
+      "message": "worker usually runs in main-worktree; git-worktree is rare for trellis-implement"
+    },
+    {
+      "execution_mode": "inline",
+      "isolation": "git-worktree",
+      "message": "inline + git-worktree is unusual; consider child-task if isolation is intentional"
+    }
+  ]
 }