@blxzer/cursor-trellis 0.4.1 → 0.4.2

package/dist/templates/markdown/spec/guides/cursor-trellis-release-coexistence-guide.md.txt

@@ -1,166 +0,0 @@
-# cursor-trellis Release & Coexistence Guide
-
-> **Audience**: Maintainers and agents working on `@blxzer/cursor-trellis` in `D:\MyHarness\cursor-trellis`.  
-> **Scope**: npm publish runbook, git tag naming (`cstl-v*`), and upstream Trellis coexistence semantics (0.3.2+).
-
----
-
-## 1. npm publish runbook (mandatory)
-
-cursor-trellis ships **two** npm packages at the **same version**:
-
-| Package | Role |
-| --- | --- |
-| `@blxzer/cursor-trellis-core` | SDK (must publish **first**) |
-| `@blxzer/cursor-trellis` | CLI (depends on core) |
-
-### Do
-
-```bash
-cd D:\MyHarness\cursor-trellis\packages\cli
-
-# 1. Version parity (cli + core package.json must match)
-cd ../.. && pnpm release:check
-
-# 2. Optional: dry-run pack shape (rewrites workspace:* in tarball)
-node packages/cli/scripts/publish-packages.js --dry-run
-
-# 3. Publish both packages in dependency order
-node packages/cli/scripts/publish-packages.js
-
-# 4. Verify registry visibility
-node packages/cli/scripts/release-preflight.js verify-npm --package all
-```
-
-`publish-packages.js` uses **`pnpm publish`** (not bare `npm publish`). pnpm rewrites `workspace:*` dependencies to the resolved semver (e.g. `"@blxzer/cursor-trellis-core": "0.3.3"`). Bare `npm publish` leaves `workspace:*` in the tarball → **`EUNSUPPORTEDPROTOCOL`** on install.
-
-### Do not
-
-- **`npm publish`** from `packages/cli` alone (0.3.1 incident: cli tarball had `workspace:*`, core was missing).
-- Publish cli before core (cli install fails with ETARGET until core exists).
-- Skip `prepublishOnly` (runs test + build + copy-release-assets on cli).
-
-### Preflight commands
-
-| Command | Purpose |
-| --- | --- |
-| `release-preflight.js check-versions` | cli/core version match |
-| `release-preflight.js verify-packed-cli` | Packed cli resolves core to exact semver (not `workspace:*`) |
-| `release-preflight.js verify-npm` | Post-publish registry check |
-| `release-preflight.js publish-plan` | Idempotent CI plan (skip already-published versions) |
-
-### Withdrawn / deprecated versions
-
-- **0.3.1 cli**: withdrawn (unpublish); use **0.3.2+**.
-- **0.3.1 core**: cannot unpublish (npm policy); **`npm deprecate`** applied — use `@latest`.
-
----
-
-## 2. Git tags (`cstl-v*` prefix)
-
-This repo shares git history with legacy `@blxzer/trellis` (1.x). Old tags `v0.3.x`–`v0.6.x` point at **trellis** commits, not cursor-trellis releases.
-
-| Tag pattern | Product | Example |
-| --- | --- | --- |
-| `v*` (legacy) | `@blxzer/trellis` | `v0.3.2` @ 2026-03 trellis commit |
-| **`cstl-v*`** | `@blxzer/cursor-trellis` | `cstl-v0.3.2` @ cursor-trellis release commit |
-
-`packages/cli/scripts/release.js` tags releases as **`cstl-v${version}`** (since 0.3.2 tag-hygiene commit).
-
-`release-preflight tagVersionFromEnv` extracts semver from tag suffix (`cstl-v0.3.2` → `0.3.2`).
-
-**CI publish workflow** (`.github/workflows/publish.yml`): triggers on `push.tags: cstl-v*`. Requires repo secret `NPM_TOKEN`.
-
-Do **not** delete legacy `v*` tags — they are historical trellis releases.
-
----
-
-## 3. Coexistence with upstream mindfold-ai/Trellis
-
-**Product decision**: Both are workflow frameworks. **Cursor configuration belongs to cursor-trellis**. Upstream Trellis keeps `.trellis/` and non-Cursor platform dirs; cursor-trellis uses `.cstl/` + `.cursor/cstl-*`.
-
-### Scenario matrix
-
-| Scenario | User state | Action |
-| --- | --- | --- |
-| 1 Pure cstl | Only cursor-trellis (legacy `.trellis/` runtime) | `cstl update --migrate` → rename `.trellis/` → `.cstl/` |
-| 2 Coexistence | Upstream `.trellis/` + wants Cursor cstl | `cstl init --cursor` → creates `.cstl/`, **takes over `.cursor/`**, AGENTS dual-block |
-| 3 Fresh | Never used either | `cstl init --cursor` → `.cstl/` only |
-
-### `cstl init` coexistence mode
-
-When `.trellis/` exists and `.cstl/` does not:
-
-1. Creates `.cstl/` (does not touch `.trellis/`).
-2. **Force-writes** `.cursor/` (hooks, rules, commands) even under `-y`.
-3. **AGENTS.md dual-block**: preserves `<!-- TRELLIS:START -->`, adds/refreshes `<!-- CSTL:START -->` (`insertCstlManagedBlock`).
-4. Prints banner: do **not** run `cstl update --migrate` (would rename upstream `.trellis/`).
-
-### Migrate gate (`assessCstlDirectoryMigrate`)
-
-Conservative by default for `.trellis/` → `.cstl/` rename:
-
-| Signal | Meaning |
-| --- | --- |
-| F1 | `.cursor/commands/cstl-*.md` |
-| F2 | `.cursor/rules/cstl-triage.mdc` |
-| F3 | `.trellis/scripts/common/cli_adapter.py` contains `cstl` |
-| U1 | `.claude/agents/trellis-implement.md` |
-| U2 | Non-Cursor platform `trellis-*` agents/skills |
-| U4 | `.cursor/commands/trellis-*.md` without cstl fingerprint |
-
-- No F fingerprint → **abort** (protect scenario 2).
-- F + U mixed → **abort** (manual split).
-- Escape: `cstl update --force-cstl-migrate`.
-
-### AGENTS.md hash tracking (block-level)
-
-`.template-hashes.json` stores **CSTL block hash only** for `AGENTS.md`, not the whole file. Upstream edits to TRELLIS block or user content outside CSTL block do **not** trigger "modified" on `cstl update`.
-
-Implementation: `template-hash.ts` → `hashContentForPath` + `extractBlock(CSTL:START/END)`.
-
-### `cstl uninstall` in coexistence repos
-
-- Strips **CSTL block only** (`removeCstlManagedBlock`); keeps TRELLIS block + user content.
-- If file was only the CSTL block → deletes `AGENTS.md`.
-- Does **not** restore upstream `.cursor/` files overwritten during init (by design: cstl owned Cursor).
-
----
-
-## 4. Post-release dogfood checklist
-
-```bash
-npm install -g @blxzer/cursor-trellis@latest
-cstl --version
-
-# Each dogfood project (no --migrate unless upgrading from pre-0.3.1):
-cd <project>
-cstl update --skip-readiness --skip-all
-# Confirm .cstl/.version matches npm latest
-```
-
-Sandbox smoke (from empty dir):
-
-```bash
-npm init -y && npm install @blxzer/cursor-trellis@latest
-npx cstl init --yes --skip-readiness --cursor
-```
-
----
-
-## 5. Related files (source of truth)
-
-| Topic | Path |
-| --- | --- |
-| Publish orchestration | `cursor-trellis/packages/cli/scripts/publish-packages.js` |
-| Release preflight | `cursor-trellis/packages/cli/scripts/release-preflight.js` |
-| Tag prefix | `cursor-trellis/packages/cli/scripts/release.js` |
-| Coexistence init | `packages/cli/src/commands/init.ts` |
-| Migrate gate | `packages/cli/src/utils/workflow-ownership.ts` |
-| AGENTS helpers | `packages/cli/src/utils/agents-md.ts` |
-| Block-level hash | `packages/cli/src/utils/template-hash.ts` |
-| Uninstall strip | `packages/cli/src/commands/uninstall.ts` |
-
----
-
-**Last updated**: 2026-07-04 (0.3.3 follow-up: uninstall CSTL strip + block hash + this guide).

package/dist/templates/markdown/spec/guides/goal-release-regression-runbook.md.txt

@@ -1,132 +0,0 @@
-# Goal 发布回归 Runbook
-
-> **受众**：Root npm 闸、Parent 集成前自检、维护者。  
-> **范围**：`cstl goal` 回归 checklist — **不扩展 Goal 功能**，仅钉死 hardening 命令。  
-> **基线**：`cursor-trellis` `main`（A1/A2 合并后 tip）；harness 侧 `.cstl/spec/Trellis/framework/cstl-goal-*.md`。
-
----
-
-## 1. 发布门语义
-
-| 项 | 说明 |
-| --- | --- |
-| **用途** | npm 发布前 Goal 回归闸；Parent `verify.md` 可链接本页 |
-| **非目标** | 不新增 runner/worker 能力；不替代 [cursor-trellis release runbook](./cursor-trellis-release-coexistence-guide.md) |
-| **通过标准** | Mock 路径全绿（§2）；Live 路径（§3）为可选加分项 |
-| **零功能 diff** | 本闸仅文档与命令；**不得**附带 `cursor-trellis/packages/cli/src/goal/*` 语义变更 |
-
----
-
-## 2. Mock 路径（必须 — 无需 `CURSOR_API_KEY`）
-
-在 harness 根目录执行。CI / 新人 onboarding 至少跑完本节。
-
-### 2.1 全量 Goal 测试
-
-```powershell
-cd cursor-trellis/packages/cli
-pnpm test goal/
-```
-
-**期望：** 7 个 test files、32 tests 全部 PASS。
-
-### 2.2 Golden + 墙单元测试
-
-```powershell
-cd cursor-trellis/packages/cli
-pnpm exec vitest run test/goal/reviewer-golden.test.ts test/goal/walls.test.ts
-```
-
-**期望：**
-
-- `mis-allow gate is zero on hard-deny bucket` 通过
-- `walls.test.ts` 墙钟逻辑通过
-
-### 2.3 墙 smoke 脚本语法
-
-```powershell
-python -m py_compile .cstl/scripts/goal_wall_smoke.py
-```
-
-### 2.4 可选 — 墙钟 crash 可复现 smoke
-
-需已有 goal run 目录（`goal_id` 来自历史 hardening 或本地狗粮）：
-
-```powershell
-python ./.cstl/scripts/goal_wall_smoke.py <goal_id> --mode window --json
-```
-
-**期望：** JSON 中 `ok: true`；`audit.log` 含 `wall-clock reached`。
-
----
-
-## 3. Live 路径（可选 — 需要 `CURSOR_API_KEY`）
-
-仅当维护者显式同意 live SDK 狗粮时执行。Cursor Agent shell **默认不继承** User 级环境变量，须先加载：
-
-```powershell
-$env:CURSOR_API_KEY = [Environment]::GetEnvironmentVariable('CURSOR_API_KEY','User')
-```
-
-### 3.1 Preflight → Accept → Run
-
-```powershell
-cstl goal preflight --goal "..." --json
-cstl goal accept <goal_id>
-cstl goal run <goal_id> --max-steps 1 --json
-```
-
-CI 风格可用 mock worker（无需 live SDK）：
-
-```powershell
-cstl goal run <goal_id> --mock-worker --max-steps 1 --json
-```
-
-若全局 `cstl` 未 link 最新 dist，改用本地 CLI：
-
-```powershell
-node cursor-trellis/packages/cli/dist/cli/index.js goal preflight --goal "..." --json
-```
-
----
-
-## 4. 契约引用
-
-回归失败时对照合同，勿在发布闸中改语义：
-
-| 文档 | 路径 |
-| --- | --- |
-| cstl-goal 验收合同 | [`.cstl/spec/Trellis/framework/cstl-goal-contract.md`](../Trellis/framework/cstl-goal-contract.md) |
-| Action Packet | [`.cstl/spec/Trellis/framework/cstl-goal-action-packet.md`](../Trellis/framework/cstl-goal-action-packet.md) |
-| Golden 用例 | `cursor-trellis/packages/cli/test/fixtures/goal-reviewer-golden/cases.json` |
-
----
-
-## 5. SDK 残余风险（须诚实记录）
-
-| 来源 | 结论 |
-| --- | --- |
-| `@cursor/sdk` `Agent.prompt` | `sdk-client.ts` 包装为**单次** `Promise`，**无** mid-run cancel / abort 参数 |
-| Goal SDK worker | `worker.ts` 仅外层 `withTimeout(..., ctx.timeoutMs)` |
-| smart-search docs 探针（2026-08-07） | 未发现官方 mid-run cancel API — **按 timeout-only 风险处理** |
-
-**实践建议：**
-
-- Live 回归控制 `--max-steps` 与 wall 配置
-- 长步无法保证 turn 中途取消；超时后进程可能仍占用资源直至 Promise  settle
-- 无 key 环境一律用 `--mock-worker` 或 §2 Mock 路径
-
----
-
-## 6. 快速 Checklist
-
-- [ ] `pnpm test goal/` — 32 PASS
-- [ ] `reviewer-golden.test.ts` + `walls.test.ts` — PASS
-- [ ] `python -m py_compile .cstl/scripts/goal_wall_smoke.py` — OK
-- [ ] （可选）`goal_wall_smoke.py <goal_id> --mode window --json` — `ok: true`
-- [ ] （可选 live）`cstl goal preflight` / `accept` / `run --max-steps 1`
-- [ ] **无** `cursor-trellis/packages/cli/src/goal/*` 功能 diff
-
----
-
-**来源：** `08-06-cstl-p2-goal-hardening/verify.md` · Parent `08-07-cstl-parent-orch-visibility` §5.2