@blxzer/cursor-trellis 0.4.1 → 0.4.3

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

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

@@ -26,6 +26,7 @@ from .task_map import (
     validate_child_archive_state,
     validate_parent_children_complete,
 )
+from .full_quality import full_quality_archive_errors, rigor_from_required_controls
 
 SCHEMA_VERSION = 1
 BASELINE_GATE = "baseline-check"
@@ -182,13 +183,45 @@ def normalize_result(result: str) -> str:
     return result.strip().upper()
 
 
+def wave_c_stop_read_confirmed(start: Path | None = None) -> bool:
+    """Return True after ``cstl update`` wrote the Wave C confirm flag.
+
+    Unconfirmed projects keep leftover dual-read. Missing ``.cstl`` is
+    unconfirmed (unit fixtures without a repo root stay dual-read).
+    """
+    from .paths import DIR_WORKFLOW, get_repo_root
+
+    root = get_repo_root(start)
+    path = root / DIR_WORKFLOW / ".p36-wave-c.json"
+    if not path.is_file():
+        return False
+    try:
+        parsed = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return False
+    return isinstance(parsed, dict) and parsed.get("confirmed") is True
+
+
 def task_closeout_profile(task_dir: Path, task_data: dict | None = None) -> str:
-    """Return lite, full, or parent closeout profile."""
+    """Return lite, full, or parent closeout profile.
+
+    New Tasks use persisted ``required_controls`` / Topology only. Missing
+    contract is explicit Lite. File existence and ``children[]`` are not
+    used to infer Rigor or Parent. Leftover kind/mode/classification are
+    dual-read only until Wave C is confirmed.
+    """
     data = task_data or {}
-    child_names = data.get("children")
-    if isinstance(child_names, list) and any(isinstance(name, str) for name in child_names):
+    topology = data.get("topology") if isinstance(data.get("topology"), dict) else {}
+    if topology.get("kind") == "parent-child":
         return "parent"
 
+    persisted = rigor_from_required_controls(data)
+    if persisted in ("lite", "full"):
+        return persisted
+
+    if wave_c_stop_read_confirmed(task_dir):
+        return "lite"
+
     meta = data.get("meta") if isinstance(data.get("meta"), dict) else {}
     candidates = [
         data.get("task_kind"),
@@ -200,8 +233,6 @@ def task_closeout_profile(task_dir: Path, task_data: dict | None = None) -> str:
         meta.get("classification"),
         meta.get("mode"),
     ]
-
-    explicit_lite = False
     for value in candidates:
         if not isinstance(value, str):
             continue
@@ -211,13 +242,8 @@ def task_closeout_profile(task_dir: Path, task_data: dict | None = None) -> str:
         if "full" in normalized:
             return "full"
         if "lite" in normalized:
-            explicit_lite = True
-
-    if explicit_lite:
-        return "lite"
+            return "lite"
 
-    if (task_dir / "design.md").is_file() and (task_dir / "implement.md").is_file():
-        return "full"
     return "lite"
 
 
@@ -478,7 +504,12 @@ def make_baseline_record(
 
 
 def write_gate_record(task_data: dict, transition: str, gate: str, record: dict) -> None:
-    """Write a gate record into task_data in-place."""
+    """Write a gate record into task_data in-place.
+
+    This mutates memory only. Stage 2 persists `quality_gate_results` as a
+    Kernel Command projection (same command as `record-gate` / start / archive).
+    Do not treat this helper as an independent `task.json` writer.
+    """
     qgr = task_data.get("quality_gate_results")
     if not isinstance(qgr, dict):
         qgr = {}
@@ -499,6 +530,35 @@ def write_gate_record(task_data: dict, transition: str, gate: str, record: dict)
     transition_records[gate] = record
 
 
+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 collect_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 build_reviewer_gate_record(
     task_dir: Path,
     task_data: dict,
@@ -998,6 +1058,7 @@ def validate_archive(
 
     errors.extend(_required_file_errors(task_dir, ["verify.md"]))
     errors.extend(_verify_evidence_errors(task_dir, task_data))
+    errors.extend(full_quality_archive_errors(task_dir, task_data))
 
     parent_name = task_data.get("parent")
     if isinstance(parent_name, str) and parent_name:

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

@@ -2,8 +2,10 @@
 """
 Parent/Child task-map helpers.
 
-task-map.md is the Parent Supervisor's orchestration authority. This module
-parses and writes only the small YAML frontmatter subset generated here.
+task-map.md is a projection of the Kernel Topology / Dependency Graph plus
+Parent orchestration fields (child worker state, event log). Graph authority
+is Kernel extras (`topology`, `dependency_graph`); this module may render,
+not invent, typed edges.
 """
 
 from __future__ import annotations
@@ -75,7 +77,7 @@ def ensure_task_map(
         data = {
             "parent_id": parent_data.get("id") or parent_dir.name,
             "contract_epoch": 1,
-            "execution_topology": "serial",
+            "execution_topology": "parallel",
             "merge_limit": 1,
             "children": [],
             "stages": [],
@@ -85,7 +87,7 @@ def ensure_task_map(
 
     data.setdefault("parent_id", parent_data.get("id") or parent_dir.name)
     data.setdefault("contract_epoch", 1)
-    data.setdefault("execution_topology", "serial")
+    data.setdefault("execution_topology", "parallel")
     data.setdefault("merge_limit", 1)
     data.setdefault("children", [])
     data.setdefault("stages", [])
@@ -102,6 +104,16 @@ def ensure_task_map(
             data["children"].append(child)
             existing[child_name] = child
 
+    extras = {
+        key: parent_data[key]
+        for key in ("topology", "dependency_graph")
+        if key in parent_data
+    }
+    if extras:
+        from .ondemand_topology import apply_kernel_graph_projection
+
+        apply_kernel_graph_projection(data, extras)
+
     write_task_map(parent_dir, data, body, event)
     return data
 
@@ -492,12 +504,21 @@ def _default_body() -> str:
     return (
         "# Task Map\n\n"
         "## Orchestration notes\n\n"
-        "- `execution_topology: parallel` — children with empty `depends_on` may run concurrently; "
-        "Parent integrates serially up to `merge_limit`.\n"
+        "- **parallel-first:** Prefer Cursor Multitask / Build in Parallel / Agent `Task` / native "
+        "worktree. Trellis does not schedule workers or replace Multitask.\n"
+        "- `execution_topology: parallel` — default when ≥2 children have empty `depends_on`. "
+        "Parent `integrate-child`, HITL, `start-execution --approved`, and reviewer gates stay "
+        "serial (`merge_limit`).\n"
+        "- `serial_reason` — required when topology is `serial`. One of: shared write-set / "
+        "HITL or reviewer gate / `depends_on` unmet / user asked serial / conflict surface "
+        "cannot isolate.\n"
+        "- `stages:` (or `parallel_groups`) — concurrently runnable child id groups.\n"
+        "- `merge_points` — where serial join happens (usually `integrate-child` + gates). "
+        "Default `merge_limit: 1`.\n"
+        "- `touches` (or `conflict_surface`) — write-sets that can collide; declare before dispatch.\n"
         "- Child-reported states: `open` → `working` → `blocked` | `review`.\n"
         "- Parent-controlled states: `review` → `changes` | `accepted` → `integrating` → "
         "`integrated` | `cancelled`.\n"
-        "- Declare `touches` per child before dispatch to reduce merge conflicts.\n"
         "- `isolation: git-worktree` — run `prepare-child-worktree` from the **git package root** "
         "(not a non-git harness root).\n\n"
         "## Event Log\n\n"
@@ -594,10 +615,22 @@ def _format_frontmatter(data: dict) -> str:
     lines = [
         f"parent_id: {_format_value(data.get('parent_id'))}",
         f"contract_epoch: {_format_value(data.get('contract_epoch', 1))}",
-        f"execution_topology: {_format_value(data.get('execution_topology', 'serial'))}",
+        f"execution_topology: {_format_value(data.get('execution_topology', 'parallel'))}",
         f"merge_limit: {_format_value(data.get('merge_limit', 1))}",
-        "children:",
     ]
+    if data.get("serial_reason"):
+        lines.append(f"serial_reason: {_format_value(data.get('serial_reason'))}")
+    if data.get("parallel_groups"):
+        lines.append(f"parallel_groups: {_format_value(data.get('parallel_groups'))}")
+    if data.get("merge_points"):
+        lines.append(f"merge_points: {_format_value(data.get('merge_points'))}")
+    if data.get("conflict_surface"):
+        lines.append(f"conflict_surface: {_format_value(data.get('conflict_surface'))}")
+    if data.get("graph_authority"):
+        lines.append(f"graph_authority: {_format_value(data.get('graph_authority'))}")
+    if data.get("topology_kind"):
+        lines.append(f"topology_kind: {_format_value(data.get('topology_kind'))}")
+    lines.append("children:")
     children = data.get("children", [])
     if isinstance(children, list):
         for child in children: