@blxzer/pactile 0.5.0 → 0.6.0-beta.4

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

@@ -1,104 +0,0 @@
-#!/usr/bin/env python3
-"""Deterministic quality-layer ranking for the four V3 retrieval intents."""
-
-from __future__ import annotations
-
-import math
-import unicodedata
-from typing import Any
-
-
-INTENTS = ("exact", "semantic", "structural", "external")
-
-
-def _clamp(value: object, minimum: float = 0, maximum: float = 1) -> float:
-    if isinstance(value, bool) or not isinstance(value, (int, float)) or not math.isfinite(value):
-        return minimum
-    return max(minimum, min(maximum, float(value)))
-
-
-def _normalized_path(value: str) -> str:
-    return unicodedata.normalize("NFC", value.replace("\\", "/")).lower()
-
-
-def score_candidate(candidate: dict[str, Any], intents: list[str]) -> dict[str, Any]:
-    selected = set(intents)
-    score = _clamp(candidate.get("baseScore"), -1000, 1000)
-    reasons: list[str] = []
-    if "exact" in selected and candidate.get("exactMatch") is True:
-        score += 100
-        reasons.append("exact-match")
-    if "semantic" in selected and "semanticScore" in candidate:
-        score += _clamp(candidate.get("semanticScore")) * 40
-        reasons.append("semantic-candidate")
-    if "structural" in selected and candidate.get("structuralMatch") is True:
-        score += 60
-        reasons.append("structural-match")
-    if "external" in selected and "externalFreshness" in candidate:
-        score += _clamp(candidate.get("externalFreshness")) * 30
-        reasons.append("external-freshness-candidate")
-    if candidate.get("sourceReference"):
-        score += 10
-        reasons.append("source-reference-present")
-    if candidate.get("assemblyOnly") is True:
-        score -= 30 if "structural" in selected else 10
-        reasons.append("assembly-only-demotion")
-    return {**candidate, "score": score, "reasons": reasons}
-
-
-def rank_retrieval_result_candidates(
-    candidates: list[dict[str, Any]],
-    *,
-    intents: list[str],
-    top_k: int | None = None,
-    **_compatibility_options: object,
-) -> dict[str, Any]:
-    limit = len(candidates) if top_k is None else max(0, min(top_k, len(candidates)))
-    ranked = [score_candidate(candidate, intents) for candidate in candidates]
-    ranked.sort(
-        key=lambda candidate: (
-            -float(candidate["score"]),
-            _normalized_path(str(candidate.get("path", ""))).encode("utf-8"),
-            int(candidate.get("line", 0)) if isinstance(candidate.get("line", 0), int) else 0,
-        )
-    )
-    return {"ranked": ranked[:limit], "total": len(candidates)}
-
-
-def paged_caller_aggregation(
-    pages: list[dict[str, Any]],
-    *,
-    intents: list[str] | None = None,
-    top_k: int | None = None,
-) -> dict[str, Any]:
-    unique: dict[str, dict[str, Any]] = {}
-    for page in sorted(pages, key=lambda item: int(item.get("page", 0))):
-        candidates = page.get("candidates")
-        if not isinstance(candidates, list):
-            continue
-        for candidate in candidates:
-            if not isinstance(candidate, dict):
-                continue
-            key = f"{_normalized_path(str(candidate.get('path', '')))}:{candidate.get('line', 0)}"
-            unique.setdefault(key, candidate)
-    return rank_retrieval_result_candidates(
-        list(unique.values()), intents=intents or ["structural"], top_k=top_k
-    )
-
-
-def intent_ids_from_router_envelope(plan: dict[str, Any]) -> list[str]:
-    raw = plan.get("intents")
-    if not isinstance(raw, list):
-        return []
-    return [item for item in raw if isinstance(item, str) and item in INTENTS]
-
-
-def result_layer_ranking_hint(intents: list[str], *, locale: str = "zh") -> str:
-    if not any(intent in INTENTS for intent in intents):
-        return ""
-    if locale != "zh":
-        return (
-            "**Result quality:** ranking scores only order candidates; source, Git, or "
-            "repeatable-test corroboration is still required.\n"
-        )
-    return "**结果质量：** 排序分数只用于候选排序，仍必须用源码、Git 或可重复测试佐证。\n"

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

@@ -1,166 +0,0 @@
-"""Classify observed retrieval execution without selecting an implementation."""
-
-from __future__ import annotations
-
-import re
-from dataclasses import dataclass
-
-
-EXACT_PATTERNS = (
-    re.compile(r"^grep$", re.I),
-    re.compile(r"^rg$", re.I),
-    re.compile(r"ripgrep", re.I),
-    re.compile(r"find.?files?", re.I),
-    re.compile(r"^glob$", re.I),
-)
-SEMANTIC_PATTERNS = (
-    re.compile(r"semantic", re.I),
-    re.compile(r"concept", re.I),
-    re.compile(r"meaning", re.I),
-)
-STRUCTURAL_PATTERNS = (
-    re.compile(r"structural", re.I),
-    re.compile(r"callers?", re.I),
-    re.compile(r"callees?", re.I),
-    re.compile(r"dependenc", re.I),
-    re.compile(r"call.?graph", re.I),
-)
-EXTERNAL_PATTERNS = (
-    re.compile(r"external", re.I),
-    re.compile(r"^web", re.I),
-    re.compile(r"browser", re.I),
-    re.compile(r"http.?fetch", re.I),
-    re.compile(r"remote.?search", re.I),
-)
-READ_PATTERNS = (
-    re.compile(r"^read$", re.I),
-    re.compile(r"read.?file", re.I),
-    re.compile(r"get-content", re.I),
-    re.compile(r"source.?read", re.I),
-)
-GIT_PATTERNS = (
-    re.compile(r"^git(?:\s|$)", re.I),
-    re.compile(r"git.?diff", re.I),
-    re.compile(r"git.?log", re.I),
-    re.compile(r"git.?show", re.I),
-)
-TEST_PATTERNS = (
-    re.compile(r"test", re.I),
-    re.compile(r"vitest", re.I),
-    re.compile(r"pytest", re.I),
-    re.compile(r"check", re.I),
-)
-ROUTER_PATTERNS = (
-    re.compile(r"route.?codebase.?retrieval", re.I),
-    re.compile(r"retrieval.?plan", re.I),
-)
-
-
-def _matches(name: str, patterns: tuple[re.Pattern[str], ...]) -> bool:
-    return any(pattern.search(name) for pattern in patterns)
-
-
-@dataclass(frozen=True)
-class ClassifiedToolCalls:
-    exact_count: int
-    semantic_count: int
-    structural_count: int
-    external_count: int
-    read_count: int
-    git_count: int
-    test_count: int
-    router_cli_invoked: bool
-    unclassified_count: int
-    # Read-only aliases retained for pre-V3 evidence readers.
-    tools_called: list[str]
-    grep_count: int
-    codegraph_attempted: bool
-    codegraph_executed: bool
-    semantic_attempted: bool
-    semantic_executed: bool
-    platform_semantic_executed: bool
-    fast_context_count: int = 0
-    cursor_fast_context_misuse: bool = False
-
-
-def classify_tool_calls(
-    raw: list[str],
-    **_compatibility_options: object,
-) -> ClassifiedToolCalls:
-    exact = semantic = structural = external = read = git = test = unclassified = 0
-    router = False
-    for raw_name in raw:
-        name = raw_name.strip() if isinstance(raw_name, str) else ""
-        if not name:
-            unclassified += 1
-            continue
-        classified = False
-        if _matches(name, EXACT_PATTERNS):
-            exact += 1
-            classified = True
-        if _matches(name, SEMANTIC_PATTERNS):
-            semantic += 1
-            classified = True
-        if _matches(name, STRUCTURAL_PATTERNS):
-            structural += 1
-            classified = True
-        if _matches(name, EXTERNAL_PATTERNS):
-            external += 1
-            classified = True
-        if _matches(name, READ_PATTERNS):
-            read += 1
-            classified = True
-        if _matches(name, GIT_PATTERNS):
-            git += 1
-            classified = True
-        if _matches(name, TEST_PATTERNS):
-            test += 1
-            classified = True
-        if _matches(name, ROUTER_PATTERNS):
-            router = True
-            classified = True
-        if not classified:
-            unclassified += 1
-    return ClassifiedToolCalls(
-        exact_count=exact,
-        semantic_count=semantic,
-        structural_count=structural,
-        external_count=external,
-        read_count=read,
-        git_count=git,
-        test_count=test,
-        router_cli_invoked=router,
-        unclassified_count=unclassified,
-        tools_called=list(raw),
-        grep_count=exact,
-        codegraph_attempted=structural > 0,
-        codegraph_executed=structural > 0,
-        semantic_attempted=semantic > 0,
-        semantic_executed=semantic > 0,
-        platform_semantic_executed=semantic > 0,
-    )
-
-
-def structural_routes_in_plan(intents: list[str]) -> bool:
-    return "structural" in intents
-
-
-def semantic_routes_in_plan(intents: list[str]) -> bool:
-    return "semantic" in intents
-
-
-def platform_semantic_route_order(steps: list[dict[str, object]]) -> int | None:
-    for step in steps:
-        if step.get("intent") == "semantic" and step.get("kind") == "provider-request":
-            order = step.get("order")
-            return order if isinstance(order, int) else None
-    return None
-
-
-def observed_intent_count(classified: ClassifiedToolCalls, intent: str) -> int:
-    return {
-        "exact": classified.exact_count,
-        "semantic": classified.semantic_count,
-        "structural": classified.structural_count,
-        "external": classified.external_count,
-    }.get(intent, 0)

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

@@ -1,285 +0,0 @@
-"""
-Safe git-add helpers for Pactile-owned paths.
-
-Why this module exists
-----------------------
-A real user incident: a project's `.gitignore` listed `.pactile/` (company-wide
-template / personal habit). When `add_session.py` and `task.py archive` ran
-their auto-commit and `git add` failed with `ignored by .gitignore`, the AI
-agent driving the workflow "fixed" it by retrying with
-`git add -f .pactile/` — which fan-out-included every ignored subtree
-(`.pactile/.backup-*/`, `.pactile/worktrees/`, `.pactile/.template-hashes.json`,
-`.pactile/.runtime/`), committing 548 files / 83474 lines of caches/backups.
-
-Design
-------
-- Scripts only stage SPECIFIC product paths (journal files, index.md, the
-  current task dir, the archive dir). Never the whole `.pactile/` tree.
-- If plain `git add <specific>` fails with "ignored by", DO NOT retry with
-  ``-f``. The presence of `.pactile/` in `.gitignore` is treated as user
-  intent ("keep .pactile/ local-only"). The script warns and skips the
-  auto-commit; users who want auto-staging can either fix their `.gitignore`
-  or set ``session_auto_commit: false`` and manage git themselves.
-- The warning includes a negative example: ``Do NOT use `git add -f .pactile/` ...``
-  so any AI rereading the log doesn't reinvent the bug.
-
-History note: 0.5.10 introduced an automatic ``git add -f`` retry on the
-specific paths. That was reverted in 0.5.11 — auto-forcing into a tree the
-user had gitignored violates user intent even when the path list is narrow.
-The wider-grain forbidden command stays forbidden, and the narrow-grain auto
-``-f`` is gone too.
-"""
-
-from __future__ import annotations
-
-import sys
-from pathlib import Path
-
-from .git import run_git
-from .paths import (
-    DIR_ARCHIVE,
-    DIR_TASKS,
-    DIR_WORKFLOW,
-    DIR_WORKSPACE,
-    FILE_JOURNAL_PREFIX,
-    get_developer,
-)
-
-
-# Paths under .pactile/ that must NEVER be auto-staged. Listed here so the
-# warning to the user can show concrete subpaths to ignore individually
-# instead of ignoring the whole `.pactile/` tree.
-PACTILE_IGNORED_SUBPATHS = (
-    ".pactile/.backup-*",
-    ".pactile/worktrees/",
-    ".pactile/.template-hashes.json",
-    ".pactile/.runtime/",
-    ".pactile/.cache/",
-)
-
-
-def safe_pactile_paths_to_add(repo_root: Path) -> list[str]:
-    """Return the list of repo-relative paths the auto-commit should stage.
-
-    Only includes paths that exist on disk so callers don't pass non-existent
-    arguments to git. The caller is responsible for `git diff --cached`
-    checking afterwards.
-
-    Included:
-      - .pactile/workspace/<developer>/journal-*.md
-      - .pactile/workspace/<developer>/index.md
-      - .pactile/tasks/<task-dir>/   (every active task directory)
-      - .pactile/tasks/archive/      (whole archive subtree, if present)
-
-    Excluded (intentionally — these must not be staged):
-      - .pactile/.backup-*, .pactile/worktrees/,
-        .pactile/.template-hashes.json, .pactile/.runtime/, .pactile/.cache/
-    """
-    paths: list[str] = []
-
-    # Workspace journal files + index.md
-    developer = get_developer(repo_root)
-    if developer:
-        ws = repo_root / DIR_WORKFLOW / DIR_WORKSPACE / developer
-        if ws.is_dir():
-            for f in sorted(ws.glob(f"{FILE_JOURNAL_PREFIX}*.md")):
-                if f.is_file():
-                    paths.append(
-                        f"{DIR_WORKFLOW}/{DIR_WORKSPACE}/{developer}/{f.name}"
-                    )
-            index_md = ws / "index.md"
-            if index_md.is_file():
-                paths.append(
-                    f"{DIR_WORKFLOW}/{DIR_WORKSPACE}/{developer}/index.md"
-                )
-
-    # Active tasks: each direct child of tasks/ that is a directory and not
-    # the archive root. The archive subtree is added as a single path below.
-    tasks_dir = repo_root / DIR_WORKFLOW / DIR_TASKS
-    if tasks_dir.is_dir():
-        for child in sorted(tasks_dir.iterdir()):
-            if not child.is_dir():
-                continue
-            if child.name == DIR_ARCHIVE:
-                continue
-            paths.append(f"{DIR_WORKFLOW}/{DIR_TASKS}/{child.name}")
-
-        archive_dir = tasks_dir / DIR_ARCHIVE
-        if archive_dir.is_dir():
-            paths.append(f"{DIR_WORKFLOW}/{DIR_TASKS}/{DIR_ARCHIVE}")
-
-    return paths
-
-
-def safe_archive_paths_to_add(
-    repo_root: Path,
-    task_name: str | None = None,
-    modified_children: list[str] | None = None,
-) -> list[str]:
-    """Return paths to stage after `task.py archive`.
-
-    Scoped to ONLY the paths the archive operation actually touched:
-
-      - the archive subtree (where the freshly-moved task lives)
-      - the source task directory (for source-side deletes; caller pairs
-        this with `git rm --cached` since `git add` won't stage deletes
-        for a path that no longer exists in the working tree)
-      - any child task directories whose `task.json` was edited to drop
-        the archived parent (parent-children relationship update)
-
-    This narrow scope avoids "scope creep" — dirty changes in OTHER
-    active task dirs (parallel-window edits) are NOT bundled into the
-    archive commit. Callers handle each kind of change in its own
-    commit boundary.
-
-    Backwards-compat: with no arguments, the function walks the whole
-    `.pactile/tasks/` subtree the old way (active tasks + archive). New
-    callers should always pass `task_name`.
-    """
-    paths: list[str] = []
-    tasks_dir = repo_root / DIR_WORKFLOW / DIR_TASKS
-    if not tasks_dir.is_dir():
-        return paths
-
-    archive_dir = tasks_dir / DIR_ARCHIVE
-
-    if task_name is not None:
-        # Narrow scope — only paths that still exist on disk (so
-        # `git add` doesn't choke on the moved-away source). The caller
-        # handles the source-side deletes via `git rm --cached`
-        # explicitly.
-        if archive_dir.is_dir():
-            paths.append(
-                f"{DIR_WORKFLOW}/{DIR_TASKS}/{DIR_ARCHIVE}"
-            )
-        for child_name in modified_children or []:
-            paths.append(f"{DIR_WORKFLOW}/{DIR_TASKS}/{child_name}")
-        return paths
-
-    # Legacy wide scope (no task_name): preserve old behavior so callers
-    # that have not been updated keep working.
-    if archive_dir.is_dir():
-        paths.append(f"{DIR_WORKFLOW}/{DIR_TASKS}/{DIR_ARCHIVE}")
-    for child in sorted(tasks_dir.iterdir()):
-        if not child.is_dir():
-            continue
-        if child.name == DIR_ARCHIVE:
-            continue
-        paths.append(f"{DIR_WORKFLOW}/{DIR_TASKS}/{child.name}")
-    return paths
-
-
-def _stderr_indicates_ignored(stderr: str) -> bool:
-    """git add error indicates the path is excluded by .gitignore."""
-    if not stderr:
-        return False
-    lowered = stderr.lower()
-    return "ignored by" in lowered
-
-
-def safe_git_add(
-    paths: list[str], repo_root: Path
-) -> tuple[bool, bool, str]:
-    """Run `git add` on specific paths; never retry with -f.
-
-    Returns ``(success, used_force, stderr)``. The ``used_force`` field is
-    kept for signature compatibility with the 0.5.10 implementation but is
-    always ``False`` — we never auto-force.
-
-    Behavior:
-      - No paths passed → success, no force, empty stderr.
-      - Plain ``git add -- <paths>`` succeeds → return success.
-      - Plain fails (any reason — ignored or otherwise) → return failure with
-        the stderr. Callers should inspect the stderr (see
-        :func:`print_gitignore_warning`) and skip the auto-commit.
-    """
-    if not paths:
-        return True, False, ""
-
-    rc, _, err = run_git(["add", "--", *paths], cwd=repo_root)
-    if rc == 0:
-        return True, False, ""
-    return False, False, err
-
-
-def print_gitignore_warning(paths: list[str]) -> None:
-    """Explain to the user (and any AI reading the log) what to do.
-
-    CRITICAL: includes the negative example
-    ``Do NOT use `git add -f .pactile/``` — agents reading the warning are
-    known to invent that command, which fans out to ignored caches/backups.
-    """
-    print(
-        "[WARN] git add failed because .pactile/ paths are ignored by your .gitignore.",
-        file=sys.stderr,
-    )
-    print(
-        "[WARN] Skipping auto-commit. The journal/task files were still written to disk;",
-        file=sys.stderr,
-    )
-    print(
-        "[WARN] git was not touched.",
-        file=sys.stderr,
-    )
-    print("[WARN]", file=sys.stderr)
-    print(
-        "[WARN] Pactile manages these specific paths and they should be tracked:",
-        file=sys.stderr,
-    )
-    if paths:
-        for p in paths:
-            print(f"[WARN]   {p}", file=sys.stderr)
-    else:
-        print(
-            "[WARN]   .pactile/workspace/<developer>/{journal-*.md,index.md}",
-            file=sys.stderr,
-        )
-        print(
-            "[WARN]   .pactile/tasks/<task-dir>/",
-            file=sys.stderr,
-        )
-        print(
-            "[WARN]   .pactile/tasks/archive/",
-            file=sys.stderr,
-        )
-    print("[WARN]", file=sys.stderr)
-    print(
-        "[WARN] Recommended: change your .gitignore from `.pactile/` to specific",
-        file=sys.stderr,
-    )
-    print(
-        "[WARN] subpaths that should remain ignored, e.g.:",
-        file=sys.stderr,
-    )
-    for sub in PACTILE_IGNORED_SUBPATHS:
-        print(f"[WARN]   {sub}", file=sys.stderr)
-    print("[WARN]", file=sys.stderr)
-    print(
-        "[WARN] Or, if you intentionally keep .pactile/ local-only, set in",
-        file=sys.stderr,
-    )
-    print(
-        "[WARN] .pactile/config.yaml:",
-        file=sys.stderr,
-    )
-    print(
-        "[WARN]   session_auto_commit: false",
-        file=sys.stderr,
-    )
-    print(
-        "[WARN] so the scripts skip git entirely and you can review / commit",
-        file=sys.stderr,
-    )
-    print(
-        "[WARN] manually with `git status` / `git add` / `git commit`.",
-        file=sys.stderr,
-    )
-    print("[WARN]", file=sys.stderr)
-    print(
-        "[WARN] Do NOT use `git add -f .pactile/` — it pulls in backups, worktrees,",
-        file=sys.stderr,
-    )
-    print(
-        "[WARN] and runtime caches that should never be committed.",
-        file=sys.stderr,
-    )

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

@@ -1,53 +0,0 @@
-"""Neutral semantic-intent reminder for V3 retrieval plans."""
-
-from __future__ import annotations
-
-from typing import Any
-
-
-def platform_semantic_order_from_envelope(envelope: dict[str, Any]) -> int | None:
-    steps = envelope.get("steps")
-    if not isinstance(steps, list):
-        return None
-    for step in steps:
-        if (
-            isinstance(step, dict)
-            and step.get("intent") == "semantic"
-            and step.get("kind") == "provider-request"
-        ):
-            order = step.get("order")
-            return order if isinstance(order, int) else None
-    return None
-
-
-def semantic_compliance_gate_hint(
-    envelope: dict[str, Any], *, locale: str = "zh"
-) -> str:
-    steps = envelope.get("steps")
-    if not isinstance(steps, list):
-        return ""
-    step = next(
-        (
-            item
-            for item in steps
-            if isinstance(item, dict)
-            and item.get("intent") == "semantic"
-            and item.get("kind") == "provider-request"
-        ),
-        None,
-    )
-    if not isinstance(step, dict) or not isinstance(step.get("providerRequirement"), dict):
-        return ""
-    requirement = step["providerRequirement"]
-    if locale != "zh":
-        return (
-            f"**Semantic retrieval gate:** step #{step['order']} requests a project-resolved "
-            f"semantic capability at minimum assurance `{envelope.get('minimumAssurance')}` "
-            f"(status: `{requirement.get('status')}`). Treat every result as a candidate until source, Git, "
-            "or repeatable-test corroboration succeeds."
-        )
-    return (
-        f"**语义检索门控：** 第 {step['order']} 步请求由项目 Resolver 解析的语义能力，"
-        f"最低 assurance 为 `{envelope.get('minimumAssurance')}`（状态：`{requirement.get('status')}`）。"
-        "所有结果在源码、Git 或可重复测试完成佐证前都只能作为 candidate。"
-    )