@blxzer/cursor-trellis 0.4.2 → 0.4.3

package/dist/templates/trellis/scripts/common/lite_context.py

@@ -0,0 +1,280 @@
+#!/usr/bin/env python3
+"""Personal Lite context pack (P29 context-progressive / P30 Stage 3).
+
+Phase-assembled Definition / Evidence pack with a hard budget. Unactivated
+On-demand modules (Parent / VCS / retrieval-extended) and a full workflow.md
+dump are rejected instead of silently stuffed into the pack.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+LITE_PACK_VERSION = 1
+LITE_PACK_SOURCE = "personal-lite-context-pack"
+
+LITE_BASELINE_MODULES = (
+    "intake-basic",
+    "define-basic",
+    "approval-personal",
+    "execute-agent",
+    "verify-basic",
+    "close-basic",
+    "context-progressive",
+    "observability-local",
+)
+
+LITE_BLOCKED_ON_DEMAND_MODULES = (
+    "parent-child",
+    "vcs-integration",
+    "personal-memory",
+    "retention-storage",
+    "retrieval-extended",
+)
+
+LITE_RETRIEVAL_INTENTS = ("exact", "semantic", "structural", "external")
+
+LITE_DEFAULT_MAX_ITEMS = 8
+LITE_DEFAULT_MAX_ESTIMATED_TOKENS = 4000
+LITE_CHARS_PER_TOKEN = 4
+LITE_MIN_ITEM_TOKENS = 40
+
+PHASE_ROLES: dict[str, tuple[str, ...]] = {
+    "open": ("triage", "retrieval-router"),
+    "define": ("triage", "definition", "retrieval-router"),
+    "approve": ("triage", "definition", "approval", "retrieval-router"),
+    "execute": ("definition", "approval", "retrieval-router"),
+    "verify": ("definition", "evidence", "retrieval-router"),
+    "integrate": ("definition", "evidence", "retrieval-router"),
+    "close": ("definition", "evidence", "outcome", "retrieval-router"),
+}
+
+ROLE_MODULE = {
+    "triage": "intake-basic",
+    "definition": "define-basic",
+    "approval": "approval-personal",
+    "evidence": "verify-basic",
+    "outcome": "close-basic",
+    "retrieval-router": "context-progressive",
+}
+
+STATUS_TO_PHASE = {
+    "planning": "define",
+    "in_progress": "execute",
+    "review": "verify",
+    "completed": "close",
+    "done": "close",
+}
+
+
+class LiteContextPackError(RuntimeError):
+    """Lite pack refused to assemble (budget, On-demand, or workflow dump)."""
+
+    def __init__(self, code: str, message: str) -> None:
+        super().__init__(message)
+        self.code = code
+
+
+def kernel_phase_from_legacy_status(status: str | None) -> str:
+    """Project user-visible task.json.status onto a Kernel phase name."""
+    if not status:
+        return "open"
+    return STATUS_TO_PHASE.get(status, "open")
+
+
+def estimate_lite_tokens(text: str) -> int:
+    if not text:
+        return LITE_MIN_ITEM_TOKENS
+    return max(LITE_MIN_ITEM_TOKENS, len(text) // LITE_CHARS_PER_TOKEN + 20)
+
+
+def _normalize_path(value: object) -> str:
+    if not isinstance(value, str) or not value.strip():
+        return ""
+    return value.replace("\\", "/")
+
+
+def _is_workflow_dump(role: str, path: str) -> bool:
+    if role == "workflow-full":
+        return True
+    base = path.rsplit("/", 1)[-1]
+    return base == "workflow.md"
+
+
+def _is_blocked(name: str) -> bool:
+    return name in LITE_BLOCKED_ON_DEMAND_MODULES
+
+
+def build_lite_context_pack(
+    *,
+    phase: str,
+    artifacts: list[dict[str, Any]] | None = None,
+    activated_modules: list[str] | None = None,
+    include_full_workflow: bool = False,
+    max_items: int | None = None,
+    max_estimated_tokens: int | None = None,
+) -> dict[str, Any]:
+    """Assemble a bounded Lite pack. Raises LiteContextPackError on refuse."""
+    if phase not in PHASE_ROLES:
+        raise LiteContextPackError("WORKFLOW_DUMP", f"invalid Lite pack phase: {phase}")
+    if include_full_workflow:
+        raise LiteContextPackError(
+            "WORKFLOW_DUMP",
+            "Lite context pack refuses a full workflow.md dump",
+        )
+
+    activated = [
+        name for name in (activated_modules or []) if isinstance(name, str) and name.strip()
+    ]
+    for name in activated:
+        if _is_blocked(name):
+            raise LiteContextPackError(
+                "ON_DEMAND_INACTIVE",
+                f"Lite pack excludes unactivated On-demand module: {name}",
+            )
+
+    item_cap = LITE_DEFAULT_MAX_ITEMS if max_items is None else max_items
+    token_cap = (
+        LITE_DEFAULT_MAX_ESTIMATED_TOKENS
+        if max_estimated_tokens is None
+        else max_estimated_tokens
+    )
+    allowed_roles = set(PHASE_ROLES[phase])
+
+    candidates: list[dict[str, Any]] = [
+        {
+            "role": "retrieval-router",
+            "module": "context-progressive",
+            "path": "capability://retrieval-router",
+            "estimatedTokens": LITE_MIN_ITEM_TOKENS,
+        }
+    ]
+
+    for artifact in artifacts or []:
+        if not isinstance(artifact, dict):
+            continue
+        role = str(artifact.get("role") or "")
+        path = _normalize_path(artifact.get("path"))
+        if _is_workflow_dump(role, path):
+            raise LiteContextPackError(
+                "WORKFLOW_DUMP",
+                "Lite context pack refuses a full workflow.md dump",
+            )
+        module_name = str(artifact.get("module") or ROLE_MODULE.get(role) or "")
+        if _is_blocked(module_name) or _is_blocked(role):
+            raise LiteContextPackError(
+                "ON_DEMAND_INACTIVE",
+                f"Lite pack excludes unactivated On-demand module: {module_name or role}",
+            )
+        if role not in allowed_roles:
+            continue
+        candidates.append(
+            {
+                "role": role,
+                "module": module_name or "define-basic",
+                "path": path,
+                "estimatedTokens": estimate_lite_tokens(str(artifact.get("content") or "")),
+            }
+        )
+
+    selected: list[dict[str, Any]] = []
+    omitted: list[dict[str, str]] = []
+    warnings: list[str] = []
+    estimated_tokens = 0
+    budget_exceeded = False
+
+    for item in candidates:
+        would_exceed_items = len(selected) >= item_cap
+        next_tokens = int(item["estimatedTokens"])
+        would_exceed_tokens = estimated_tokens + next_tokens > token_cap
+        if would_exceed_items or would_exceed_tokens:
+            budget_exceeded = True
+            reason = (
+                "outside token budget after higher-ranked Lite surfaces"
+                if would_exceed_tokens
+                else "outside item budget after higher-ranked Lite surfaces"
+            )
+            omitted.append({"role": item["role"], "path": item["path"], "reason": reason})
+            continue
+        selected.append(item)
+        estimated_tokens += next_tokens
+
+    if budget_exceeded:
+        if any(
+            row["path"].endswith("workflow.md") or row["role"] == "workflow-full"
+            for row in omitted
+        ):
+            raise LiteContextPackError(
+                "BUDGET_EXCEEDED",
+                "Lite context pack over budget; refusing silent full workflow dump",
+            )
+        warnings.append("budget limits caused Lite pack omission")
+
+    return {
+        "version": LITE_PACK_VERSION,
+        "source": LITE_PACK_SOURCE,
+        "phase": phase,
+        "budget": {
+            "maxItems": item_cap,
+            "maxEstimatedTokens": token_cap,
+            "estimatedTokens": estimated_tokens,
+            "itemsUsed": len(selected),
+        },
+        "selected": selected,
+        "omitted": omitted,
+        "modules": {
+            "baseline": list(LITE_BASELINE_MODULES),
+            "activatedOnDemand": activated,
+        },
+        "retrievalIntents": list(LITE_RETRIEVAL_INTENTS),
+        "warnings": warnings,
+    }
+
+
+def collect_lite_artifacts(task_dir) -> list[dict[str, Any]]:
+    """Read Definition / Evidence surfaces when present (capped per file)."""
+    from pathlib import Path
+
+    root = Path(task_dir)
+    artifacts: list[dict[str, Any]] = []
+    for role, name in (("definition", "prd.md"), ("evidence", "verify.md")):
+        path = root / name
+        if not path.is_file():
+            continue
+        try:
+            content = path.read_text(encoding="utf-8")
+        except OSError:
+            continue
+        artifacts.append(
+            {
+                "role": role,
+                "path": name,
+                "content": content[:12_000],
+            }
+        )
+    return artifacts
+
+
+def get_lite_context_json(repo_root=None) -> dict[str, Any]:
+    """Build a Lite pack for the selected task, or an Open-phase empty pack."""
+    from .paths import get_repo_root, get_selected_task
+    from .tasks import load_task
+    from .task_utils import resolve_task_dir
+
+    root = repo_root or get_repo_root()
+    selected = get_selected_task(root)
+    phase = "open"
+    artifacts: list[dict[str, Any]] = []
+    if selected:
+        task_dir = resolve_task_dir(selected, root)
+        info = load_task(task_dir) if task_dir.is_dir() else None
+        status = getattr(info, "status", None) if info is not None else None
+        if status is None and task_dir.is_dir():
+            from .io import read_json
+            from .paths import FILE_TASK_JSON
+
+            data = read_json(task_dir / FILE_TASK_JSON) or {}
+            status = data.get("status") if isinstance(data, dict) else None
+        phase = kernel_phase_from_legacy_status(status if isinstance(status, str) else None)
+        artifacts = collect_lite_artifacts(task_dir)
+    return build_lite_context_pack(phase=phase, artifacts=artifacts)

package/dist/templates/trellis/scripts/common/ondemand_topology.py

@@ -0,0 +1,225 @@
+"""Stage 5 Topology + typed graph + On-demand (Python projection).
+
+Kernel extras remain authoritative. This module renders and validates the
+same contract; it does not schedule workers or write a second graph.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+STAGE5_SOURCE = "stage5-ondemand-topology"
+STAGE5_SCHEMA_VERSION = 1
+
+STAGE5_ONDEMAND_MODULES = (
+    "candidate-pool",
+    "define-extended",
+    "worker-orchestration",
+    "parent-child",
+    "debug-recovery",
+    "integration-handoff",
+    "session-transfer",
+    "spec-learning",
+    "vcs-integration",
+    "personal-memory",
+    "retention-storage",
+)
+
+ONDEMAND_OWNERS = {
+    "integration-handoff": "parent-child",
+    "session-transfer": "session-transfer",
+}
+
+LITE_DORMANT_ONDEMAND = (
+    "parent-child",
+    "vcs-integration",
+    "personal-memory",
+    "retention-storage",
+)
+
+
+class TopologyError(RuntimeError):
+    """Topology / On-demand contract rejected a request."""
+
+
+def capture_candidate(summary: str) -> dict[str, Any]:
+    return {
+        "kind": "candidate",
+        "summary": (summary or "").strip(),
+        "task_created": False,
+    }
+
+
+def propose_decompose(parent_id: str, slices: list[str]) -> dict[str, Any]:
+    return {
+        "parent_id": parent_id,
+        "slices": _unique(slices),
+        "confirmed": False,
+        "children_created": [],
+    }
+
+
+def confirm_decompose(proposal: dict[str, Any]) -> dict[str, Any]:
+    slices = _unique(proposal.get("slices") or [])
+    return {
+        **proposal,
+        "confirmed": True,
+        "children_created": slices,
+    }
+
+
+def apply_retention(outcome: str) -> str:
+    return outcome
+
+
+def default_topology(
+    parent: str | None = None,
+    children: list[str] | None = None,
+) -> dict[str, Any]:
+    """Seed Topology. ``parent_id`` + empty children stays ``single``."""
+    kids = _unique(children or [])
+    parent_id = (parent or "").strip() or None
+    return {
+        "schema_version": STAGE5_SCHEMA_VERSION,
+        "kind": "parent-child" if kids else "single",
+        "parent_id": parent_id,
+        "children": kids,
+    }
+
+
+def assign_parent(topology: dict[str, Any], parent_id: str) -> dict[str, Any]:
+    current = topology.get("parent_id")
+    next_parent = (parent_id or "").strip()
+    if not next_parent:
+        raise TopologyError("parent_id must be a non-empty string")
+    if current and current != next_parent:
+        raise TopologyError(
+            f"single-parent tree: second parent rejected ({current} vs {next_parent})"
+        )
+    children = list(topology.get("children") or [])
+    return {
+        "schema_version": STAGE5_SCHEMA_VERSION,
+        "kind": "parent-child" if children else "single",
+        "parent_id": next_parent,
+        "children": children,
+    }
+
+
+def assert_integration_authority(actor_role: str) -> None:
+    if actor_role == "parent":
+        return
+    raise TopologyError(
+        "Integration authority stays with Parent; Child cannot integrate-child"
+    )
+
+
+def expand_depends_on_to_requires(
+    graph: dict[str, Any],
+    from_id: str,
+    depends_on: list[str],
+) -> dict[str, Any]:
+    edges = list(graph.get("edges") or [])
+    for dep in _unique(depends_on):
+        if any(
+            edge.get("from") == from_id
+            and edge.get("to") == dep
+            and edge.get("type") == "requires"
+            for edge in edges
+            if isinstance(edge, dict)
+        ):
+            continue
+        edges.append({"from": from_id, "to": dep, "type": "requires"})
+    return {"schema_version": STAGE5_SCHEMA_VERSION, "edges": edges}
+
+
+def unmet_requires(
+    graph: dict[str, Any],
+    satisfied: list[str],
+    from_id: str | None = None,
+) -> list[str]:
+    done = set(satisfied)
+    missing: list[str] = []
+    for edge in graph.get("edges") or []:
+        if not isinstance(edge, dict) or edge.get("type") != "requires":
+            continue
+        if from_id and edge.get("from") != from_id:
+            continue
+        target = edge.get("to")
+        if isinstance(target, str) and target not in done and target not in missing:
+            missing.append(target)
+    return missing
+
+
+def project_task_map_graph(
+    topology: dict[str, Any],
+    graph: dict[str, Any],
+) -> dict[str, Any]:
+    children = []
+    for child_id in topology.get("children") or []:
+        if not isinstance(child_id, str):
+            continue
+        depends = [
+            edge.get("to")
+            for edge in graph.get("edges") or []
+            if isinstance(edge, dict)
+            and edge.get("type") == "requires"
+            and edge.get("from") == child_id
+        ]
+        children.append({"id": child_id, "depends_on": depends})
+    return {
+        "graph_authority": "kernel-extras",
+        "topology_kind": topology.get("kind") or "single",
+        "parent_id": topology.get("parent_id"),
+        "children": children,
+    }
+
+
+def apply_kernel_graph_projection(data: dict[str, Any], extras: dict[str, Any]) -> None:
+    """Stamp Parent task-map frontmatter from Kernel extras. Projection only."""
+    topology = extras.get("topology")
+    graph = extras.get("dependency_graph")
+    if not isinstance(topology, dict) and not isinstance(graph, dict):
+        return
+    projection = project_task_map_graph(
+        topology if isinstance(topology, dict) else {},
+        graph if isinstance(graph, dict) else {"edges": []},
+    )
+    data["graph_authority"] = "kernel-extras"
+    data["topology_kind"] = projection["topology_kind"]
+    if projection.get("parent_id"):
+        data["parent_id"] = projection["parent_id"]
+    existing = {
+        child.get("id"): child
+        for child in data.get("children") or []
+        if isinstance(child, dict)
+    }
+    children = data.setdefault("children", [])
+    if not isinstance(children, list):
+        data["children"] = []
+        children = data["children"]
+    for child in projection["children"]:
+        current = existing.get(child["id"])
+        if current is None:
+            current = {"id": child["id"], "state": "open", "depends_on": []}
+            children.append(current)
+            existing[child["id"]] = current
+        current["depends_on"] = child["depends_on"]
+
+
+def resident_on_demand_modules(extras: dict[str, Any]) -> list[str]:
+    modules = extras.get("ondemand_modules")
+    if not isinstance(modules, dict):
+        return []
+    active = modules.get("active") or []
+    return [name for name in active if isinstance(name, str)]
+
+
+def _unique(values: list[Any]) -> list[str]:
+    out: list[str] = []
+    for value in values:
+        if not isinstance(value, str):
+            continue
+        item = value.strip()
+        if item and item not in out:
+            out.append(item)
+    return out

package/dist/templates/trellis/scripts/common/parent_orchestration.py

@@ -271,7 +271,7 @@ def build_child_prompt(
                 f"Selected task: {child_rel}",
                 "",
                 "Delivery mode: subagent (Cursor)",
-                "- **Default:** Parent session dispatches **Task** with `subagent_type=cstl-implement` and this prompt as the task description (writable sub-agent). Model under Cursor++ BYOK comes from `.cstl/local/cursor2plus/` routing (see `.cstl/framework/cursor-subagent-policy.md` Method 2.5/2.6).",
+                "- **Default:** Parent session dispatches **Task** with `subagent_type=cstl-implement` and this prompt as the task description (writable sub-agent). Native Cursor `model:` frontmatter still applies. Cursor++ / cstl-byok are not Native install surfaces.",
                 "- **Exception:** If parent `child-prompts.md` or the user names this child for a **separate writable Agent chat**, open a new Agent session, pick the model manually, paste this prompt — do not use Task from Parent.",
                 "- Parent retains `review-child` / `integrate-child`. Child must not nest further `cstl-research` / `cstl-implement` / `cstl-check` Task dispatches.",
                 f"- Parent orchestration: `execution_topology={topo}`, `merge_limit={merge_lim}`.",

package/dist/templates/trellis/scripts/common/pool_store.py

@@ -12,7 +12,7 @@ Frontmatter writes splice a re-serialized header between the raw `---`
 fences so the body is preserved byte-for-byte (including the blank line
 after the closing fence and the final newline), and key order stays stable:
 known keys first (id, title, status, type, locale, created, approved,
-linked_tasks), unknown keys keep their original relative order.
+priority, linked_tasks), unknown keys keep their original relative order.
 """
 
 from __future__ import annotations
@@ -22,7 +22,8 @@ from dataclasses import dataclass, field
 from pathlib import Path
 
 from .artifact_search import parse_frontmatter, split_frontmatter
-from .io import read_json, write_json
+from .io import read_json
+from .kernel_command import kernel_expected_revision, kernel_patch, kernel_projection_extras
 from .paths import get_repo_root, get_tasks_dir
 
 POOL_STATUSES = frozenset({"inbox", "review", "accepted", "rejected", "rework"})
@@ -39,6 +40,7 @@ KNOWN_FRONTMATTER_KEY_ORDER = (
     "locale",
     "created",
     "approved",
+    "priority",
     LINKED_TASKS_KEY,
 )
 
@@ -328,7 +330,7 @@ def _iter_task_dirs(tasks_dir: Path):
 
 
 def _task_meta_with_pool_items(task_dir: Path, item_id: str, *, remove: bool) -> bool:
-    """Add/remove item_id in task.json meta.pool_items. True if file changed."""
+    """Add/remove item_id in task.json meta.pool_items via Kernel patch."""
     data = read_json(task_dir / "task.json")
     if not isinstance(data, dict):
         return False
@@ -346,7 +348,17 @@ def _task_meta_with_pool_items(task_dir: Path, item_id: str, *, remove: bool) ->
         pool_items.append(item_id)
     meta[POOL_ITEMS_KEY] = pool_items
     data[META_KEY] = meta
-    return bool(write_json(task_dir / "task.json", data))
+    action = "unlink" if remove else "link"
+    kernel_patch(
+        task_dir,
+        data,
+        kernel_projection_extras(data),
+        expected_revision=kernel_expected_revision(task_dir),
+        actor="pool.py link" if not remove else "pool.py unlink",
+        idempotency_key=f"patch:pool-{action}:{task_dir.name}:{item_id}",
+        evidence="pool_store._task_meta_with_pool_items",
+    )
+    return True
 
 
 def link_item_task(

package/dist/templates/trellis/scripts/common/retrieval_agent_instructions.py

@@ -312,11 +312,11 @@ def render_agent_instructions(
             label = (
                 "**语义合规（cursorEnv 未知，保守 BYOK）：**"
                 if cursor_env == ENV_UNKNOWN
-                else "**语义合规（Cursor++ BYOK）：**"
+                else "**语义合规（BYOK env）：**"
             )
             if locale != "zh":
                 lines.append(
-                    "**Semantic compliance (Cursor++ BYOK):**"
+                    "**Semantic compliance (BYOK env):**"
                     if cursor_env != ENV_UNKNOWN
                     else "**Semantic compliance (cursorEnv unknown, conservative BYOK):**"
                 )

package/dist/templates/trellis/scripts/common/session_context.py

@@ -22,7 +22,6 @@ from pathlib import Path
 from .active_task import resolve_context_key
 from .artifact_locale import artifact_locale_summary, resolve_artifact_locale
 from .config import get_git_packages, get_journal_snippet_enabled
-from .session_memory import get_latest_journal_summary
 from .git import run_git
 from .packages_context import get_packages_section
 from .tasks import iter_active_tasks, load_task, get_all_statuses, children_progress
@@ -48,7 +47,30 @@ from .paths import (
 # =============================================================================
 
 _PACKAGE_NAME = "@blxzer/cursor-trellis"
-_PYTHON_CMD = "python"
+
+
+def _resolve_python_command() -> str:
+    """Pick the platform-appropriate python command.
+
+    Mirrors test resolvePython() (win32 prefers python, POSIX prefers
+    python3) so rendered guidance matches what integration tests assert.
+    """
+    candidates = ["python", "python3"] if os.name == "nt" else ["python3", "python"]
+    for exe in candidates:
+        try:
+            subprocess.run(
+                [exe, "--version"],
+                capture_output=True,
+                timeout=2,
+                check=True,
+            )
+            return exe
+        except (OSError, subprocess.SubprocessError):
+            continue
+    return "python"
+
+
+_PYTHON_CMD = _resolve_python_command()
 _UPDATE_CHECK_TIMEOUT_SECONDS = 1.0
 _VERSION_RE = re.compile(
     r"^\s*(\d+)(?:\.(\d+))?(?:\.(\d+))?(?:-([0-9A-Za-z.-]+))?\s*$"
@@ -842,6 +864,10 @@ def _resolve_journal_snippet(
 ) -> str:
     if not journal_file or not developer:
         return ""
+    try:
+        from .session_memory import get_latest_journal_summary
+    except ImportError:
+        return ""
     return get_latest_journal_summary(journal_file, repo_root, developer)