@blxzer/pactile 0.5.0

package/dist/templates/pactile/scripts/common/context_pack.py

@@ -0,0 +1,371 @@
+#!/usr/bin/env python3
+"""
+Build bounded retrieval context packs from scored evidence.
+
+Pure functions only. Does not run retrieval commands, Smart Search, network
+calls, MCP tools, or codebase search.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from typing import Any
+
+from common.retrieval_evidence import (
+    STATUS_DEGRADED,
+    STATUS_FAILED,
+    STATUS_MISSING,
+    STATUS_NOT_CONFIGURED,
+    STATUS_OK,
+    VALIDATION_CANDIDATE,
+    VALIDATION_FAILED,
+    VALIDATION_UNAVAILABLE,
+)
+
+PACK_VERSION = 1
+PACK_SOURCE = "retrieval-context-pack"
+
+METADATA_ONLY_TOKENS = 80
+MIN_CONTENT_TOKENS = 40
+CHARS_PER_TOKEN = 4
+
+SELECTABLE_STATUSES = frozenset({STATUS_OK, STATUS_DEGRADED})
+UNAVAILABLE_STATUSES = frozenset(
+    {STATUS_FAILED, STATUS_NOT_CONFIGURED, STATUS_MISSING}
+)
+
+OMIT_UNAVAILABLE = "unavailable evidence excluded from pack body"
+OMIT_BUDGET = "outside budget after higher-ranked evidence"
+OMIT_CANDIDATE_BUDGET = "candidate evidence skipped due to budget"
+OMIT_DIAGNOSTICS_ONLY = "diagnostic-only evidence excluded from pack body"
+
+
+def build_context_pack(
+    scored_evidence: dict[str, Any],
+    *,
+    max_items: int | None = None,
+    max_estimated_tokens: int | None = None,
+    include_diagnostics: bool = False,
+) -> dict[str, object]:
+    """Partition scored evidence into selected and omitted pack items."""
+    items = list_value(scored_evidence.get("items"))
+    normalized_items = [item for item in items if isinstance(item, dict)]
+
+    budget_limits = {
+        "maxItems": max_items,
+        "maxEstimatedTokens": max_estimated_tokens,
+    }
+
+    if not normalized_items:
+        return _empty_pack(budget_limits)
+
+    selected: list[dict[str, object]] = []
+    omitted: list[dict[str, object]] = []
+    warnings: list[str] = []
+    estimated_tokens = 0
+    budget_exceeded = False
+
+    for item in normalized_items:
+        status = string_value(item.get("status")) or STATUS_MISSING
+        validation_state = string_value(item.get("validationState")) or ""
+        estimate = estimate_item_tokens(item)
+        selectable = _is_selectable(
+            status=status,
+            validation_state=validation_state,
+            include_diagnostics=include_diagnostics,
+        )
+
+        if not selectable:
+            omitted.append(
+                _build_omitted_item(
+                    item,
+                    reason=_unavailable_reason(status, validation_state),
+                )
+            )
+            warnings.extend(_collect_item_warnings(item, status))
+            continue
+
+        if _would_exceed_budget(
+            selected_count=len(selected),
+            estimated_tokens=estimated_tokens,
+            next_item_tokens=estimate["estimatedTokens"],
+            max_items=max_items,
+            max_estimated_tokens=max_estimated_tokens,
+        ):
+            budget_exceeded = True
+            reason = (
+                OMIT_CANDIDATE_BUDGET
+                if validation_state == VALIDATION_CANDIDATE
+                else OMIT_BUDGET
+            )
+            omitted.append(_build_omitted_item(item, reason=reason))
+            continue
+
+        selected.append(_build_selected_item(item, estimate))
+        estimated_tokens += int(estimate["estimatedTokens"])
+
+    if budget_exceeded:
+        warnings.append("budget limits caused evidence omission")
+
+    return {
+        "version": PACK_VERSION,
+        "source": PACK_SOURCE,
+        "budget": {
+            **budget_limits,
+            "estimatedTokens": estimated_tokens,
+            "itemsUsed": len(selected),
+        },
+        "selected": selected,
+        "omitted": omitted,
+        "warnings": normalize_messages(warnings),
+        "summary": {
+            "totalInput": len(normalized_items),
+            "selectedCount": len(selected),
+            "omittedCount": len(omitted),
+            "budgetExceeded": budget_exceeded,
+        },
+    }
+
+
+def estimate_item_tokens(item: dict[str, Any]) -> dict[str, object]:
+    """Estimate conservative token usage for one scored evidence item."""
+    text_parts: list[str] = []
+    for key in ("content", "summary", "snippet"):
+        value = string_value(item.get(key))
+        if value:
+            text_parts.append(value)
+
+    snippets = list_value(item.get("snippets"))
+    for snippet in snippets:
+        if isinstance(snippet, str):
+            text_parts.append(snippet)
+        elif isinstance(snippet, dict):
+            for field in ("text", "body", "content"):
+                value = string_value(snippet.get(field))
+                if value:
+                    text_parts.append(value)
+
+    if not text_parts:
+        title = string_value(item.get("title")) or ""
+        reasons = list_value(item.get("reasons"))
+        text_parts.extend(str(reason) for reason in reasons if reason)
+        if title:
+            text_parts.append(title)
+        metadata_only = True
+        estimated = METADATA_ONLY_TOKENS
+    else:
+        metadata_only = False
+        combined = "\n".join(text_parts)
+        estimated = max(MIN_CONTENT_TOKENS, len(combined) // CHARS_PER_TOKEN + 20)
+
+    return {
+        "estimatedTokens": estimated,
+        "metadataOnly": metadata_only,
+    }
+
+
+def _is_selectable(
+    *,
+    status: str,
+    validation_state: str,
+    include_diagnostics: bool,
+) -> bool:
+    if status in UNAVAILABLE_STATUSES:
+        return include_diagnostics
+    if validation_state in {VALIDATION_UNAVAILABLE, VALIDATION_FAILED}:
+        return include_diagnostics
+    if status in SELECTABLE_STATUSES:
+        return True
+    if validation_state == VALIDATION_CANDIDATE:
+        return status == STATUS_OK or status == STATUS_DEGRADED
+    return False
+
+
+def _would_exceed_budget(
+    *,
+    selected_count: int,
+    estimated_tokens: int,
+    next_item_tokens: int,
+    max_items: int | None,
+    max_estimated_tokens: int | None,
+) -> bool:
+    if max_items is not None and selected_count >= max_items:
+        return True
+    if max_estimated_tokens is not None:
+        return estimated_tokens + next_item_tokens > max_estimated_tokens
+    return False
+
+
+def _build_selected_item(
+    item: dict[str, Any],
+    estimate: dict[str, object],
+) -> dict[str, object]:
+    reasons = list_value(item.get("reasons"))
+    top_reason = string_value(reasons[0]) if reasons else None
+    selected: dict[str, object] = {
+        "source": string_value(item.get("source")) or "",
+        "reference": string_value(item.get("reference")) or "",
+        "title": string_value(item.get("title")) or "",
+        "score": int_value(item.get("score")),
+        "status": string_value(item.get("status")) or "",
+        "validationState": string_value(item.get("validationState")) or "",
+        "estimatedTokens": estimate["estimatedTokens"],
+        "metadataOnly": estimate["metadataOnly"],
+        "reason": top_reason or "selected as highest-ranked usable evidence",
+    }
+    return selected
+
+
+def _build_omitted_item(item: dict[str, Any], *, reason: str) -> dict[str, object]:
+    reasons = list_value(item.get("reasons"))
+    warnings = list_value(item.get("warnings"))
+    omitted: dict[str, object] = {
+        "source": string_value(item.get("source")) or "",
+        "reference": string_value(item.get("reference")) or "",
+        "title": string_value(item.get("title")) or "",
+        "score": int_value(item.get("score")),
+        "status": string_value(item.get("status")) or "",
+        "validationState": string_value(item.get("validationState")) or "",
+        "reason": reason,
+    }
+    if reasons:
+        omitted["reasons"] = [str(value) for value in reasons[:3]]
+    if warnings:
+        omitted["warnings"] = [str(value) for value in warnings[:3]]
+    return omitted
+
+
+def _unavailable_reason(status: str, validation_state: str) -> str:
+    if status in UNAVAILABLE_STATUSES:
+        return f"{OMIT_UNAVAILABLE}: status {status}"
+    if validation_state in {VALIDATION_UNAVAILABLE, VALIDATION_FAILED}:
+        return f"{OMIT_UNAVAILABLE}: validationState {validation_state}"
+    return OMIT_DIAGNOSTICS_ONLY
+
+
+def _collect_item_warnings(item: dict[str, Any], status: str) -> list[str]:
+    warnings = [str(value) for value in list_value(item.get("warnings")) if value]
+    if status in UNAVAILABLE_STATUSES and not warnings:
+        warnings.append(f"omitted unavailable evidence with status {status}")
+    return warnings
+
+
+def _empty_pack(budget_limits: dict[str, int | None]) -> dict[str, object]:
+    return {
+        "version": PACK_VERSION,
+        "source": PACK_SOURCE,
+        "budget": {
+            **budget_limits,
+            "estimatedTokens": 0,
+            "itemsUsed": 0,
+        },
+        "selected": [],
+        "omitted": [],
+        "warnings": [],
+        "summary": {
+            "totalInput": 0,
+            "selectedCount": 0,
+            "omittedCount": 0,
+            "budgetExceeded": False,
+        },
+    }
+
+
+def normalize_messages(values: list[str]) -> list[str]:
+    seen: set[str] = set()
+    normalized: list[str] = []
+    for value in values:
+        text = " ".join(str(value).split()).strip()
+        if not text or text in seen:
+            continue
+        seen.add(text)
+        normalized.append(text[:200])
+    return normalized
+
+
+def parse_args(argv: list[str] | None = None) -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description="Build a bounded retrieval context pack from scored evidence JSON.",
+    )
+    parser.add_argument(
+        "--input",
+        required=True,
+        help="Path to scored evidence JSON (score_evidence_bundle output).",
+    )
+    parser.add_argument(
+        "--max-items",
+        type=int,
+        default=None,
+        help="Maximum number of selected evidence items.",
+    )
+    parser.add_argument(
+        "--max-estimated-tokens",
+        type=int,
+        default=None,
+        help="Maximum estimated token budget for selected items.",
+    )
+    parser.add_argument(
+        "--include-diagnostics",
+        action="store_true",
+        help="Include failed/unavailable evidence in selected output when budget allows.",
+    )
+    parser.add_argument(
+        "--json",
+        action="store_true",
+        help="Emit JSON to stdout.",
+    )
+    return parser.parse_args(argv)
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = parse_args(argv)
+    try:
+        with open(args.input, encoding="utf-8") as handle:
+            scored_evidence = json.load(handle)
+    except (OSError, json.JSONDecodeError) as error:
+        print(f"context pack error: {error}", file=sys.stderr)
+        return 1
+
+    if not isinstance(scored_evidence, dict):
+        print("context pack error: input must be a JSON object", file=sys.stderr)
+        return 1
+
+    pack = build_context_pack(
+        scored_evidence,
+        max_items=args.max_items,
+        max_estimated_tokens=args.max_estimated_tokens,
+        include_diagnostics=args.include_diagnostics,
+    )
+
+    if args.json:
+        print(json.dumps(pack, indent=2, ensure_ascii=False))
+    else:
+        print(json.dumps(pack, ensure_ascii=False))
+    return 0
+
+
+def list_value(value: Any) -> list[Any]:
+    return value if isinstance(value, list) else []
+
+
+def string_value(value: Any) -> str | None:
+    if isinstance(value, str):
+        stripped = value.strip()
+        return stripped or None
+    return None
+
+
+def int_value(value: Any, default: int = 0) -> int:
+    if isinstance(value, bool):
+        return int(value)
+    if isinstance(value, int):
+        return value
+    if isinstance(value, float):
+        return int(value)
+    return default
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

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

@@ -0,0 +1,31 @@
+"""Legacy import-path shim for host-neutral retrieval planning.
+
+V3 never reads process or user-global state to select a capability. Concrete
+capability discovery belongs to the project resolver and adapters.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+ENV_UNKNOWN = "unknown"
+CursorRetrievalEnv = str
+
+
+def detect_cursor_retrieval_env_info() -> dict[str, Any]:
+    return {"env": ENV_UNKNOWN, "source": "neutral-compat", "detail": None}
+
+
+def detect_cursor_retrieval_env() -> CursorRetrievalEnv:
+    return ENV_UNKNOWN
+
+
+def semantic_route_spec(_env: CursorRetrievalEnv) -> dict[str, object]:
+    """Return a neutral requirement for legacy consumers."""
+    return {
+        "commands": [],
+        "rationale_suffix": " Capability binding is deferred to the project resolver.",
+        "platformNative": False,
+        "semanticBackend": None,
+    }

package/dist/templates/pactile/scripts/common/developer.py

@@ -0,0 +1,190 @@
+#!/usr/bin/env python3
+"""
+Developer management utilities.
+
+Provides:
+    init_developer     - Initialize developer
+    ensure_developer   - Ensure developer is initialized (exit if not)
+    show_developer_info - Show developer information
+"""
+
+from __future__ import annotations
+
+import sys
+from datetime import datetime
+from pathlib import Path
+
+from .paths import (
+    DIR_WORKFLOW,
+    DIR_WORKSPACE,
+    DIR_TASKS,
+    FILE_DEVELOPER,
+    FILE_JOURNAL_PREFIX,
+    get_repo_root,
+    get_developer,
+    check_developer,
+)
+
+
+# =============================================================================
+# Developer Initialization
+# =============================================================================
+
+def init_developer(name: str, repo_root: Path | None = None) -> bool:
+    """Initialize developer.
+
+    Creates:
+        - .pactile/.developer file with developer info
+        - .pactile/workspace/<name>/ directory structure
+        - Initial journal file and index.md
+
+    Args:
+        name: Developer name.
+        repo_root: Repository root path. Defaults to auto-detected.
+
+    Returns:
+        True on success, False on error.
+    """
+    if not name:
+        print("Error: developer name is required", file=sys.stderr)
+        return False
+
+    if repo_root is None:
+        repo_root = get_repo_root()
+
+    dev_file = repo_root / DIR_WORKFLOW / FILE_DEVELOPER
+    workspace_dir = repo_root / DIR_WORKFLOW / DIR_WORKSPACE / name
+
+    # Create .developer file
+    initialized_at = datetime.now().isoformat()
+    try:
+        dev_file.write_text(
+            f"name={name}\ninitialized_at={initialized_at}\n",
+            encoding="utf-8"
+        )
+    except (OSError, IOError) as e:
+        print(f"Error: Failed to create .developer file: {e}", file=sys.stderr)
+        return False
+
+    # Create workspace directory structure
+    try:
+        workspace_dir.mkdir(parents=True, exist_ok=True)
+    except (OSError, IOError) as e:
+        print(f"Error: Failed to create workspace directory: {e}", file=sys.stderr)
+        return False
+
+    # Create initial journal file
+    journal_file = workspace_dir / f"{FILE_JOURNAL_PREFIX}1.md"
+    if not journal_file.exists():
+        today = datetime.now().strftime("%Y-%m-%d")
+        journal_content = f"""# Journal - {name} (Part 1)
+
+> AI development session journal
+> Started: {today}
+
+---
+
+"""
+        try:
+            journal_file.write_text(journal_content, encoding="utf-8")
+        except (OSError, IOError) as e:
+            print(f"Error: Failed to create journal file: {e}", file=sys.stderr)
+            return False
+
+    # Create index.md with markers for auto-update
+    index_file = workspace_dir / "index.md"
+    if not index_file.exists():
+        index_content = f"""# Workspace Index - {name}
+
+> Journal tracking for AI development sessions.
+
+---
+
+## Current Status
+
+<!-- @@@auto:current-status -->
+- **Active File**: `journal-1.md`
+- **Total Sessions**: 0
+- **Last Active**: -
+<!-- @@@/auto:current-status -->
+
+---
+
+## Active Documents
+
+<!-- @@@auto:active-documents -->
+| File | Lines | Status |
+|------|-------|--------|
+| `journal-1.md` | ~0 | Active |
+<!-- @@@/auto:active-documents -->
+
+---
+
+## Session History
+
+<!-- @@@auto:session-history -->
+| # | Date | Title | Commits | Branch |
+|---|------|-------|---------|--------|
+<!-- @@@/auto:session-history -->
+
+---
+
+## Notes
+
+- Sessions are appended to journal files
+- New journal file created when current exceeds 2000 lines
+- Use `add_session.py` to record sessions
+"""
+        try:
+            index_file.write_text(index_content, encoding="utf-8")
+        except (OSError, IOError) as e:
+            print(f"Error: Failed to create index.md: {e}", file=sys.stderr)
+            return False
+
+    print(f"Developer initialized: {name}")
+    print(f"  .developer file: {dev_file}")
+    print(f"  Workspace dir: {workspace_dir}")
+
+    return True
+
+
+def ensure_developer(repo_root: Path | None = None) -> None:
+    """Ensure developer is initialized, exit if not.
+
+    Args:
+        repo_root: Repository root path. Defaults to auto-detected.
+    """
+    if repo_root is None:
+        repo_root = get_repo_root()
+
+    if not check_developer(repo_root):
+        print("Error: Developer not initialized.", file=sys.stderr)
+        print(f"Run: python3 ./{DIR_WORKFLOW}/scripts/init_developer.py <your-name>", file=sys.stderr)
+        sys.exit(1)
+
+
+def show_developer_info(repo_root: Path | None = None) -> None:
+    """Show developer information.
+
+    Args:
+        repo_root: Repository root path. Defaults to auto-detected.
+    """
+    if repo_root is None:
+        repo_root = get_repo_root()
+
+    developer = get_developer(repo_root)
+
+    if not developer:
+        print("Developer: (not initialized)")
+    else:
+        print(f"Developer: {developer}")
+        print(f"Workspace: {DIR_WORKFLOW}/{DIR_WORKSPACE}/{developer}/")
+        print(f"Tasks: {DIR_WORKFLOW}/{DIR_TASKS}/")
+
+
+# =============================================================================
+# Main Entry (for testing)
+# =============================================================================
+
+if __name__ == "__main__":
+    show_developer_info()