@blxzer/cursor-trellis 0.3.5 → 0.4.0

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

@@ -0,0 +1,317 @@
+#!/usr/bin/env python3
+"""Injection budget constants and measurement helpers (P0 channel matrix aligned)."""
+
+from __future__ import annotations
+
+import json
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Literal
+
+RULES_TOTAL_WARN_BYTES = 20_480
+RULES_TOTAL_FAIL_BYTES = 32_768
+AGENTS_CSTL_WARN_BYTES = 4_096
+JSONL_MAX_ENTRIES = 8
+JSONL_MAX_FILE_CHARS = 12_000
+JSONL_MAX_TOTAL_CHARS = 48_000
+
+DISPATCH_DEFAULT_MAX_CHARS: dict[str, int] = {
+    "implement": 96_000,
+    "check": 64_000,
+    "research": 48_000,
+}
+
+DispatchRole = Literal["implement", "check", "research"]
+
+
+@dataclass
+class RuleFileMeasure:
+    path: str
+    bytes: int
+    always_apply: bool
+
+
+@dataclass
+class RulesMeasure:
+    files: list[RuleFileMeasure] = field(default_factory=list)
+
+    @property
+    def always_apply_total_bytes(self) -> int:
+        return sum(f.bytes for f in self.files if f.always_apply)
+
+
+@dataclass
+class AgentsMeasure:
+    path: str
+    total_bytes: int
+    cstl_block_bytes: int
+
+
+@dataclass
+class JsonlMeasure:
+    jsonl_path: str
+    entry_count: int
+    expanded_chars: int
+    skipped: list[str] = field(default_factory=list)
+    loaded_files: list[str] = field(default_factory=list)
+
+
+@dataclass
+class DispatchMeasure:
+    role: str
+    task_rel: str
+    prompt_chars: int
+    warnings: list[str] = field(default_factory=list)
+
+
+@dataclass
+class BudgetReport:
+    rules: RulesMeasure
+    agents: AgentsMeasure | None
+    jsonl: list[JsonlMeasure] = field(default_factory=list)
+    dispatch: DispatchMeasure | None = None
+
+
+def _read_text_bytes(path: Path) -> tuple[str, int]:
+    data = path.read_bytes()
+    try:
+        text = data.decode("utf-8")
+    except UnicodeDecodeError:
+        text = data.decode("utf-8", errors="replace")
+    return text, len(data)
+
+
+def measure_always_apply_rules(repo_root: Path) -> RulesMeasure:
+    rules_dir = repo_root / ".cursor" / "rules"
+    result = RulesMeasure()
+    if not rules_dir.is_dir():
+        return result
+
+    for path in sorted(rules_dir.glob("*.mdc")):
+        text, nbytes = _read_text_bytes(path)
+        always = bool(re.search(r"^alwaysApply:\s*true\s*$", text, re.MULTILINE))
+        result.files.append(
+            RuleFileMeasure(path=str(path.relative_to(repo_root)), bytes=nbytes, always_apply=always)
+        )
+    return result
+
+
+def measure_agents_block(repo_root: Path) -> AgentsMeasure | None:
+    agents_path = repo_root / "AGENTS.md"
+    if not agents_path.is_file():
+        return None
+    text, nbytes = _read_text_bytes(agents_path)
+    cstl_bytes = 0
+    start = text.find("<!-- CSTL:START -->")
+    end = text.find("<!-- CSTL:END -->")
+    if start != -1 and end != -1 and end > start:
+        cstl_bytes = len(text[start : end + len("<!-- CSTL:END -->")].encode("utf-8"))
+    return AgentsMeasure(
+        path="AGENTS.md",
+        total_bytes=nbytes,
+        cstl_block_bytes=cstl_bytes,
+    )
+
+
+def _expand_jsonl_entry(repo_root: Path, file_path: str, entry_type: str) -> list[tuple[str, str]]:
+    if entry_type == "directory":
+        from .subagent_dispatch import read_directory_contents  # lazy import
+
+        return read_directory_contents(str(repo_root), file_path)
+    from .subagent_dispatch import read_file_content
+
+    content = read_file_content(str(repo_root), file_path)
+    if content is None:
+        return []
+    return [(file_path, content)]
+
+
+def measure_jsonl_manifest(
+    repo_root: Path,
+    task_dir: Path,
+    jsonl_name: str,
+    *,
+    apply_budget: bool = True,
+) -> JsonlMeasure:
+    jsonl_path = task_dir / jsonl_name
+    rel_jsonl = str(jsonl_path.relative_to(repo_root)) if jsonl_path.is_file() else jsonl_name
+    measure = JsonlMeasure(jsonl_path=rel_jsonl, entry_count=0, expanded_chars=0)
+    if not jsonl_path.is_file():
+        return measure
+
+    entries: list[tuple[str, str]] = []
+    for line in jsonl_path.read_text(encoding="utf-8").splitlines():
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            item = json.loads(line)
+        except json.JSONDecodeError:
+            continue
+        file_path = item.get("file") or item.get("path")
+        if not file_path:
+            continue
+        entry_type = item.get("type", "file")
+        entries.append((file_path, entry_type))
+
+    measure.entry_count = len(entries)
+    if not apply_budget:
+        for file_path, entry_type in entries:
+            for rel, content in _expand_jsonl_entry(repo_root, file_path, entry_type):
+                measure.loaded_files.append(rel)
+                measure.expanded_chars += len(content)
+        return measure
+
+    total_chars = 0
+    loaded_count = 0
+    for file_path, entry_type in entries:
+        if loaded_count >= JSONL_MAX_ENTRIES:
+            measure.skipped.append(f"{file_path}: entry cap ({JSONL_MAX_ENTRIES})")
+            continue
+        expanded = _expand_jsonl_entry(repo_root, file_path, entry_type)
+        if not expanded:
+            measure.skipped.append(f"{file_path}: missing or empty")
+            continue
+        block_chars = sum(len(content) for _, content in expanded)
+        if block_chars > JSONL_MAX_FILE_CHARS:
+            measure.skipped.append(
+                f"{file_path}: file cap ({block_chars}>{JSONL_MAX_FILE_CHARS} chars)"
+            )
+            continue
+        if total_chars + block_chars > JSONL_MAX_TOTAL_CHARS:
+            measure.skipped.append(
+                f"{file_path}: total cap ({total_chars + block_chars}>{JSONL_MAX_TOTAL_CHARS})"
+            )
+            continue
+        for rel, content in expanded:
+            measure.loaded_files.append(rel)
+            total_chars += len(content)
+        loaded_count += 1
+
+    measure.expanded_chars = total_chars
+    return measure
+
+
+def measure_dispatch_prompt(repo_root: Path, task_dir: Path, role: DispatchRole) -> DispatchMeasure | None:
+    from .subagent_dispatch import build_dispatch_prompt
+
+    prompt, warnings, errors = build_dispatch_prompt(
+        repo_root,
+        task_dir,
+        role,
+        max_chars=DISPATCH_DEFAULT_MAX_CHARS.get(role),
+        require_in_progress=False,
+    )
+    if not prompt:
+        return None
+    try:
+        task_rel = task_dir.relative_to(repo_root).as_posix()
+    except ValueError:
+        task_rel = task_dir.as_posix()
+    return DispatchMeasure(
+        role=role,
+        task_rel=task_rel,
+        prompt_chars=len(prompt),
+        warnings=list(warnings) + [f"error:{e}" for e in errors],
+    )
+
+
+def collect_budget_report(
+    repo_root: Path,
+    *,
+    task_dir: Path | None = None,
+    dispatch_role: DispatchRole | None = None,
+) -> BudgetReport:
+    report = BudgetReport(
+        rules=measure_always_apply_rules(repo_root),
+        agents=measure_agents_block(repo_root),
+    )
+    if task_dir and task_dir.is_dir():
+        for name in ("implement.jsonl", "check.jsonl"):
+            report.jsonl.append(measure_jsonl_manifest(repo_root, task_dir, name))
+        if dispatch_role:
+            report.dispatch = measure_dispatch_prompt(repo_root, task_dir, dispatch_role)
+    return report
+
+
+def budget_violations(report: BudgetReport, *, strict: bool = False) -> list[str]:
+    violations: list[str] = []
+    rules_total = report.rules.always_apply_total_bytes
+    if rules_total > RULES_TOTAL_WARN_BYTES:
+        level = "FAIL" if strict and rules_total > RULES_TOTAL_FAIL_BYTES else "WARN"
+        violations.append(
+            f"{level}: alwaysApply rules total {rules_total} B "
+            f"(warn>{RULES_TOTAL_WARN_BYTES}, fail>{RULES_TOTAL_FAIL_BYTES})"
+        )
+    elif strict and rules_total > RULES_TOTAL_WARN_BYTES:
+        violations.append(
+            f"WARN: alwaysApply rules total {rules_total} B (warn>{RULES_TOTAL_WARN_BYTES})"
+        )
+
+    if report.agents and report.agents.cstl_block_bytes > AGENTS_CSTL_WARN_BYTES:
+        violations.append(
+            f"WARN: AGENTS CSTL block {report.agents.cstl_block_bytes} B "
+            f"(warn>{AGENTS_CSTL_WARN_BYTES})"
+        )
+
+    for jm in report.jsonl:
+        if jm.entry_count > JSONL_MAX_ENTRIES:
+            violations.append(
+                f"WARN: {jm.jsonl_path} has {jm.entry_count} entries (max {JSONL_MAX_ENTRIES})"
+            )
+        if jm.expanded_chars > JSONL_MAX_TOTAL_CHARS:
+            violations.append(
+                f"WARN: {jm.jsonl_path} expanded {jm.expanded_chars} chars "
+                f"(max {JSONL_MAX_TOTAL_CHARS})"
+            )
+
+    if report.dispatch:
+        cap = DISPATCH_DEFAULT_MAX_CHARS.get(report.dispatch.role, 0)
+        if cap and report.dispatch.prompt_chars > cap:
+            violations.append(
+                f"WARN: dispatch {report.dispatch.role} prompt {report.dispatch.prompt_chars} chars "
+                f"(default cap {cap})"
+            )
+
+    return violations
+
+
+def format_budget_report(report: BudgetReport) -> str:
+    lines: list[str] = ["# Injection budget report", ""]
+    lines.append("## alwaysApply rules (.cursor/rules/*.mdc)")
+    for rf in report.rules.files:
+        flag = "alwaysApply" if rf.always_apply else "scoped"
+        lines.append(f"- {rf.path}: {rf.bytes} B ({flag})")
+    lines.append(f"- **Total alwaysApply:** {report.rules.always_apply_total_bytes} B")
+    lines.append("")
+
+    if report.agents:
+        lines.append("## AGENTS.md")
+        lines.append(f"- Total: {report.agents.total_bytes} B")
+        lines.append(f"- CSTL block: {report.agents.cstl_block_bytes} B")
+        lines.append("")
+
+    for jm in report.jsonl:
+        lines.append(f"## {jm.jsonl_path}")
+        lines.append(f"- Entries: {jm.entry_count}")
+        lines.append(f"- Expanded (budgeted): {jm.expanded_chars} chars")
+        if jm.loaded_files:
+            lines.append(f"- Loaded: {', '.join(jm.loaded_files)}")
+        if jm.skipped:
+            lines.append("- Skipped:")
+            for item in jm.skipped:
+                lines.append(f"  - {item}")
+        lines.append("")
+
+    if report.dispatch:
+        lines.append(f"## Layer 2 dispatch ({report.dispatch.role})")
+        lines.append(f"- Task: {report.dispatch.task_rel}")
+        lines.append(f"- Prompt chars: {report.dispatch.prompt_chars}")
+        if report.dispatch.warnings:
+            lines.append("- Warnings:")
+            for w in report.dispatch.warnings:
+                lines.append(f"  - {w}")
+        lines.append("")
+
+    return "\n".join(lines)

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

@@ -12,6 +12,7 @@ import re
 from datetime import datetime, timezone
 from pathlib import Path
 
+from .io import read_json
 from .paths import get_repo_root
 from .task_gates import (
     build_spec_update_scaffold,
@@ -22,6 +23,7 @@ from .task_map import (
     PARENT_TERMINAL_STATES,
     get_child_entry,
     load_task_map,
+    resolve_child_map_id,
     validate_parent_child_integration,
 )
 
@@ -100,7 +102,7 @@ def _child_prompt_section(
     *,
     include_artifacts: bool,
 ) -> str:
-    child_name = child_dir.name
+    child_name = child_entry.get("id") or child_dir.name
     parent_rel = _repo_rel(parent_dir, repo_root)
     child_rel = _repo_rel(child_dir, repo_root)
     state = child_entry.get("state", "open")
@@ -164,12 +166,15 @@ def build_child_prompt(
     """Build an implementation prompt for a linked child task."""
     errors: list[str] = []
     repo_root = get_repo_root()
-    child_name = child_dir.name
 
     parent_json = parent_dir / "task.json"
     if not parent_json.is_file():
         return None, [f"parent task.json missing: {parent_dir}"]
 
+    parent_data = read_json(parent_json) or {}
+    child_data = read_json(child_dir / "task.json") or {}
+    child_name = resolve_child_map_id(parent_data, child_dir, child_data)
+
     data, body = load_task_map(parent_dir)
     if data is None:
         return None, ["parent task-map.md missing or invalid"]
@@ -360,6 +365,141 @@ def _unit_readiness(
     return ("ready" if not blocked else "blocked", blocked)
 
 
+_PACK_GENERATED_RE = re.compile(r"^- Generated:\s*(.+)$", re.MULTILINE)
+_PACK_DASH = r"[\u2014\-]"
+_PACK_UNIT_LINE_RE = re.compile(
+    rf"^- `([^`]+)` {_PACK_DASH} `([^`]+)` {_PACK_DASH} \*\*(ready|blocked)\*\*",
+    re.MULTILINE,
+)
+
+
+def _parse_iso_timestamp(raw: str) -> datetime | None:
+    text = raw.strip()
+    if not text:
+        return None
+    normalized = text[:-1] + "+00:00" if text.endswith("Z") else text
+    try:
+        parsed = datetime.fromisoformat(normalized)
+    except ValueError:
+        try:
+            parsed = datetime.strptime(text, "%Y-%m-%d")
+        except ValueError:
+            return None
+    if parsed.tzinfo is None:
+        return parsed.replace(tzinfo=timezone.utc)
+    return parsed
+
+
+def _parse_pack_generated(pack_text: str) -> datetime | None:
+    match = _PACK_GENERATED_RE.search(pack_text)
+    if not match:
+        return None
+    return _parse_iso_timestamp(match.group(1))
+
+
+def _last_integrate_event_time(body: str) -> datetime | None:
+    last: datetime | None = None
+    for line in body.splitlines():
+        stripped = line.strip()
+        if not stripped.startswith("- "):
+            continue
+        remainder = stripped[2:]
+        parts = remainder.split(" - ", 1)
+        if len(parts) != 2:
+            continue
+        ts_raw, message = parts[0].strip(), parts[1]
+        lowered = message.lower()
+        if "integration state" not in message and "integrate-through" not in lowered:
+            continue
+        parsed = _parse_iso_timestamp(ts_raw)
+        if parsed is not None and (last is None or parsed > last):
+            last = parsed
+    return last
+
+
+def _pack_ready_units(pack_text: str) -> set[str]:
+    ready: set[str] = set()
+    for unit_id, _state, readiness in _PACK_UNIT_LINE_RE.findall(pack_text):
+        if readiness == "ready":
+            ready.add(unit_id)
+    return ready
+
+
+def _expected_pack_ready_units(
+    data: dict,
+    children_by_id: dict[str, dict],
+) -> set[str]:
+    stages, _, _ = _normalize_stages(data)
+    ready: set[str] = set()
+    for stage in stages:
+        for unit in stage.get("units") or []:
+            if not isinstance(unit, str):
+                continue
+            readiness, _ = _unit_readiness(unit, children_by_id)
+            if readiness == "ready":
+                ready.add(unit)
+    return ready
+
+
+def _pack_unit_states_mismatch(
+    pack_text: str,
+    children_by_id: dict[str, dict],
+) -> bool:
+    for unit_id, pack_state, _readiness in _PACK_UNIT_LINE_RE.findall(pack_text):
+        entry = children_by_id.get(unit_id) or {}
+        current_state = entry.get("state", "?")
+        if str(current_state) != pack_state:
+            return True
+    return False
+
+
+def _compute_stale_pack(
+    parent_dir: Path,
+    data: dict,
+    body: str,
+    children_by_id: dict[str, dict],
+) -> bool | None:
+    pack_path = parent_dir / "child-prompts" / "PACK.md"
+    if not pack_path.is_file():
+        return None
+    try:
+        pack_text = pack_path.read_text(encoding="utf-8")
+    except OSError:
+        return None
+
+    generated = _parse_pack_generated(pack_text)
+    if generated is None:
+        return None
+
+    stale = False
+    last_integrate = _last_integrate_event_time(body)
+    if last_integrate is not None and generated < last_integrate:
+        stale = True
+    if _pack_unit_states_mismatch(pack_text, children_by_id):
+        stale = True
+    expected_ready = _expected_pack_ready_units(data, children_by_id)
+    if _pack_ready_units(pack_text) != expected_ready:
+        stale = True
+    return stale
+
+
+def _compute_newly_ready(children_by_id: dict[str, dict]) -> list[str]:
+    ready_ids: list[str] = []
+    for unit_id in sorted(children_by_id):
+        entry = children_by_id[unit_id]
+        if entry.get("state") != "open":
+            continue
+        readiness, _ = _unit_readiness(unit_id, children_by_id)
+        if readiness == "ready":
+            ready_ids.append(unit_id)
+    return ready_ids
+
+
+def _child_prompt_filename(unit_id: str) -> str:
+    """Flat filename for child-prompts (nested slash unit ids use `--`)."""
+    return f"{unit_id.replace('/', '--')}.md"
+
+
 def build_publish_pack(
     parent_dir: Path,
     *,
@@ -442,7 +582,7 @@ def build_publish_pack(
                 if prompt_errors or not prompt:
                     errors.extend(prompt_errors or [f"could not build prompt for `{unit}`"])
                     continue
-                out_name = f"{unit}.md"
+                out_name = _child_prompt_filename(unit)
                 out_rel = f"{parent_rel}/child-prompts/{out_name}"
                 if not dry_run:
                     prompts_dir.mkdir(parents=True, exist_ok=True)
@@ -470,7 +610,7 @@ def build_publish_pack(
                         "",
                     ]
                 )
-                out_name = f"{unit}.md"
+                out_name = _child_prompt_filename(unit)
                 out_rel = f"{parent_rel}/child-prompts/{out_name}"
                 if not dry_run:
                     prompts_dir.mkdir(parents=True, exist_ok=True)
@@ -539,6 +679,9 @@ def build_parent_status_dict(parent_dir: Path) -> dict | None:
 
     children_by_id = _children_by_id(data)
     stages, stage_errors, legacy = _normalize_stages(data)
+    _, body = load_task_map(parent_dir)
+    stale_pack = _compute_stale_pack(parent_dir, data, body, children_by_id)
+    newly_ready = _compute_newly_ready(children_by_id)
 
     stage_rows: list[dict] = []
     for stage in stages:
@@ -597,6 +740,8 @@ def build_parent_status_dict(parent_dir: Path) -> dict | None:
         "integrationQueue": data.get("integration_queue") or [],
         "stageErrors": stage_errors,
         "legacyStages": legacy,
+        "stalePack": stale_pack,
+        "newlyReady": newly_ready,
     }
 
 
@@ -620,6 +765,17 @@ def build_parent_status(parent_dir: Path) -> str:
 
     children_by_id = _children_by_id(data)
     stages, stage_errors, legacy = _normalize_stages(data)
+    _, body = load_task_map(parent_dir)
+    stale_pack = _compute_stale_pack(parent_dir, data, body, children_by_id)
+    newly_ready = _compute_newly_ready(children_by_id)
+    lines.append("## Pack freshness")
+    lines.append("")
+    lines.append(f"- stalePack: {stale_pack}")
+    if newly_ready:
+        lines.append(f"- newlyReady: {', '.join(newly_ready)}")
+    else:
+        lines.append("- newlyReady: (none)")
+    lines.append("")
     lines.append("## Stages")
     lines.append("")
     if stage_errors:
@@ -790,7 +946,7 @@ def build_review_report(
     notes: str | None,
 ) -> tuple[str, list[str], dict]:
     """Build review summary and validate integration transitions for a decision."""
-    child_name = child_dir.name
+    child_name = resolve_child_map_id(parent_data, child_dir, child_data)
     summary = _summarize_handoff(child_dir)
     errors: list[str] = []
     actions: dict = {"integrate": None, "gates": []}