@blxzer/cursor-trellis 0.4.1 → 0.4.3

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

@@ -0,0 +1,158 @@
+"""Stage 6 Event Bridge + Middleware Provider projection.
+
+Kernel extras remain authoritative. This module mirrors the contract for
+hooks and tests. It does not write a second store or invent Command ops.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+STAGE6_SOURCE = "stage6-adapter-middleware"
+STAGE6_SCHEMA_VERSION = 1
+SMART_SEARCH_PROVIDER = "smart-search"
+EXTERNAL_KNOWLEDGE_CAPABILITY = "external-knowledge"
+RETRIEVAL_INTENTS = ("exact", "semantic", "structural", "external")
+OPTIONAL_CODE_INTEL_PROVIDERS = ("codegraph", "fast-context")
+
+
+class AdapterMiddlewareError(RuntimeError):
+    """Event Bridge / Middleware contract rejected a request."""
+
+
+def default_event_bridge() -> dict[str, Any]:
+    return {
+        "schema_version": STAGE6_SCHEMA_VERSION,
+        "source": STAGE6_SOURCE,
+        "subscriptions": [],
+    }
+
+
+def default_middleware_providers() -> dict[str, Any]:
+    return {
+        "schema_version": STAGE6_SCHEMA_VERSION,
+        "source": STAGE6_SOURCE,
+        "registered": [SMART_SEARCH_PROVIDER],
+        "required": [SMART_SEARCH_PROVIDER],
+        "active": [],
+        "degraded": [],
+        "readiness": {
+            SMART_SEARCH_PROVIDER: {
+                "status": "unknown",
+                "capability": EXTERNAL_KNOWLEDGE_CAPABILITY,
+                "evidence": None,
+            }
+        },
+    }
+
+
+def default_capability_router() -> dict[str, Any]:
+    return {
+        "schema_version": STAGE6_SCHEMA_VERSION,
+        "source": STAGE6_SOURCE,
+        "exact": True,
+        "semantic": True,
+        "structural": True,
+        "external": True,
+    }
+
+
+def dispatch_hook_event(
+    event_bridge: dict[str, Any],
+    event: str,
+    *,
+    source: str = "cursor-hooks",
+    at: str | None = None,
+) -> dict[str, Any]:
+    name = (event or "").strip()
+    if not name:
+        raise AdapterMiddlewareError("event_bridge.last_event.event must be a non-empty string")
+    delivered: list[str] = []
+    skipped: list[str] = []
+    for item in event_bridge.get("subscriptions") or []:
+        if not isinstance(item, dict):
+            continue
+        module = str(item.get("module") or "").strip()
+        if not module:
+            continue
+        if item.get("event") == name:
+            if module not in delivered:
+                delivered.append(module)
+        else:
+            skipped.append(module)
+    return {
+        "event": name,
+        "at": at or "",
+        "source": source,
+        "delivered": delivered,
+        "skipped": skipped,
+    }
+
+
+def probe_smart_search_readiness(*, available: bool | None = None, status: str | None = None) -> dict[str, Any]:
+    resolved = status
+    if resolved not in {"ready", "missing", "failed", "unknown"}:
+        if available is True:
+            resolved = "ready"
+        elif available is False:
+            resolved = "missing"
+        else:
+            resolved = "unknown"
+    return {
+        "status": resolved,
+        "capability": EXTERNAL_KNOWLEDGE_CAPABILITY,
+        "evidence": None,
+    }
+
+
+def normalize_capability_router(raw: Any) -> dict[str, Any]:
+    if raw is None:
+        return default_capability_router()
+    if not isinstance(raw, dict):
+        raise AdapterMiddlewareError("capability_router must be a JSON object")
+    for key in list(raw.keys()):
+        if key in OPTIONAL_CODE_INTEL_PROVIDERS or key in {
+            "fast_context_search",
+            "codegraph_explore",
+            "codegraph_search",
+            "codegraph_callers",
+        }:
+            raise AdapterMiddlewareError("capability_router must not bind Optional tool names")
+    next_router = default_capability_router()
+    for intent in RETRIEVAL_INTENTS:
+        if raw.get(intent) is False:
+            next_router.pop(intent, None)
+        else:
+            next_router[intent] = True
+    return next_router
+
+
+def required_capabilities(extras: dict[str, Any]) -> list[str]:
+    raw = extras.get("required_capabilities") or []
+    if not isinstance(raw, list):
+        return []
+    out: list[str] = []
+    for item in raw:
+        if isinstance(item, str) and item.strip() and item not in out:
+            out.append(item.strip())
+    return out
+
+
+def assert_external_knowledge(
+    extras: dict[str, Any],
+    readiness: dict[str, Any],
+    *,
+    phase: str,
+) -> None:
+    if phase in {"create", "patch"}:
+        return
+    if EXTERNAL_KNOWLEDGE_CAPABILITY not in required_capabilities(extras):
+        return
+    if readiness.get("status") == "ready":
+        return
+    if extras.get("external_knowledge_policy") == "degrade":
+        extras["profile_health"] = "degraded"
+        return
+    raise AdapterMiddlewareError(
+        "external-knowledge required but smart-search Provider is not ready"
+    )

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

@@ -8,7 +8,8 @@ import sys
 from pathlib import Path
 
 from .config import CONFIG_FILE
-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 DIR_TASKS, DIR_WORKFLOW, FILE_TASK_JSON, get_repo_root
 
 VALID_LOCALES = ("zh", "en")
@@ -272,7 +273,7 @@ def set_workspace_artifact_locale(locale: str, repo_root: Path | None = None) ->
 
 
 def set_task_artifact_locale(task_dir: Path, locale: str, repo_root: Path | None = None) -> None:
-    """Write task.json meta.artifact_locale."""
+    """Write task.json meta.artifact_locale via Kernel patch."""
     _ = repo_root
     normalized = normalize_locale(locale)
     if not normalized:
@@ -291,4 +292,12 @@ def set_task_artifact_locale(task_dir: Path, locale: str, repo_root: Path | None
         meta = {}
     meta[_ARTIFACT_LOCALE_KEY] = normalized
     data["meta"] = meta
-    write_json(task_json, data)
+    kernel_patch(
+        task_dir,
+        data,
+        kernel_projection_extras(data),
+        expected_revision=kernel_expected_revision(task_dir),
+        actor="artifact_locale.set_task_artifact_locale",
+        idempotency_key=f"patch:artifact-locale:{task_dir.name}:{normalized}",
+        evidence="meta.artifact_locale",
+    )

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

@@ -1,4 +1,7 @@
-"""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.
+"""
 
 from __future__ import annotations
 
@@ -92,7 +95,7 @@ def semantic_route_spec(cursor_env: CursorRetrievalEnv) -> dict[str, object]:
         return {
             "commands": ["fast_context_search (fast-context MCP)"],
             "rationale_suffix": (
-                " Cursor++ BYOK: built-in semantic unavailable; fast-context MCP primary."
+                " BYOK env probe: built-in semantic unavailable; Optional fast-context only if selected."
                 + unknown_caveat
             ),
             "platformNative": False,

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()