@blxzer/cursor-trellis 0.4.2 → 0.4.3

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

@@ -0,0 +1,237 @@
+"""Stage 4 Full Quality helpers (controls, AC ledger, graded Independent Check).
+
+Python projection of the Kernel Full Quality contract. Kernel remains the
+writer; these helpers validate extras before archive and prefer persisted
+required_controls over inferring Rigor from files.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import re
+from pathlib import Path
+from typing import Any
+
+FULL_QUALITY_SOURCE = "full-quality-contract"
+FULL_QUALITY_SCHEMA_VERSION = 1
+FULL_BASELINE_CONTROLS = (
+    "definition",
+    "execution-contract",
+    "verification-plan",
+    "evidence",
+    "independent-check",
+)
+DEFAULT_CONTROL_SURFACES = {
+    "definition": "prd.md",
+    "execution-contract": "implement.md",
+    "verification-plan": "implement.md",
+    "evidence": "verify.md",
+    "design": "design.md",
+}
+DESIGN_RISK_SIGNALS = {
+    "architecture",
+    "public-contract",
+    "schema",
+    "security",
+    "secret",
+    "framework-semantics",
+    "runtime-semantics",
+}
+PLACEHOLDER_VALUE_RE = re.compile(
+    r"(?i)^(TBD|TODO|待定|待补充|N/?A|NA|NONE|-|\.\.\.)$"
+)
+AC_ITEM_RE = re.compile(r"(?im)^\s*-\s*\[[ xX]\]\s+(.+)$")
+
+
+class FullQualityError(RuntimeError):
+    """Full Quality contract rejected a start/close request."""
+
+
+def quality_fingerprint(payload: str) -> str:
+    digest = hashlib.sha256(payload.encode("utf-8")).hexdigest()
+    return f"sha256:{digest}"
+
+
+def resolve_required_controls(
+    *,
+    rigor: str = "lite",
+    verification_profile: str | None = None,
+    risk_signals: list[str] | None = None,
+    policy_requires_design: bool = False,
+    explicit_controls: list[str] | None = None,
+    surfaces: dict[str, str] | None = None,
+) -> dict[str, Any]:
+    normalized = "full" if rigor == "full" else "lite"
+    signals = [str(item).strip().lower() for item in (risk_signals or []) if item]
+    design_required = normalized == "full" and (
+        policy_requires_design
+        or verification_profile == "architecture"
+        or any(signal in DESIGN_RISK_SIGNALS for signal in signals)
+    )
+    if explicit_controls:
+        controls = _unique(explicit_controls)
+    elif normalized == "full":
+        controls = list(FULL_BASELINE_CONTROLS)
+        if design_required:
+            controls.append("design")
+    else:
+        controls = ["definition", "evidence"]
+    if design_required and "design" not in controls:
+        controls.append("design")
+    return {
+        "schema_version": FULL_QUALITY_SCHEMA_VERSION,
+        "source": FULL_QUALITY_SOURCE,
+        "rigor": normalized,
+        "controls": controls,
+        "surfaces": {**DEFAULT_CONTROL_SURFACES, **(surfaces or {})},
+        "resolved_from": {
+            "verification_profile": verification_profile,
+            "risk_signals": signals,
+            "policy_requires_design": policy_requires_design,
+        },
+    }
+
+
+def rigor_from_required_controls(task_data: dict | None) -> str | None:
+    extras = task_data or {}
+    bundle = extras.get("required_controls")
+    if not isinstance(bundle, dict):
+        return None
+    rigor = bundle.get("rigor")
+    if rigor in ("lite", "full"):
+        return rigor
+    return None
+
+
+def parse_acceptance_items(prd_text: str) -> list[dict[str, str]]:
+    items: list[dict[str, str]] = []
+    index = 0
+    for match in AC_ITEM_RE.finditer(prd_text):
+        statement = match.group(1).strip()
+        if not statement or PLACEHOLDER_VALUE_RE.match(statement):
+            continue
+        index += 1
+        items.append({"id": f"AC-{index}", "statement": statement})
+    return items
+
+
+def evaluate_independent_check(
+    *,
+    mode: str,
+    independent_worker_available: bool,
+    evidence: str,
+    code_fingerprint: str,
+    attempted_writes: bool = False,
+) -> dict[str, Any]:
+    if attempted_writes:
+        raise FullQualityError("Independent Check is read-only; repairs return to Execute")
+    if mode not in ("self-review", "true-independent"):
+        raise FullQualityError("Independent Check mode must be self-review or true-independent")
+    if mode == "true-independent" and not independent_worker_available:
+        return {
+            "schema_version": FULL_QUALITY_SCHEMA_VERSION,
+            "mode": "true-independent",
+            "readonly": True,
+            "result": "BLOCKED",
+            "evidence": evidence.strip(),
+            "independent_worker": False,
+            "code_fingerprint": code_fingerprint,
+        }
+    if not evidence.strip() or PLACEHOLDER_VALUE_RE.match(evidence.strip()):
+        raise FullQualityError(
+            "Independent Check PASS/FAIL requires non-empty evidence (no fake-green)"
+        )
+    return {
+        "schema_version": FULL_QUALITY_SCHEMA_VERSION,
+        "mode": mode,
+        "readonly": True,
+        "result": "PASS",
+        "evidence": evidence.strip(),
+        "independent_worker": independent_worker_available,
+        "code_fingerprint": code_fingerprint,
+    }
+
+
+def full_quality_archive_errors(task_dir: Path, task_data: dict | None) -> list[str]:
+    """Return archive errors for persisted Full required_controls only.
+
+    Lite and legacy file-heuristic Full are unchanged: this does not force
+    Independent Check onto Lite.
+    """
+    data = task_data or {}
+    bundle = data.get("required_controls")
+    if not isinstance(bundle, dict) or bundle.get("rigor") != "full":
+        return []
+    errors: list[str] = []
+    controls = bundle.get("controls")
+    if not isinstance(controls, list):
+        controls = list(FULL_BASELINE_CONTROLS)
+    surfaces = bundle.get("surfaces") if isinstance(bundle.get("surfaces"), dict) else {}
+    seen: set[str] = set()
+    for control in controls:
+        if control in ("independent-check",):
+            continue
+        relative = surfaces.get(control) or DEFAULT_CONTROL_SURFACES.get(control)
+        if not relative or relative in seen:
+            continue
+        seen.add(relative)
+        path = task_dir / relative
+        if not path.is_file() or not path.read_text(encoding="utf-8").strip():
+            errors.append(f"Full required control {control} missing surface {relative}")
+
+    ledger = data.get("ac_evidence_ledger")
+    if not isinstance(ledger, dict):
+        errors.append("Full Close requires a machine-readable AC → Evidence ledger")
+    else:
+        definition = surfaces.get("definition") or DEFAULT_CONTROL_SURFACES["definition"]
+        prd_path = task_dir / definition
+        prd_text = prd_path.read_text(encoding="utf-8") if prd_path.is_file() else ""
+        acceptance = parse_acceptance_items(prd_text)
+        mapped = {
+            item.get("ac_id"): item
+            for item in ledger.get("items", [])
+            if isinstance(item, dict)
+        }
+        if not acceptance:
+            errors.append(f"{definition} has no Acceptance Criteria items to map")
+        for item in acceptance:
+            mapping = mapped.get(item["id"])
+            ref = mapping.get("evidence_ref") if isinstance(mapping, dict) else ""
+            if not isinstance(ref, str) or not ref.strip() or PLACEHOLDER_VALUE_RE.match(ref.strip()):
+                errors.append(f"AC → Evidence ledger missing mapping for {item['id']}")
+        current_source = quality_fingerprint(prd_text)
+        if ledger.get("source_fingerprint") and ledger.get("source_fingerprint") != current_source:
+            errors.append("AC → Evidence ledger is stale after Definition/code change")
+
+    check = data.get("independent_check")
+    if not isinstance(check, dict):
+        errors.append("Full Close requires a graded Independent Check verdict")
+    else:
+        if check.get("readonly") is False:
+            errors.append("Independent Check is read-only; repairs return to Execute")
+        mode = check.get("mode") or check.get("assurance")
+        if mode == "true-independent" and check.get("independent_worker") is not True:
+            errors.append("true-independent Check cannot be satisfied without an independent worker")
+        if check.get("result") != "PASS":
+            errors.append("Full Close requires Independent Check result PASS")
+        evidence = check.get("evidence")
+        if not isinstance(evidence, str) or not evidence.strip():
+            errors.append("Independent Check PASS requires non-empty evidence (no fake-green)")
+        ledger = data.get("ac_evidence_ledger")
+        if (
+            isinstance(ledger, dict)
+            and isinstance(ledger.get("tested_code_fingerprint"), str)
+            and isinstance(check.get("code_fingerprint"), str)
+            and check.get("code_fingerprint") != ledger.get("tested_code_fingerprint")
+        ):
+            errors.append("Independent Check verdict is stale after code change")
+    return errors
+
+
+def _unique(values: list[str]) -> list[str]:
+    out: list[str] = []
+    for value in values:
+        item = value.strip()
+        if item and item not in out:
+            out.append(item)
+    return out

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

@@ -29,3 +29,9 @@ def run_git(args: list[str], cwd: Path | None = None) -> tuple[int, str, str]:
         return result.returncode, result.stdout, result.stderr
     except Exception as e:
         return 1, "", str(e)
+
+
+def is_git_worktree(path: Path) -> bool:
+    """Return True when path is inside a Git worktree. VCS is On-demand."""
+    rc, out, _ = run_git(["rev-parse", "--is-inside-work-tree"], cwd=path)
+    return rc == 0 and out.strip().lower() == "true"

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

@@ -28,8 +28,7 @@ from .packages_context import (
     get_context_packages_json,
 )
 from .paths import get_repo_root
-from .project_file_stats import resolve_project_file_count_arg
-from .retrieval_pack_context import output_retrieval_pack_json, read_evidence_input
+from .lite_context import LiteContextPackError, get_lite_context_json
 from .trellis_config import read_trellis_config
 from .workflow_phase import (
     filter_platform,
@@ -60,13 +59,14 @@ def main() -> None:
     parser.add_argument(
         "--mode",
         "-m",
-        choices=["default", "record", "packages", "phase", "retrieval-pack"],
+        choices=["default", "record", "packages", "phase", "retrieval-pack", "lite"],
         default="default",
         help=(
             "Output mode: default (full context), record (for record-session), "
             "packages (package info only), phase (workflow step extraction), "
             "retrieval-pack (score and pack already-collected retrieval evidence; "
-            "use after research collection, not on every SessionStart)"
+            "use after research collection, not on every SessionStart), "
+            "lite (Personal Lite phase pack with budget; no Parent/VCS/retrieval-extended)"
         ),
     )
     parser.add_argument(
@@ -138,12 +138,18 @@ def main() -> None:
         print(content, end="")
     elif args.mode == "retrieval-pack":
         try:
+            from .project_file_stats import resolve_project_file_count_arg
+            from .retrieval_pack_context import (
+                output_retrieval_pack_json,
+                read_evidence_input,
+            )
+
             evidence = read_evidence_input(args.input)
             project_file_count = resolve_project_file_count_arg(
                 args.project_file_count,
                 repo_root=get_repo_root(),
             )
-        except (OSError, json.JSONDecodeError, ValueError) as error:
+        except (OSError, json.JSONDecodeError, ValueError, ImportError) as error:
             parser.exit(1, f"retrieval pack error: {error}\n")
         output_retrieval_pack_json(
             evidence_input=evidence,
@@ -153,6 +159,12 @@ def main() -> None:
             pretty=args.json,
             project_file_count=project_file_count,
         )
+    elif args.mode == "lite":
+        try:
+            pack = get_lite_context_json()
+        except LiteContextPackError as error:
+            parser.exit(1, f"lite context pack error: {error}\n")
+        print(json.dumps(pack, indent=2 if args.json else None, ensure_ascii=False))
     else:
         if args.json:
             output_json()

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,
+            )