@blxzer/pactile 0.5.0

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

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

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

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

@@ -0,0 +1,53 @@
+"""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。"
+    )