@blxzer/pactile 0.5.0 → 0.6.0-beta.2

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

@@ -1,371 +0,0 @@
-#!/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

@@ -1,31 +0,0 @@
-"""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

@@ -1,190 +0,0 @@
-#!/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()