@blxzer/cursor-trellis 0.4.1 → 0.4.3

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

@@ -0,0 +1,367 @@
+"""JSON CLI bridge to the TypeScript Kernel (P30 Stage 2 strangler).
+
+Python create / start-execution / record-gate / archive / patch submit a
+Kernel Command. `task.json` status, meta, and gate extras are a same-command
+projection, not a second core-state writer.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+from .log import Colors, colored
+
+TASK_RECORD_FIELDS = (
+    "id",
+    "name",
+    "title",
+    "description",
+    "status",
+    "dev_type",
+    "scope",
+    "package",
+    "priority",
+    "creator",
+    "assignee",
+    "createdAt",
+    "completedAt",
+    "branch",
+    "base_branch",
+    "worktree_path",
+    "commit",
+    "pr_url",
+    "subtasks",
+    "children",
+    "parent",
+    "relatedFiles",
+    "notes",
+    "meta",
+)
+
+_NULLABLE_STRING = {
+    "dev_type",
+    "scope",
+    "package",
+    "completedAt",
+    "branch",
+    "base_branch",
+    "worktree_path",
+    "commit",
+    "pr_url",
+    "parent",
+}
+_STRING_ARRAYS = {"subtasks", "children", "relatedFiles"}
+
+
+class KernelCliNotFound(RuntimeError):
+    """`cstl kernel --json` (or TRELLIS_KERNEL_CLI) is not available."""
+
+
+class KernelCommandError(RuntimeError):
+    """Kernel JSON CLI returned ok:false or could not be parsed."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        result: dict | None = None,
+        returncode: int | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.result = result
+        self.returncode = returncode
+
+
+def to_kernel_record(task_data: dict) -> dict:
+    """Project a Python task dict onto the canonical 24-field Kernel record."""
+    record: dict = {}
+    for field in TASK_RECORD_FIELDS:
+        if field in task_data:
+            record[field] = task_data[field]
+            continue
+        if field in _NULLABLE_STRING:
+            record[field] = None
+        elif field in _STRING_ARRAYS:
+            record[field] = []
+        elif field == "meta":
+            record[field] = {}
+        elif field == "priority":
+            record[field] = "P2"
+        elif field == "status":
+            record[field] = "planning"
+        elif field in ("description", "notes", "id", "name", "title", "creator", "assignee", "createdAt"):
+            record[field] = ""
+        else:
+            record[field] = None
+    if not isinstance(record["meta"], dict):
+        record["meta"] = {}
+    else:
+        record["meta"] = {
+            key: value
+            for key, value in record["meta"].items()
+            if key not in {"classification", "task_kind", "task_type", "mode"}
+        }
+    for array_field in _STRING_ARRAYS:
+        value = record[array_field]
+        if not isinstance(value, list):
+            record[array_field] = []
+    return record
+
+
+def kernel_cli_argv() -> list[str]:
+    override = os.environ.get("TRELLIS_KERNEL_CLI", "").strip()
+    if override:
+        if sys.platform == "win32":
+            import shlex
+
+            return shlex.split(override, posix=False)
+        import shlex
+
+        return shlex.split(override)
+    cstl = shutil.which("cstl")
+    if cstl:
+        return [cstl, "kernel", "--json"]
+    raise KernelCliNotFound(
+        "Kernel CLI not found. Set TRELLIS_KERNEL_CLI or put `cstl` on PATH. "
+        "Stage 2 create/start-execution/record-gate/archive/patch require `cstl kernel --json`."
+    )
+
+
+def run_kernel_command(payload: dict, *, cwd: Path | None = None) -> dict:
+    """Send one Kernel Command on stdin and parse one JSON object from stdout."""
+    argv = kernel_cli_argv()
+    encoded = json.dumps(payload, ensure_ascii=False)
+    try:
+        proc = subprocess.run(
+            argv,
+            input=encoded,
+            capture_output=True,
+            text=True,
+            encoding="utf-8",
+            cwd=str(cwd) if cwd is not None else None,
+            check=False,
+        )
+    except OSError as err:
+        raise KernelCommandError(f"failed to invoke Kernel CLI {argv!r}: {err}") from err
+
+    raw = (proc.stdout or "").strip()
+    parsed: dict | None = None
+    if raw:
+        try:
+            parsed = json.loads(raw)
+        except json.JSONDecodeError:
+            last_line = raw.splitlines()[-1] if raw.splitlines() else raw
+            try:
+                parsed = json.loads(last_line)
+            except json.JSONDecodeError:
+                parsed = None
+
+    if not isinstance(parsed, dict):
+        err_tail = (proc.stderr or "").strip()[-800:]
+        raise KernelCommandError(
+            f"Kernel CLI did not return JSON (exit {proc.returncode}). {err_tail}",
+            returncode=proc.returncode,
+        )
+
+    if not parsed.get("ok"):
+        error = parsed.get("error") if isinstance(parsed.get("error"), dict) else {}
+        code = error.get("code", "UNKNOWN")
+        message = error.get("message", "kernel command failed")
+        raise KernelCommandError(
+            f"Kernel {payload.get('op', 'command')} failed ({code}): {message}",
+            result=parsed,
+            returncode=proc.returncode,
+        )
+    return parsed
+
+
+def kernel_read(task_dir: Path) -> dict:
+    return run_kernel_command({"op": "read", "taskDir": str(task_dir)})
+
+
+def kernel_expected_revision(task_dir: Path) -> int:
+    result = kernel_read(task_dir)
+    kernel = result.get("kernel")
+    if not isinstance(kernel, dict):
+        raise KernelCommandError("Kernel read did not include kernel.revision", result=result)
+    revision = kernel.get("revision")
+    if not isinstance(revision, int) or revision < 0:
+        raise KernelCommandError(
+            f"Kernel revision is invalid: {revision!r}",
+            result=result,
+        )
+    return revision
+
+
+def kernel_create(
+    task_dir: Path,
+    record: dict,
+    *,
+    actor: str,
+    idempotency_key: str,
+    evidence: str | None = None,
+    extras: dict | None = None,
+) -> dict:
+    payload: dict = {
+        "op": "create",
+        "taskDir": str(task_dir),
+        "actor": actor,
+        "idempotencyKey": idempotency_key,
+        "record": to_kernel_record(record),
+    }
+    if extras:
+        payload["extras"] = extras
+    if evidence:
+        payload["evidence"] = evidence
+    return run_kernel_command(payload)
+
+
+def kernel_start(
+    task_dir: Path,
+    record: dict,
+    extras: dict,
+    *,
+    expected_revision: int,
+    actor: str,
+    idempotency_key: str,
+    evidence: str | None = None,
+) -> dict:
+    payload: dict = {
+        "op": "start",
+        "taskDir": str(task_dir),
+        "expectedRevision": expected_revision,
+        "actor": actor,
+        "idempotencyKey": idempotency_key,
+        "record": to_kernel_record(record),
+        "extras": extras,
+    }
+    if evidence:
+        payload["evidence"] = evidence
+    return run_kernel_command(payload)
+
+
+def kernel_record_gate(
+    task_dir: Path,
+    *,
+    expected_revision: int,
+    actor: str,
+    idempotency_key: str,
+    transition: str,
+    gate: str,
+    record: dict,
+    extras: dict,
+    evidence: str | None = None,
+) -> dict:
+    payload: dict = {
+        "op": "record-gate",
+        "taskDir": str(task_dir),
+        "expectedRevision": expected_revision,
+        "actor": actor,
+        "idempotencyKey": idempotency_key,
+        "transition": transition,
+        "gate": gate,
+        "record": record,
+        "extras": extras,
+    }
+    if evidence:
+        payload["evidence"] = evidence
+    return run_kernel_command(payload)
+
+
+KERNEL_PROJECTION_EXTRA_KEYS = (
+    "quality_gate_results",
+    "execution_approval",
+    "required_controls",
+    "ac_evidence_ledger",
+    "independent_check",
+    "topology",
+    "dependency_graph",
+    "ondemand_modules",
+    "depends_on",
+    "dependency_satisfied",
+    "decompose_proposal",
+    "profile_health",
+    "event_bridge",
+    "middleware_providers",
+    "capability_router",
+    "required_capabilities",
+)
+
+
+def kernel_projection_extras(task_data: dict) -> dict:
+    """Non-canonical task.json fields owned by the same Kernel Command."""
+    extras: dict = {}
+    for key in KERNEL_PROJECTION_EXTRA_KEYS:
+        if key in task_data:
+            extras[key] = task_data[key]
+    return extras
+
+
+def kernel_archive(
+    task_dir: Path,
+    record: dict,
+    extras: dict,
+    *,
+    expected_revision: int,
+    actor: str,
+    idempotency_key: str,
+    evidence: str | None = None,
+) -> dict:
+    payload: dict = {
+        "op": "archive",
+        "taskDir": str(task_dir),
+        "expectedRevision": expected_revision,
+        "actor": actor,
+        "idempotencyKey": idempotency_key,
+        "record": to_kernel_record(record),
+        "extras": extras,
+    }
+    if evidence:
+        payload["evidence"] = evidence
+    return run_kernel_command(payload)
+
+
+def kernel_patch(
+    task_dir: Path,
+    record: dict | None = None,
+    extras: dict | None = None,
+    *,
+    expected_revision: int,
+    actor: str,
+    idempotency_key: str,
+    evidence: str | None = None,
+) -> dict:
+    payload: dict = {
+        "op": "patch",
+        "taskDir": str(task_dir),
+        "expectedRevision": expected_revision,
+        "actor": actor,
+        "idempotencyKey": idempotency_key,
+    }
+    if record is not None:
+        payload["record"] = to_kernel_record(record)
+    if extras is not None:
+        payload["extras"] = extras
+    if evidence:
+        payload["evidence"] = evidence
+    return run_kernel_command(payload)
+
+
+def print_kernel_error(err: Exception) -> None:
+    print(colored(f"Error: {err}", Colors.RED), file=sys.stderr)
+    if isinstance(err, KernelCommandError) and isinstance(err.result, dict):
+        half = err.result.get("halfConversion")
+        if isinstance(half, dict) and half.get("kernelPersisted"):
+            print(
+                colored(
+                    "Kernel.json was committed but the task.json projection did not finish "
+                    "(half-conversion). Re-run the same command to recover; do not treat this as success.",
+                    Colors.YELLOW,
+                ),
+                file=sys.stderr,
+            )

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)