@blxzer/cursor-trellis 0.4.2 → 0.4.3

package/dist/templates/trellis/scripts/task.py

@@ -1,9 +1,14 @@
 #!/usr/bin/env python3
 # -*- coding: utf-8 -*-
 """
-Task Management Script.
+Thin Task shim over `cstl kernel --json`.
+
+Write-path commands (create / start-execution / record-gate / archive / patch
+via add-subtask and friends) submit a Kernel Command. Do not invent `cstl task`.
+Select / dashboard / jsonl / parent-status stay Python overlays.
 
 Usage:
+    python task.py kernel                      # stdin JSON → cstl kernel --json
     python task.py create "<title>" [--slug <name>] [--assignee <dev>] [--priority P0|P1|P2|P3] [--parent <dir>] [--package <pkg>]
     python task.py add-context <dir> <file> <path> [reason] # Add jsonl entry
     python task.py validate <dir>              # Validate jsonl files
@@ -39,6 +44,7 @@ Usage:
 from __future__ import annotations
 
 import argparse
+import json
 import sys
 from datetime import datetime, timezone
 from pathlib import Path
@@ -58,12 +64,22 @@ from common.active_task import (
     resolve_selected_task,
     set_selected_task,
 )
-from common.io import read_json, write_json
+from common.io import read_json
+from common.kernel_command import (
+    KernelCliNotFound,
+    KernelCommandError,
+    kernel_expected_revision,
+    kernel_record_gate,
+    kernel_start,
+    print_kernel_error,
+    run_kernel_command,
+)
 from common.task_dashboard import render_task_dashboard
 from common.cli_environment import optional_capability_note
 from common.task_gates import (
     BASELINE_GATE,
     build_reviewer_gate_record,
+    collect_kernel_projection_extras,
     read_strategy_contract,
     start_execution_repair_hints,
     validate_start_execution,
@@ -141,6 +157,27 @@ def _resolve_existing_task(task_input: str, repo_root):
     return full_path
 
 
+def cmd_kernel(args: argparse.Namespace) -> int:
+    """Forward one JSON object on stdin to `cstl kernel --json`."""
+    _ = args
+    raw = sys.stdin.read()
+    try:
+        payload = json.loads(raw) if raw.strip() else {}
+    except json.JSONDecodeError as err:
+        print(colored(f"Error: stdin is not JSON: {err}", Colors.RED), file=sys.stderr)
+        return 1
+    if not isinstance(payload, dict):
+        print(colored("Error: Kernel request must be a JSON object", Colors.RED), file=sys.stderr)
+        return 1
+    try:
+        result = run_kernel_command(payload, cwd=get_repo_root())
+    except (KernelCliNotFound, KernelCommandError) as err:
+        print_kernel_error(err)
+        return 1
+    print(json.dumps(result, ensure_ascii=False))
+    return 0
+
+
 def cmd_dashboard(args: argparse.Namespace) -> int:
     """Show Task Dashboard without mutating selection or status."""
     _ = args
@@ -348,8 +385,24 @@ def cmd_start_execution(args: argparse.Namespace) -> int:
     }
     if task_data.get("status") == "planning":
         task_data["status"] = "in_progress"
-    if not write_json(task_json_path, task_data):
-        print(colored("Error: failed to write task.json", Colors.RED), file=sys.stderr)
+
+    extras = collect_kernel_projection_extras(task_data)
+    try:
+        expected = kernel_expected_revision(task_dir)
+        kernel_start(
+            task_dir,
+            task_data,
+            extras,
+            expected_revision=expected,
+            actor="task.py start-execution --approved",
+            idempotency_key=(
+                f"start:{task_data.get('id') or task_dir.name}:"
+                f"{task_data['execution_approval']['approved_at']}"
+            ),
+            evidence="task.py start-execution --approved",
+        )
+    except (KernelCliNotFound, KernelCommandError) as err:
+        print_kernel_error(err)
         return 1
 
     print(colored(f"✓ Execution approved for: {_repo_relative(task_dir, repo_root)}", Colors.GREEN))
@@ -394,8 +447,25 @@ def cmd_record_gate(args: argparse.Namespace) -> int:
 
     assert record is not None
     write_gate_record(task_data, args.transition, args.gate, record)
-    if not write_json(task_json_path, task_data):
-        print(colored("Error: failed to write task.json", Colors.RED), file=sys.stderr)
+    extras = collect_kernel_projection_extras(task_data)
+    try:
+        expected = kernel_expected_revision(task_dir)
+        kernel_record_gate(
+            task_dir,
+            expected_revision=expected,
+            actor="task.py record-gate",
+            idempotency_key=(
+                f"gate:{args.transition}:{args.gate}:"
+                f"{record.get('contract_fingerprint') or record.get('evidence')}"
+            ),
+            transition=args.transition,
+            gate=args.gate,
+            record=record,
+            extras=extras,
+            evidence=str(record.get("evidence") or args.evidence),
+        )
+    except (KernelCliNotFound, KernelCommandError) as err:
+        print_kernel_error(err)
         return 1
 
     print(colored(f"✓ Recorded gate: {args.transition}/{args.gate} = {record['result']}", Colors.GREEN))
@@ -656,11 +726,16 @@ def main() -> int:
         return 2
 
     parser = argparse.ArgumentParser(
-        description="Task Management Script",
+        description="Thin Task shim over cstl kernel --json",
         formatter_class=argparse.RawDescriptionHelpFormatter,
     )
     subparsers = parser.add_subparsers(dest="command", help="Commands")
 
+    subparsers.add_parser(
+        "kernel",
+        help="Forward stdin JSON to `cstl kernel --json` (do not invent cstl task)",
+    )
+
     # create
     p_create = subparsers.add_parser("create", help="Create new task")
     p_create.add_argument("title", help="Task title")
@@ -989,6 +1064,7 @@ def main() -> int:
         return 1
 
     commands = {
+        "kernel": cmd_kernel,
         "create": cmd_create,
         "add-context": cmd_add_context,
         "validate": cmd_validate,

package/dist/templates/trellis/workflow.md

@@ -1,17 +1,22 @@
 # Development Workflow
 
+> **Human overview — not runtime SSOT.** This file is a copy-template reading guide for people. Gates, Rigor, Topology, and Task state are Kernel/`task.json` projections (`required_controls`, Topology, Event Bridge). Do not parse this document as the runtime program of record.
+
 ---
 
 ## Core Principles
 
-1. **Plan before code** — figure out what to do before you start
-2. **Specs injected, not remembered** — guidelines are injected via hook/skill, not recalled from memory
-3. **Persist everything** — research, decisions, and lessons all go to files; conversations get compacted, files don't
-4. **Incremental development** — one task at a time
-5. **Capture learnings** — after each task, review and write new knowledge back to spec
+1. **Parallel first** — when ≥2 independent units have isolatable write-sets, default to parallel; serial needs a written reason. Attention order is not a serial lock. Convention + review, not a new CLI gate. See Parallel-first below.
+2. **Plan before code** — figure out what to do before you start
+3. **Specs injected, not remembered** — guidelines are injected via hook/skill, not recalled from memory
+4. **Persist everything** — research, decisions, and lessons all go to files; conversations get compacted, files don't
+5. **Incremental development** — finish a slice before expanding; this is not a serial lock on independent units
+6. **Capture learnings** — after each task, review and write new knowledge back to spec
 
 **Session boundary** — Continue → clear → handoff (`cstl-handoff`, when the work needs to travel) → subagent → compact. A task directory's `handoff.md` is integration/delivery evidence, not a session handoff document.
 
+**Durable objectives** — Cursor official `/goal` (persistent in-session run). Not a Trellis task type, not Parent/Child, not `cstl-handoff`. Do **not** restore `cstl-goal`.
+
 ---
 
 ## Trellis System
@@ -110,7 +115,7 @@ python3 ./.cstl/scripts/get_context.py --mode retrieval-pack --json --input <evi
 
 **Retrieval daily guide:** `.cstl/framework/retrieval-daily-guide.md` — when to use rg, codegraph, fast-context-mcp, smart-search-cli (and Cursor web fallback), artifact/session memory, codebase router (suggest-only), and explicit retrieval-pack scoring.
 
-**Cursor subagent dispatch:** `.cstl/framework/cursor-subagent-policy.md` — `cstl-research` / `cstl-implement` / `cstl-check`; Parent child default **Task** `cstl-implement` from Parent session (`generate-child-prompt --mode subagent`). **Cursor++ BYOK:** per-type models via `.cstl/local/cursor2plus/` + user/project JSON maps (not committed slugs). **Native Cursor API:** frontmatter `model:` on agents still works. PRD Grill stays in the planning session (Read `.cstl/framework/prd-grill-frontier.md`), not a subagent. **Cursor++:** compatible v0.0.11+ (SubAgent readonly bug fixed).
+**Cursor subagent dispatch:** `.cstl/framework/cursor-subagent-policy.md` — `cstl-research` / `cstl-implement` / `cstl-check`; Parent child default **Task** `cstl-implement` from Parent session (`generate-child-prompt --mode subagent`). **Native Cursor API:** frontmatter `model:` on agents still works. PRD Grill stays in the planning session (Read `.cstl/framework/prd-grill-frontier.md`), not a subagent. Cursor++ / cstl-byok are **not** Native install surfaces (no command, skill, or init ask).
 
 ---
 
@@ -188,6 +193,65 @@ Classification mark (R2 — visible audit trail). Start your reply with one line
 
 Consent gate. After classifying into any mode that creates a task, ask the user for task-creation consent before creating any Trellis artifact. User approval to create a task is **not** approval to start implementation — planning still happens first. If the user declines a task for a simple request, skip Trellis for this session.
 
+### Personal Lite path (Open → Close)
+
+Personal Lite is the default runnable slice: **main Agent**, Definition / Evidence dual surfaces, **no Parent topology**, **no Git requirement**. Kernel phase names are internal; user-visible `planning` / `in_progress` / `completed` stay unchanged.
+
+| Step | Event / surface | Notes |
+| --- | --- | --- |
+| Open | Triage Outcome `No Task` or `Lite` | Event-style; do not require Parent. Full always-on tree stays for Full/Parent. |
+| Define | `prd.md` | Created on `task.py create`; fill Acceptance Criteria before Execute. |
+| Approve | `task.py start-execution --approved` | `--check` is CLI preflight only — it does **not** impersonate human approval. |
+| Execute | Main Agent | Do not force Subagent, worktree, or Parent. |
+| Verify | `verify.md` | Required Evidence. Placeholder / fake-green still fails Close. |
+| Close | `task.py archive` | Writes Outcome. Missing `.git` or `task-map.md` / `children[]` must not fail Lite Close. Physical directory retention is not a completion condition. |
+
+Context: `python3 ./.cstl/scripts/get_context.py --mode lite --json` assembles a **budgeted** pack (Definition / Evidence / thin exact-semantic-structural-external router). Unactivated On-demand (Parent / VCS / retrieval-extended) and a full `workflow.md` dump are refused rather than silently stuffed in.
+
+Low interaction: no hard-Risk Lite does not add extra mechanical confirmation gates. The Agent retrieves repo facts; the user decides intent, risk acceptance, and the Approve/Close gates above.
+
+### Full Quality path (conditional Design + ledger + graded Check)
+
+Full keeps the same user-visible `planning` / `in_progress` / `completed` names. Kernel persists resolved `required_controls`; **do not infer Rigor from whether `design.md` happens to exist**.
+
+| Role | Default surface | Required? |
+| --- | --- | --- |
+| Definition | `prd.md` | Yes |
+| Execution Contract | `implement.md` (strategy contract) | Yes |
+| Verification Plan | `implement.md` | Yes |
+| Evidence | `verify.md` (human projection) | Yes |
+| Independent Check | `self-review` or `true-independent` verdict | Yes for Full; **not** for Lite |
+| Design | `design.md` | Only when Risk/Policy or `verification_profile: architecture` requires it |
+
+- `verification_profile` expands to gates; Kernel stores the final `required_controls`.
+- AC → Evidence Ledger is machine-readable (`ac_evidence_ledger` on `task.json`); `verify.md` is the human projection. Missing mapping, placeholder evidence, or a stale fingerprint after definition/code change blocks Close.
+- Independent Check is **read-only**. Repair returns to Execute. Platform without a reliable independent worker must label `self-review` and must not claim independent. `true-independent` without a worker **blocks**.
+- Lite Open→Close is unchanged and does not gain Independent Check from this path.
+
+### On-demand and Topology (Stage 5)
+
+Rigor (`lite` / `full`) and Topology (`single` / `parent-child`) are orthogonal. Parent is an orchestration topology, not a higher quality grade. Kernel extras (`topology`, `dependency_graph`, `ondemand_modules`) are the graph authority; `task-map.md` and the dashboard are projections. Prefer Cursor native parallel (P18); Trellis does not schedule workers.
+
+- Single-parent tree: a Task has at most one Parent. A second Parent is rejected.
+- Decompose only proposes slices. Child directories are not created until the user confirms.
+- Capture Candidate writes a pool candidate. It does not create a Task.
+- Typed edges: `requires` blocks readiness; `advisory` does not. Existing `depends_on` expands to `requires`.
+- Integration authority stays with the Parent. A Child must not `integrate-child`.
+- On-demand modules (Parent-Child, VCS, Memory, Retention, …) are registered and dormant. First legal trigger activates them and is auditable. Lite Single does not force Parent / VCS / Memory / Retention into the resident pack.
+- `integration-handoff` is owned by Parent-Child. `session-transfer` is a separate owner.
+- Missing lifecycle slots still block start. Missing Profile-required On-demand is `degraded`, not fake-green. Physical Retention does not change Close Outcome.
+- User-visible `planning` / `in_progress` / `completed` names stay unchanged.
+
+### Adapter and Middleware (Stage 6)
+
+Cursor Adapter stays thin: a generic Event Bridge, one Bootstrap rule, and a short AGENTS pointer. Modules subscribe to standard hook events; an unsubscribed module must not fail the hook. Baseline capability routing is only `exact` / `semantic` / `structural` / `external`.
+
+- smart-search is an independent `external-knowledge` Middleware Provider. CSTL holds capability, readiness, compatibility range, and evidence pointers — not the Provider implementation.
+- Missing or failed Provider marks Profile `degraded`. Tasks that do not need external knowledge may Open→Close. Tasks that require it block, or degrade when Policy says so. Platform native Web is a downgrade, not an equivalent.
+- codegraph and fast-context are Optional. They are not default always-on and are not forced into the install surface.
+- Native SSOT has no Cursor++ / cstl-byok live entry. Environment probe fields may remain.
+- Do not rewrite smart-search or codegraph here. Do not invent a Trellis scheduler.
+
 Selected-task continuity. When a `selected_task` already exists, do not rerun global classification on every follow-up; continue inside the selected task unless a strong conflict exists (explicit exit/switch/create language, out-of-scope request, different artifact/archive target, new independent deliverable, contract-changing request, or evidence pollution risk).
 
 Review-pool boundary. In-session requests that are clear and directly actionable go straight to Lite / Full / Parent task creation and do **not** enter the pool (`.cstl/pool/`). Ideas, directions, gaps, or unformed thoughts go into the pool. Only `accepted` pool entries may be turned into tasks via `task.py create`. The pool is a candidate queue; a Task is a commitment. See `.cstl/pool/README.md` for the full state machine and role split. Pool entry ↔ task links and pool/plan validation are maintained via the pool CLI: `python3 ./.cstl/scripts/pool.py --help` (link/unlink/validate/plan-check/show). Choosing the next item: treat `plan.md` closed/mainline sections as authoritative → item status → `task.py list` → ask the user; landed items/mechanisms must leave fog (discipline in `.cstl/pool/README.md` 「下一项怎么选 + fog 卫生」).
@@ -201,7 +265,7 @@ Classify by risk and persistence, not raw effort size. A short change to durable
 | No Task | Conversation, status, explanation, read-only lookup, or a tiny one-turn action with no durable project change. | explain / status / lookup / read-only / one-liner | None. No archive unless upgraded. |
 | Micro-Grill | The user needs focused clarification, decision pressure, or a small requirement interrogation before deciding whether work exists. | small + underspecified / "depends" / needs clarification / decision tree first | Usually none. Upgrade before durable edits, validation, gates, or archive evidence. |
 | Lite Task | Low-risk durable work with narrow scope, local validation, and no shared contract change. | low-risk / single file / local validation / no contract / narrow scope | `task.json`, `prd.md`, `verify.md`, and archive evidence. |
-| Full Task | Durable code, template, runtime, workflow, or cross-file behavior where design, execution strategy, validation, or reviewer gates matter. | cross-file / framework semantics / contract change / template / runtime / workflow / multi-file behavior | `prd.md`, `design.md`, `implement.md`, `verify.md`, Development Strategy Contract, `verification_profile`, `quality_gates`, and archive evidence. |
+| Full Task | Durable code, template, runtime, workflow, or cross-file behavior where design, execution strategy, validation, or reviewer gates matter. | cross-file / framework semantics / contract change / template / runtime / workflow / multi-file behavior | `prd.md`, `implement.md`, `verify.md`, Execution/Verification contract, `required_controls`, AC ledger, Independent Check; `design.md` only when Risk/Policy requires it |
 | Parent Task / Child Tasks | One request contains independent deliverables, staged execution, parallel execution, or final integration authority that must be owned by a Parent. | multiple independent deliverables / staged / parallel / integration authority | Parent `task-map.md`, Child task artifacts, Child handoff evidence, Parent final integration evidence. |
 
 Default Trellis framework semantics, task model, platform adapters, MCP/capability setup, runtime integration, retrieval/graph tooling, Parent/Child orchestration, and quality-gate work to Full Task or higher.
@@ -227,16 +291,12 @@ Before executing an upgrade that creates artifacts, changes task mode, adds gate
 | No selected task + need dashboard | `cstl-start` |
 | Selected task + resume step | `cstl-continue` |
 | Planning / PRD | Read `.cstl/framework/prd-grill-frontier.md` (PRD Grill discipline; full body in the bundled brainstorm skill) |
-| Parent with parallel children | `generate-child-prompt --mode subagent`; writable Agent; see `.cstl/framework/cursor-subagent-policy.md` |
-
-### Goal runtime (not a Task Ladder type)
-
-**Goal** here means the **CLI subsystem** `cstl goal` (preflight → accept → run / pause / status / review), **not** a Task Ladder type and **not** Parent/Child orchestration. When the user says "use goal", run or suggest `cstl goal status` / `cstl goal preflight …` in the project terminal — do **not** create a "goal" task or map it to `add-subtask` / Parent-only planning. Default Cursor install has **no** `/cstl-goal` slash command (dogfood/extension only). See the AGENTS.md Invocation map.
+| Parent with parallel children | Prefer Multitask / `Task` parallel (serial needs `serial_reason`); `generate-child-prompt --mode subagent`; see `cursor-native-modes-guide.md` |
 
 ### Cursor native modes (Prefer — don't replace)
 
 Full map: `.cstl/framework/cursor-native-modes-guide.md` · per-turn slim rule: `.cursor/rules/cstl-cursor-modes.mdc`.  
-Task-driven: try callable native first (`SwitchMode` plan/agent, Multitask/`Task` when useful); **quiet cstl spine fallback** when not — no user-facing “不适配 mode” list.
+Task-driven: try callable native first (`SwitchMode` plan/agent; Multitask/`Task` **by default** when ≥2 independent units); **quiet cstl spine fallback** when not — no user-facing “不适配 mode” list.
 
 | Situation | Prefer Cursor mode | Trellis phase / note |
 | --- | --- | --- |
@@ -244,7 +304,7 @@ Task-driven: try callable native first (`SwitchMode` plan/agent, Multitask/`Task
 | Scope / design before code | **Plan** (`SwitchMode(plan)` when useful) | Phase 1; artifacts → `prd.md` / `design.md` / `implement.md` |
 | Approved build / verify | **Agent** | Phase 2–3; `execution_mode` contract |
 | Repeat failure / runtime debug | **Debug** when reachable | Evidence → `verify.md`; loops → `cstl-break-loop` |
-| Independent Parent children (post-approval) | **Multitask** / Build in Parallel when useful | Explicit task path per worker; Parent integrates |
+| Independent Parent children (post-approval) | **Multitask** / Build in Parallel **by default** when ≥2 independent units | Explicit task path per worker; serial needs `serial_reason`; Parent integrates |
 
 Details: archived `06-15-child-phase3-task-ladder` → `research/task-ladder-iteration.md`.
 
@@ -252,10 +312,10 @@ Details: archived `06-15-child-phase3-task-ladder` → `research/task-ladder-ite
 
 - `prd.md` — requirements, constraints, and acceptance criteria. Do not put technical design or execution checklists here.
 - `design.md` — technical design for complex tasks: boundaries, contracts, data flow, tradeoffs, compatibility, rollout / rollback shape.
-- `implement.md` — execution plan for complex tasks: ordered checklist, Development Strategy Contract, validation commands, review gates, and rollback points.
+- `implement.md` — execution plan for complex tasks: ordered checklist, Development Strategy Contract, validation commands, review gates, and rollback points. Parent / Full Task fan-out also declare parallel-first fields (可并行组 / 合并点 / 冲突面 / `serial_reason`) — see Parallel-first above and `.cstl/framework/parallel-first-execution.md`.
 - `implement.jsonl` / `check.jsonl` — spec and research manifests for sub-agent context. They do not replace `implement.md`.
-- `verification_profile` / `quality_gates` — gate policy belongs in task artifacts and `task.json`; `task.json.quality_gate_results` is compact machine-checkable state, not human review prose.
-- Lightweight tasks may be PRD-only. Complex tasks must have `prd.md`, `design.md`, and `implement.md` before `task.py start-execution --check`.
+- `verification_profile` / `quality_gates` — gate policy belongs in task artifacts and `task.json`; Kernel persists resolved `required_controls`. `task.json.quality_gate_results` is compact machine-checkable state, not human review prose. `ac_evidence_ledger` is the machine AC → Evidence map; `verify.md` is the human projection.
+- Lightweight tasks may be PRD-only. Full tasks need Definition + Execution/Verification contract (`implement.md` default) before `task.py start-execution --check`. Design is required only when Risk/Policy or `verification_profile: architecture` says so — do not treat a leftover `design.md` as Full.
 - `start-execution` planning gates (`requirements-review`, `architecture-review` when enabled) auto-record on `--approved` when artifacts pass CLI checks; use `record-gate` only as a manual override.
 
 ### Parent / Child Task Trees
@@ -264,6 +324,24 @@ Use a parent task when one user request contains several independently verifiabl
 
 Use child tasks for deliverables that can be planned, implemented, checked, and archived independently. Ordering between deliverables is an explicit declaration, not an implicit system: child-level ordering lives in the Parent `task-map.md` `children[].depends_on`, and task-level ordering in task.json `depends_on` (`task.py set-deps <task> <dep...>`). By default these declarations are soft hints only — the dashboard and `start-execution --check` show unmet / dangling / cyclic dependencies as warnings and do not block a transition (a task may opt into hard gates with `depends_mode: block`, see Task dependencies below); `depends_on` declares ordering, it does not schedule work. Keep each child's acceptance criteria testable on its own, and keep the Parent as the integration authority.
 
+### Parallel-first execution
+
+This is a **product** principle, not only an execution contract. It applies to the review pool, development-plan batches, Parent/Full fan-out, and independent middleware / protocol / release tracks. Planning declares parallel structure; **Cursor native** runs it. Trellis does **not** ship a parallel scheduler or a Multitask replacement. Field map: `.cstl/framework/parallel-first-execution.md`.
+
+**Does not apply:** Lite / single-file work; write-sets that cannot isolate; HITL / `start-execution --approved` / reviewer / `integrate-child`.
+
+**Does not replace** the existing `serial_reason` list. v1 strength is convention + review call-out, **not** a CLI hard gate.
+
+| Layer | Duty |
+| --- | --- |
+| **Prefer** | Cursor Multitask / Build in Parallel / Agent `Task` parallel / native worktree. If it can run native, run native. |
+| **Adapt** | Parent still owns `integrate-child`. HITL, `start-execution --approved`, and reviewer gates stay **serial**. Every worker prompt includes explicit `.cstl/tasks/<dir>` — never rely on `selected_task`. |
+| **Own** | Contract only: default parallel; serial must write `serial_reason`; task-map / `implement.md` declare 可并行组 / 合并点 / 冲突面. No queue, no new CLI. |
+
+**Default parallel when** planning already has ≥2 independent units: Parent children with empty `depends_on`, or a Full task with explicit Task fan-out. Lite / single-file work is **not** forced into parallel agents.
+
+**Serial is an exception.** Write `serial_reason` as one of: shared write-set / HITL or reviewer gate / `depends_on` unmet / user asked serial / conflict surface cannot isolate.
+
 ### Task dependencies (Plan A / Plan B)
 
 **任务依赖（Plan A / Plan B）**：顺序须显式声明；默认（`warn`）仅 dashboard / `start-execution --check` 软提示（WARN），不挡门禁；可 opt-in `block` 在 mutation 点硬挡（见下）；不是调度器，也不替代 Parent 集成权威。
@@ -402,10 +480,11 @@ When a user request matches one of these intents inside a selected task, route f
 
 
 - Planning or unclear requirements -> **Prefer Plan** when designing scope; read `.cstl/framework/prd-grill-frontier.md` for PRD grill discipline (see `.cstl/framework/cursor-native-modes-guide.md`).
+- Creating or making a **behavioral/structural** change to a Trellis bundled, `blaze-skills`, or harness skill → **must** Read `cstl-skill-creator` (`SKILL.md` + `references/review-checklist.md`) and follow its workflow before editing `SKILL.md`. **Skip** for typo / pure link fixes. Internal skill, not a user slash command. **Does not apply** to Cursor product skills (e.g. `~/.cursor/skills-cursor/create-skill`). Paths: `.cstl/framework/internal-skills-cursor-reachability.md`.
 - Read-only questions with no durable change -> **Prefer Ask**; classify No Task; do not create artifacts without consent.
 - `in_progress` implementation/check -> **Agent** default; if contract `execution_mode: worker`, dispatch `cstl-implement` / `cstl-check`; if `inline`, main session; if `child-task`, Child/Parent orchestration.
 - Repeated debugging / runtime evidence -> **Prefer Debug**; load `cstl-break-loop` when the same issue recurred; persist evidence in `verify.md`.
-- Parent parallel independent children (after execution approval) -> **Multitask** / Build in Parallel with explicit `.cstl/tasks/<dir>` in each worker prompt; Parent retains integration authority.
+- Parent parallel independent children (after execution approval) -> **Multitask** / Build in Parallel **by default** (empty `depends_on`); each worker prompt has explicit `.cstl/tasks/<dir>`; serial needs `serial_reason`; Parent retains integration authority. HITL / gates / `integrate-child` stay serial.
 - Spec updates after learning decision -> `cstl-update-spec`.
 
 
@@ -646,6 +725,8 @@ Read `execution_mode` from the approved Development Strategy Contract in `implem
 | `worker` | Spawn **`cstl-implement`** (Cursor): after `start-execution --approved`, assemble dispatch prompt via CLI Layer 2, then `Task(subagent_type=cstl-implement, prompt=<assembled>)`. Do **not** rely on preToolUse hook alone — see `cursor-context-injection-guide.md`. Tell the spawned agent it is already `cstl-implement` and must not spawn another `cstl-implement` / `cstl-check`. |
 | `child-task` | Child worker session (or Parent `generate-child-prompt`); isolation per contract (`git-worktree` → `prepare-child-worktree` when applicable). |
 
+Independent Parent children (post-approval, empty `depends_on`): Prefer native parallel (Multitask / Build in Parallel / `Task` / worktree). Do **not** invent a Trellis scheduler. HITL, `start-execution --approved`, reviewer gates, and `integrate-child` stay serial (`merge_limit: 1`). Serial work requires `serial_reason` in the task-map / `implement.md` declaration. See Parallel-first above.
+
 Context for worker dispatch includes `implement.jsonl` references, `prd.md`, `design.md` if present, and `implement.md` if present.
 
 #### 2.2 Quality check `[required · repeatable]`
@@ -662,6 +743,7 @@ The check agent's job:
 - Fix implementation defects only when they stay inside the approved contract
 - Route requirement, design, contract, scope, gate, capability, runtime, Parent `contract_epoch`, or Child boundary defects to Return-to-Planning
 - Run lint and typecheck to verify
+- For **new or structurally changed** Trellis / blaze-skills / harness skills: `verify.md` should record that `cstl-skill-creator` workflow + review-checklist was followed (always-on convention, not a CLI gate). Typo / link-only and Cursor product skills are out of scope.
 
 
 

package/dist/utils/cursor-retrieval-env.d.ts

@@ -1,5 +1,6 @@
 /**
- * Detect Cursor Native vs Cursor++ BYOK for retrieval routing.
+ * Detect Cursor Native vs BYOK environment for retrieval routing.
+ * This is an environment probe, not a product install surface.
  * Mirrors templates/trellis/scripts/common/cursor_retrieval_env.py
  */
 export declare const ENV_NATIVE: "native";

package/dist/utils/cursor-retrieval-env.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cursor-retrieval-env.d.ts","sourceRoot":"","sources":["../../src/utils/cursor-retrieval-env.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAMH,eAAO,MAAM,UAAU,EAAG,QAAiB,CAAC;AAC5C,eAAO,MAAM,QAAQ,EAAG,MAAe,CAAC;AACxC,eAAO,MAAM,WAAW,EAAG,SAAkB,CAAC;AAE9C,MAAM,MAAM,kBAAkB,GAC1B,OAAO,UAAU,GACjB,OAAO,QAAQ,GACf,OAAO,WAAW,CAAC;AAEvB,MAAM,WAAW,sBAAsB;IACrC,GAAG,EAAE,kBAAkB,CAAC;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,kBAAkB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC9B,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,wBAAgB,WAAW,IAAI,MAAM,CAMpC;AAED,wBAAgB,4BAA4B,IAAI,sBAAsB,CA8CrE;AAED,wBAAgB,wBAAwB,IAAI,kBAAkB,CAU7D;AAED,wBAAgB,MAAM,CAAC,GAAG,CAAC,EAAE,kBAAkB,GAAG,IAAI,GAAG,OAAO,CAE/D;AAED,8FAA8F;AAC9F,wBAAgB,kBAAkB,CAAC,GAAG,CAAC,EAAE,kBAAkB,GAAG,IAAI,GAAG,OAAO,CAG3E;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,eAAe,EAAE,MAAM,CAAC;IACxB,cAAc,EAAE,OAAO,CAAC;IACxB,eAAe,EAAE,kBAAkB,GAAG,gBAAgB,CAAC;CACxD;AAED,wBAAgB,iBAAiB,CAC/B,SAAS,EAAE,kBAAkB,GAC5B,iBAAiB,CAqBnB"}
+{"version":3,"file":"cursor-retrieval-env.d.ts","sourceRoot":"","sources":["../../src/utils/cursor-retrieval-env.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAMH,eAAO,MAAM,UAAU,EAAG,QAAiB,CAAC;AAC5C,eAAO,MAAM,QAAQ,EAAG,MAAe,CAAC;AACxC,eAAO,MAAM,WAAW,EAAG,SAAkB,CAAC;AAE9C,MAAM,MAAM,kBAAkB,GAC1B,OAAO,UAAU,GACjB,OAAO,QAAQ,GACf,OAAO,WAAW,CAAC;AAEvB,MAAM,WAAW,sBAAsB;IACrC,GAAG,EAAE,kBAAkB,CAAC;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,kBAAkB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC9B,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,wBAAgB,WAAW,IAAI,MAAM,CAMpC;AAED,wBAAgB,4BAA4B,IAAI,sBAAsB,CA8CrE;AAED,wBAAgB,wBAAwB,IAAI,kBAAkB,CAU7D;AAED,wBAAgB,MAAM,CAAC,GAAG,CAAC,EAAE,kBAAkB,GAAG,IAAI,GAAG,OAAO,CAE/D;AAED,8FAA8F;AAC9F,wBAAgB,kBAAkB,CAAC,GAAG,CAAC,EAAE,kBAAkB,GAAG,IAAI,GAAG,OAAO,CAG3E;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,eAAe,EAAE,MAAM,CAAC;IACxB,cAAc,EAAE,OAAO,CAAC;IACxB,eAAe,EAAE,kBAAkB,GAAG,gBAAgB,CAAC;CACxD;AAED,wBAAgB,iBAAiB,CAC/B,SAAS,EAAE,kBAAkB,GAC5B,iBAAiB,CAqBnB"}

package/dist/utils/cursor-retrieval-env.js

@@ -1,5 +1,6 @@
 /**
- * Detect Cursor Native vs Cursor++ BYOK for retrieval routing.
+ * Detect Cursor Native vs BYOK environment for retrieval routing.
+ * This is an environment probe, not a product install surface.
  * Mirrors templates/trellis/scripts/common/cursor_retrieval_env.py
  */
 import fs from "node:fs";
@@ -82,7 +83,7 @@ export function semanticRouteSpec(cursorEnv) {
             : "";
         return {
             commands: ["fast_context_search (fast-context MCP)"],
-            rationaleSuffix: " Cursor++ BYOK: built-in semantic unavailable; fast-context MCP primary." +
+            rationaleSuffix: " BYOK env probe: built-in semantic unavailable; Optional fast-context only if selected." +
                 unknownCaveat,
             platformNative: false,
             semanticBackend: "fast-context-mcp",

package/dist/utils/cursor-retrieval-env.js.map

@@ -1 +1 @@
-{"version":3,"file":"cursor-retrieval-env.js","sourceRoot":"","sources":["../../src/utils/cursor-retrieval-env.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"cursor-retrieval-env.js","sourceRoot":"","sources":["../../src/utils/cursor-retrieval-env.ts"],"names":[],"mappings":"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"}

package/dist/utils/cursor2plus-residue-cleanup.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Hash-safe cleanup of retired Cursor++ managed residue.
+ *
+ * Cursor++ product surfaces are no longer shipped. On `cstl update`, delete
+ * known managed paths only when on-disk content matches a pristine template
+ * hash captured from the last shipped SSOT bytes. User-modified files are
+ * preserved with a warning.
+ *
+ * Never target `.cstl/middleware/` (user overlay). Residue paths are an
+ * explicit allow-list; overlay isolation is a separate contract.
+ */
+/** Relative path under the workflow dir (`.cstl` or `.trellis`) or absolute-from-cwd. */
+export interface Cursor2plusResidueTarget {
+    /** Posix-style path relative to project cwd (uses `{workflow}` placeholder). */
+    pathTemplate: string;
+    allowedHashes: readonly string[];
+}
+/**
+ * Pristine hashes computed from packages/cli/src/templates before P23 deletion
+ * (LF-normalized SHA-256, same as computeHash).
+ */
+export declare const CURSOR2PLUS_RESIDUE_TARGETS: readonly Cursor2plusResidueTarget[];
+export interface Cursor2plusResidueCleanupResult {
+    deleted: string[];
+    preservedModified: string[];
+    missing: string[];
+}
+/**
+ * Delete pristine Cursor++ residue under cwd. Never deletes user-modified files.
+ */
+export declare function cleanupCursor2plusResidue(cwd: string, options?: {
+    dryRun?: boolean;
+}): Cursor2plusResidueCleanupResult;
+/**
+ * True when any Cursor++ local bundle directory still exists (residue notice).
+ */
+export declare function hasCursor2plusBundleResidue(cwd: string): boolean;
+//# sourceMappingURL=cursor2plus-residue-cleanup.d.ts.map

package/dist/utils/cursor2plus-residue-cleanup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cursor2plus-residue-cleanup.d.ts","sourceRoot":"","sources":["../../src/utils/cursor2plus-residue-cleanup.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AASH,yFAAyF;AACzF,MAAM,WAAW,wBAAwB;IACvC,gFAAgF;IAChF,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,SAAS,MAAM,EAAE,CAAC;CAClC;AAED;;;GAGG;AACH,eAAO,MAAM,2BAA2B,EAAE,SAAS,wBAAwB,EA6D1E,CAAC;AAEF,MAAM,WAAW,+BAA+B;IAC9C,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,iBAAiB,EAAE,MAAM,EAAE,CAAC;IAC5B,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAwBD;;GAEG;AACH,wBAAgB,yBAAyB,CACvC,GAAG,EAAE,MAAM,EACX,OAAO,GAAE;IAAE,MAAM,CAAC,EAAE,OAAO,CAAA;CAAO,GACjC,+BAA+B,CA8BjC;AAED;;GAEG;AACH,wBAAgB,2BAA2B,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAQhE"}

package/dist/utils/cursor2plus-residue-cleanup.js

@@ -0,0 +1,145 @@
+/**
+ * Hash-safe cleanup of retired Cursor++ managed residue.
+ *
+ * Cursor++ product surfaces are no longer shipped. On `cstl update`, delete
+ * known managed paths only when on-disk content matches a pristine template
+ * hash captured from the last shipped SSOT bytes. User-modified files are
+ * preserved with a warning.
+ *
+ * Never target `.cstl/middleware/` (user overlay). Residue paths are an
+ * explicit allow-list; overlay isolation is a separate contract.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { DIR_NAMES } from "../constants/paths.js";
+import { computeHash, removeHash } from "./template-hash.js";
+import { resolveWorkflowDirName } from "./workflow-dir.js";
+/**
+ * Pristine hashes computed from packages/cli/src/templates before P23 deletion
+ * (LF-normalized SHA-256, same as computeHash).
+ */
+export const CURSOR2PLUS_RESIDUE_TARGETS = [
+    {
+        pathTemplate: "{workflow}/local/cursor2plus/patch_wpelc8.py",
+        allowedHashes: [
+            "480d24cb0b5f98691938525db2e73326dfc9e2c70783fb3c357bc442f4d4c427",
+        ],
+    },
+    {
+        pathTemplate: "{workflow}/local/cursor2plus/smoke.py",
+        allowedHashes: [
+            "e7eecc069188e1dde85312ac5271932e797a3af37c3ae1bd397bbbbfe4f9785b",
+        ],
+    },
+    {
+        pathTemplate: "{workflow}/local/cursor2plus/README.md",
+        allowedHashes: [
+            "d170822a5f3d2bc01238ca4b9e72acb197b2678da7f5f9ffa0226e09fdb2a312",
+        ],
+    },
+    {
+        pathTemplate: "{workflow}/local/cursor2plus/config.local.json.example",
+        allowedHashes: [
+            "b01b653f74fed06070232eca22f2daeb8c14bf7c99db21446f6ee1105f0ce016",
+        ],
+    },
+    {
+        pathTemplate: "{workflow}/local/cursor2plus/trellis_task_models_config.py",
+        allowedHashes: [
+            "d27ebea2caeb52ec990a99c9e1c20c6a8265f65ceb95f28e01771b4efd6fa891",
+        ],
+    },
+    {
+        pathTemplate: "{workflow}/local/subagent-models.json.example",
+        allowedHashes: [
+            "57212acbb4d2434f13ca5a7b40ec7ca00136870748943a92e8036d8b1e8e7434",
+        ],
+    },
+    {
+        pathTemplate: "{workflow}/local/trellis-task-models.json.example",
+        allowedHashes: [
+            "10b74000b32020fbd5d3be73deeb61c066b51ea6fcfe7c1bba5883deb24fce65",
+        ],
+    },
+    {
+        pathTemplate: "{workflow}/local/trellis-task-models.json5.example",
+        allowedHashes: [
+            "30c7bf1809065eecd9afcafd67ad36d32b5d3a5a3c07f54b9a58a22b4f34f267",
+        ],
+    },
+    {
+        pathTemplate: ".cursor/commands/cstl-cursor2plus-setup.md",
+        allowedHashes: [
+            "7792337f85639e1bd0162d525056ee26cadb3400bf77e98d1a9bfe18d09d885c",
+        ],
+    },
+    {
+        pathTemplate: ".cursor/skills/cstl-cursor2plus-setup/SKILL.md",
+        allowedHashes: [
+            "bc3e11e550caceab6fa3feb994bcc5c4fb45ee612feb5223b0212b061d136d16",
+        ],
+    },
+];
+function resolvePathTemplate(pathTemplate, workflowDirName) {
+    return pathTemplate.replaceAll("{workflow}", workflowDirName);
+}
+function tryRemoveEmptyParents(filePath, stopAt) {
+    let dir = path.dirname(filePath);
+    const stop = path.resolve(stopAt);
+    while (dir.startsWith(stop) && dir !== stop) {
+        if (!fs.existsSync(dir)) {
+            dir = path.dirname(dir);
+            continue;
+        }
+        const entries = fs.readdirSync(dir);
+        if (entries.length > 0)
+            break;
+        fs.rmdirSync(dir);
+        dir = path.dirname(dir);
+    }
+}
+/**
+ * Delete pristine Cursor++ residue under cwd. Never deletes user-modified files.
+ */
+export function cleanupCursor2plusResidue(cwd, options = {}) {
+    const workflowDirName = resolveWorkflowDirName(cwd) ?? DIR_NAMES.WORKFLOW;
+    const result = {
+        deleted: [],
+        preservedModified: [],
+        missing: [],
+    };
+    for (const target of CURSOR2PLUS_RESIDUE_TARGETS) {
+        const rel = resolvePathTemplate(target.pathTemplate, workflowDirName);
+        const fullPath = path.join(cwd, rel);
+        if (!fs.existsSync(fullPath)) {
+            result.missing.push(rel);
+            continue;
+        }
+        const content = fs.readFileSync(fullPath, "utf-8");
+        const hash = computeHash(content);
+        if (!target.allowedHashes.includes(hash)) {
+            result.preservedModified.push(rel);
+            continue;
+        }
+        if (!options.dryRun) {
+            fs.unlinkSync(fullPath);
+            removeHash(cwd, rel);
+            tryRemoveEmptyParents(fullPath, cwd);
+        }
+        result.deleted.push(rel);
+    }
+    return result;
+}
+/**
+ * True when any Cursor++ local bundle directory still exists (residue notice).
+ */
+export function hasCursor2plusBundleResidue(cwd) {
+    const workflowDirName = resolveWorkflowDirName(cwd) ?? DIR_NAMES.WORKFLOW;
+    const candidates = [
+        path.join(cwd, workflowDirName, "local", "cursor2plus"),
+        path.join(cwd, ".cstl", "local", "cursor2plus"),
+        path.join(cwd, ".trellis", "local", "cursor2plus"),
+    ];
+    return candidates.some((p) => fs.existsSync(p));
+}
+//# sourceMappingURL=cursor2plus-residue-cleanup.js.map

package/dist/utils/cursor2plus-residue-cleanup.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cursor2plus-residue-cleanup.js","sourceRoot":"","sources":["../../src/utils/cursor2plus-residue-cleanup.ts"],"names":[],"mappings":"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"}

package/dist/utils/manifest-prune.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"manifest-prune.d.ts","sourceRoot":"","sources":["../../src/utils/manifest-prune.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAWH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAC;AACnD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAK5D,MAAM,WAAW,WAAW;IAC1B,0DAA0D;IAC1D,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,6EAA6E;IAC7E,MAAM,EAAE,cAAc,CAAC;CACxB;AA0DD,MAAM,WAAW,YAAY;IAC3B;;;;OAIG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,uBAAuB,CACrC,GAAG,EAAE,MAAM,EACX,mBAAmB,EAAE,SAAS,MAAM,EAAE,EACtC,MAAM,EAAE,cAAc,EACtB,OAAO,GAAE,YAAiB,GACzB,WAAW,CAmCb"}
+{"version":3,"file":"manifest-prune.d.ts","sourceRoot":"","sources":["../../src/utils/manifest-prune.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAWH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAC;AACnD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAK5D,MAAM,WAAW,WAAW;IAC1B,0DAA0D;IAC1D,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,6EAA6E;IAC7E,MAAM,EAAE,cAAc,CAAC;CACxB;AA0DD,MAAM,WAAW,YAAY;IAC3B;;;;OAIG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,uBAAuB,CACrC,GAAG,EAAE,MAAM,EACX,mBAAmB,EAAE,SAAS,MAAM,EAAE,EACtC,MAAM,EAAE,cAAc,EACtB,OAAO,GAAE,YAAiB,GACzB,WAAW,CAwCb"}