@blxzer/pactile 0.5.0

package/dist/templates/shared-hooks/research-end-retrieval-pack.py

@@ -0,0 +1,345 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+Research-end / stop hook: quality-layer retrieval-pack for collected evidence.
+
+Three-layer retrieval ABI (frozen; do not merge back into workflow.md):
+
+| Layer    | Owner                 | This hook                                         |
+| -------- | --------------------- | ------------------------------------------------- |
+| Intent   | context-progressive   | does not own intents                              |
+| Provider | Middleware            | does not take smart-search as a Kernel dependency |
+| Quality  | retrieval-extended    | owner: pack only when collected-evidence exists   |
+
+Runs after an agent turn (Cursor ``stop``, Claude ``Stop``). No research
+artifacts → no-op exit 0 (do not fail, do not write a pack, do not inject
+教战). Collected evidence present → pack via ``build_retrieval_pack.py``
+(input role ``collected-evidence``). The written JSON is not AC Evidence.
+
+Does not change default ``get_context --json`` behavior.
+"""
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+import sys
+import warnings
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+warnings.filterwarnings("ignore")
+
+if sys.platform.startswith("win"):
+    import io as _io
+
+    if hasattr(sys.stdout, "reconfigure"):
+        sys.stdout.reconfigure(encoding="utf-8", errors="replace")  # type: ignore[union-attr]
+    elif hasattr(sys.stdout, "detach"):
+        sys.stdout = _io.TextIOWrapper(  # type: ignore[union-attr]
+            sys.stdout.detach(), encoding="utf-8", errors="replace"
+        )
+
+DIR_WORKFLOW = ".pactile"
+OUTPUT_BASENAME = "retrieval-pack-latest.json"
+MARKER = "<!-- pactile-research-end-pack -->"
+
+ABI_INTENT_OWNER = "context-progressive"
+ABI_PROVIDER_OWNER = "middleware"
+ABI_QUALITY_OWNER = "retrieval-extended"
+ABI_LAYER = "quality"
+INPUT_ROLE = "collected-evidence"
+
+
+def _repo_root(cwd: str) -> Path | None:
+    current = Path(cwd).resolve()
+    for _ in range(32):
+        if (current / DIR_WORKFLOW / "scripts").is_dir():
+            return current
+        if current.parent == current:
+            break
+        current = current.parent
+    return None
+
+
+def _detect_platform(input_data: dict) -> str | None:
+    if isinstance(input_data.get("cursor_version"), str):
+        return "cursor"
+    env_map = {
+        "CLAUDE_PROJECT_DIR": "claude",
+        "CURSOR_PROJECT_DIR": "cursor",
+    }
+    for env_name, platform in env_map.items():
+        if os.environ.get(env_name):
+            return platform
+    script_parts = set(Path(sys.argv[0]).parts)
+    if ".cursor" in script_parts:
+        return "cursor"
+    if ".claude" in script_parts:
+        return "claude"
+    return None
+
+
+def _selected_task(repo_root: Path, input_data: dict) -> str | None:
+    scripts_dir = repo_root / DIR_WORKFLOW / "scripts"
+    if str(scripts_dir) not in sys.path:
+        sys.path.insert(0, str(scripts_dir))
+    try:
+        from common.active_task import resolve_selected_task  # type: ignore[import-not-found]
+    except Exception:
+        return None
+    selected = resolve_selected_task(
+        repo_root,
+        input_data,
+        platform=_detect_platform(input_data),
+    )
+    return selected.task_path if selected else None
+
+
+def _retrieval_extended_active(repo_root: Path, task_dir: Path) -> bool:
+    """Unactivated retrieval-extended → no pack write, no delivery claim."""
+    scripts_dir = repo_root / DIR_WORKFLOW / "scripts"
+    if str(scripts_dir) not in sys.path:
+        sys.path.insert(0, str(scripts_dir))
+    try:
+        from common.ondemand_topology import is_ondemand_module_active  # type: ignore[import-not-found]
+    except Exception:
+        return False
+    return bool(is_ondemand_module_active(task_dir, "retrieval-extended"))
+
+
+def _relpath(path: Path, repo_root: Path) -> str:
+    try:
+        return path.resolve().relative_to(repo_root.resolve()).as_posix()
+    except ValueError:
+        return str(path)
+
+
+def _freshness(path: Path) -> str | None:
+    try:
+        return datetime.fromtimestamp(path.stat().st_mtime, timezone.utc).isoformat()
+    except OSError:
+        return None
+
+
+def collect_evidence_items(task_dir: Path, repo_root: Path) -> list[dict[str, Any]]:
+    """Build collected-evidence items (path + provider + optional freshness)."""
+    items: list[dict[str, Any]] = []
+    research = task_dir / "research"
+    if not research.is_dir():
+        return items
+
+    for child in sorted(research.iterdir(), key=lambda path: path.name):
+        if child.name == OUTPUT_BASENAME:
+            continue
+        if child.is_file() and child.suffix.lower() in {".md", ".json"}:
+            record: dict[str, Any] = {
+                "path": _relpath(child, repo_root),
+                "provider": "task-research",
+            }
+            stamp = _freshness(child)
+            if stamp:
+                record["freshness"] = stamp
+            items.append(record)
+            continue
+        if child.is_dir() and child.name == "smart-search":
+            for run_dir in sorted(child.iterdir(), key=lambda path: path.name):
+                manifest = run_dir / "manifest.json"
+                if not manifest.is_file():
+                    continue
+                record = {
+                    "path": _relpath(manifest, repo_root),
+                    "provider": "smart-search",
+                }
+                stamp = _freshness(manifest)
+                if stamp:
+                    record["freshness"] = stamp
+                items.append(record)
+    return items
+
+
+def _stamp_pack(pack: dict[str, Any], collection_status: str, reason: str) -> dict[str, Any]:
+    stamped = dict(pack)
+    stamped["inputRole"] = INPUT_ROLE
+    stamped["outputRole"] = "retrieval-pack"
+    stamped["abiLayer"] = ABI_LAYER
+    stamped["abiOwner"] = ABI_QUALITY_OWNER
+    stamped["abiIntentOwner"] = ABI_INTENT_OWNER
+    stamped["abiProviderOwner"] = ABI_PROVIDER_OWNER
+    stamped["collectionStatus"] = collection_status
+    stamped["closeEvidenceEligible"] = False
+    stamped["notAcEvidence"] = True
+    stamped["reason"] = reason
+    return stamped
+
+
+def _pack_via_quality_cli(
+    repo_root: Path, items: list[dict[str, Any]]
+) -> dict[str, Any] | None:
+    scripts_dir = repo_root / DIR_WORKFLOW / "scripts"
+    if str(scripts_dir) not in sys.path:
+        sys.path.insert(0, str(scripts_dir))
+    try:
+        from build_retrieval_pack import pack_from_collected_evidence
+    except Exception:
+        return None
+    try:
+        return pack_from_collected_evidence(
+            items,
+            payload={"inputRole": INPUT_ROLE, "items": items},
+            repo_root=repo_root,
+        )
+    except Exception:
+        return None
+
+
+def _pack_via_get_context(repo_root: Path) -> dict[str, Any] | None:
+    script = repo_root / DIR_WORKFLOW / "scripts" / "get_context.py"
+    if not script.is_file():
+        return None
+    env = os.environ.copy()
+    env["PYTHONIOENCODING"] = "utf-8"
+    cmd = [
+        sys.executable,
+        "-W",
+        "ignore",
+        str(script),
+        "--mode",
+        "retrieval-pack",
+        "--json",
+    ]
+    proc = subprocess.run(
+        cmd,
+        cwd=str(repo_root),
+        capture_output=True,
+        text=True,
+        encoding="utf-8",
+        errors="replace",
+        timeout=45,
+        env=env,
+    )
+    if proc.returncode != 0:
+        print(
+            f"[research-end-retrieval-pack] WARN: get_context exit {proc.returncode}: "
+            f"{proc.stderr[:500]}",
+            file=sys.stderr,
+        )
+        return None
+    try:
+        parsed = json.loads(proc.stdout)
+    except json.JSONDecodeError:
+        return None
+    if not isinstance(parsed, dict):
+        return None
+    collection = parsed.get("collection") if isinstance(parsed.get("collection"), dict) else {}
+    total = 0
+    for value in collection.values():
+        if isinstance(value, int):
+            total += value
+    status = "collected" if total > 0 else "empty"
+    reason = (
+        "quality-layer retrieval-pack of collected-evidence; "
+        "not AC Evidence and not Close Evidence"
+        if status == "collected"
+        else (
+            "collected-evidence items were present but pack collection is empty; "
+            "not AC Evidence"
+        )
+    )
+    return _stamp_pack(parsed, status, reason)
+
+
+def _is_collected_pack(pack: dict[str, Any]) -> bool:
+    if pack.get("collectionStatus") == "collected":
+        return True
+    collection = pack.get("collection")
+    if not isinstance(collection, dict):
+        return False
+    return any(isinstance(value, int) and value > 0 for value in collection.values())
+
+
+def _emit(platform: str | None, message: str) -> None:
+    payload: dict[str, Any]
+    if platform == "cursor":
+        payload = {"followup_message": message}
+    else:
+        payload = {
+            "hookSpecificOutput": {
+                "hookEventName": "Stop",
+                "additionalContext": message,
+            },
+        }
+    print(json.dumps(payload, ensure_ascii=False), flush=True)
+
+
+def main() -> int:
+    try:
+        raw = sys.stdin.read()
+        input_data = json.loads(raw) if raw.strip() else {}
+    except json.JSONDecodeError:
+        return 0
+
+    cwd = (
+        input_data.get("cwd")
+        or input_data.get("workspace_roots", [None])[0]
+        or os.getcwd()
+    )
+    if not isinstance(cwd, str):
+        return 0
+
+    repo_root = _repo_root(cwd)
+    if repo_root is None:
+        return 0
+
+    task_ref = _selected_task(repo_root, input_data)
+    if not task_ref:
+        return 0
+
+    task_dir = (repo_root / task_ref).resolve()
+    if not task_dir.is_dir():
+        return 0
+
+    try:
+        if not _retrieval_extended_active(repo_root, task_dir):
+            return 0
+    except Exception:
+        return 0
+
+    items = collect_evidence_items(task_dir, repo_root)
+    if not items:
+        return 0
+
+    pack = _pack_via_quality_cli(repo_root, items)
+    if not pack:
+        pack = _pack_via_get_context(repo_root)
+    if not pack or not _is_collected_pack(pack):
+        return 0
+
+    research_dir = task_dir / "research"
+    research_dir.mkdir(parents=True, exist_ok=True)
+    out_path = research_dir / OUTPUT_BASENAME
+    out_path.write_text(
+        json.dumps(pack, ensure_ascii=False, indent=2) + "\n", encoding="utf-8"
+    )
+
+    selected_n = 0
+    context_pack = pack.get("contextPack")
+    if isinstance(context_pack, dict):
+        selected = context_pack.get("selected")
+        if isinstance(selected, list):
+            selected_n = len(selected)
+
+    rel = out_path.relative_to(repo_root).as_posix()
+    message = (
+        f"{MARKER}\n"
+        f"retrieval-extended quality layer wrote `{rel}` from collected-evidence "
+        f"(contextPack.selected={selected_n}). "
+        f"This retrieval-pack is not AC Evidence and must not be used as Close Evidence."
+    )
+    _emit(_detect_platform(input_data), message)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/dist/templates/shared-hooks/session-start.py

@@ -0,0 +1,355 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+Session Start Hook - Inject the context-progressive Session pack only.
+
+Event Bridge remains a separate earlier `sessionStart` command in hooks.json.
+This hook must not crash: compiler failure is a successful no-op (exit 0).
+"""
+from __future__ import annotations
+
+# IMPORTANT: Suppress all warnings FIRST
+import warnings
+warnings.filterwarnings("ignore")
+
+import importlib.util
+import json
+import os
+import re
+import shlex
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+
+
+def _normalize_windows_shell_path(path_str: str) -> str:
+    """Normalize Unix-style shell paths to real Windows paths.
+
+    On Windows, shells like Git Bash / MSYS2 / Cygwin may report paths like
+    `/d/Users/...` or `/cygdrive/d/Users/...`. `Path.resolve()` will misinterpret
+    these as `D:/d/Users...` on drive D: (or similar), breaking repo root
+    detection.
+
+    This function is intentionally conservative: it only rewrites patterns that
+    unambiguously represent a drive letter mount.
+    """
+    if not isinstance(path_str, str) or not path_str:
+        return path_str
+
+    # Only relevant on Windows; keep other platforms untouched.
+    if not sys.platform.startswith("win"):
+        return path_str
+
+    p = path_str.strip()
+
+    # Already a Windows drive path (C:\... or C:/...)
+    if re.match(r"^[A-Za-z]:[\/]", p):
+        return p
+
+    # MSYS/Git-Bash style: /c/Users/... or /d/Work/...
+    m = re.match(r"^/([A-Za-z])/(.*)", p)
+    if m:
+        drive, rest = m.group(1).upper(), m.group(2)
+        rest = rest.replace('/', '\\')
+        return f"{drive}:\\{rest}"
+
+    # Cygwin style: /cygdrive/c/Users/...
+    m = re.match(r"^/cygdrive/([A-Za-z])/(.*)", p)
+    if m:
+        drive, rest = m.group(1).upper(), m.group(2)
+        rest = rest.replace('/', '\\')
+        return f"{drive}:\\{rest}"
+
+    # WSL mounted drive (sometimes leaked into env): /mnt/c/Users/...
+    m = re.match(r"^/mnt/([A-Za-z])/(.*)", p)
+    if m:
+        drive, rest = m.group(1).upper(), m.group(2)
+        rest = rest.replace('/', '\\')
+        return f"{drive}:\\{rest}"
+
+    return path_str
+
+
+FIRST_REPLY_NOTICE = """<first-reply-notice>
+First visible reply: say once in Chinese that Pactile SessionStart context is loaded, then answer directly.
+This notice is one-shot: do not repeat it after the first assistant reply in the same session.
+</first-reply-notice>"""
+
+# Force UTF-8 on stdin/stdout/stderr on Windows. Default codepage there is
+# cp936 / cp1252 / etc. — non-ASCII content (Chinese task names, prd snippets)
+# both in stdin (hook payload from host CLI) and stdout (our emitted blocks)
+# raises UnicodeDecodeError / UnicodeEncodeError. Equivalent to `python -X utf8`
+# but applied per-stream so we don't depend on host CLI's command wiring.
+if sys.platform.startswith("win"):
+    import io as _io
+    for _stream_name in ("stdin", "stdout", "stderr"):
+        _stream = getattr(sys, _stream_name, None)
+        if _stream is None:
+            continue
+        if hasattr(_stream, "reconfigure"):
+            try:
+                _stream.reconfigure(encoding="utf-8", errors="replace")  # type: ignore[union-attr]
+            except Exception:
+                pass
+        elif hasattr(_stream, "detach"):
+            try:
+                setattr(sys, _stream_name, _io.TextIOWrapper(_stream.detach(), encoding="utf-8", errors="replace"))
+            except Exception:
+                pass
+
+
+def should_skip_injection() -> bool:
+    """Check if any platform's non-interactive flag is set, or if Pactile
+    hooks are explicitly disabled via PACTILE_HOOKS=0 / PACTILE_DISABLE_HOOKS=1.
+    """
+    if os.environ.get("PACTILE_HOOKS") == "0":
+        return True
+    if os.environ.get("PACTILE_DISABLE_HOOKS") == "1":
+        return True
+    non_interactive_vars = [
+        "CLAUDE_NON_INTERACTIVE",
+        "QODER_NON_INTERACTIVE",
+        "CODEBUDDY_NON_INTERACTIVE",
+        "FACTORY_NON_INTERACTIVE",
+        "CURSOR_NON_INTERACTIVE",
+        "GEMINI_NON_INTERACTIVE",
+        "KIRO_NON_INTERACTIVE",
+        "COPILOT_NON_INTERACTIVE",
+    ]
+    return any(os.environ.get(var) == "1" for var in non_interactive_vars)
+
+
+def _detect_platform(input_data: dict) -> str | None:
+    if isinstance(input_data.get("cursor_version"), str):
+        return "cursor"
+    env_map = {
+        "CLAUDE_PROJECT_DIR": "claude",
+        "CURSOR_PROJECT_DIR": "cursor",
+        "CODEBUDDY_PROJECT_DIR": "codebuddy",
+        "FACTORY_PROJECT_DIR": "droid",
+        "GEMINI_PROJECT_DIR": "gemini",
+        "QODER_PROJECT_DIR": "qoder",
+        "KIRO_PROJECT_DIR": "kiro",
+        "COPILOT_PROJECT_DIR": "copilot",
+    }
+    for env_name, platform in env_map.items():
+        if os.environ.get(env_name):
+            return platform
+    script_parts = set(Path(sys.argv[0]).parts)
+    if ".claude" in script_parts:
+        return "claude"
+    if ".cursor" in script_parts:
+        return "cursor"
+    if ".codex" in script_parts:
+        return "codex"
+    if ".gemini" in script_parts:
+        return "gemini"
+    if ".qoder" in script_parts:
+        return "qoder"
+    if ".codebuddy" in script_parts:
+        return "codebuddy"
+    if ".factory" in script_parts:
+        return "droid"
+    if ".kiro" in script_parts:
+        return "kiro"
+    return None
+
+
+def _append_hook_log(pactile_dir: Path, record: dict) -> None:
+    """Side-channel: prove this process ran even if additional_context is dropped."""
+    try:
+        log_dir = pactile_dir / ".runtime" / "hooks"
+        log_dir.mkdir(parents=True, exist_ok=True)
+        payload = {
+            "ts": datetime.now(timezone.utc)
+            .replace(microsecond=0)
+            .isoformat()
+            .replace("+00:00", "Z"),
+            **record,
+        }
+        with (log_dir / "session-start.log").open("a", encoding="utf-8") as handle:
+            handle.write(json.dumps(payload, ensure_ascii=False) + "\n")
+    except Exception:
+        pass
+
+
+def _resolve_pactile_dir(project_dir: Path) -> Path:
+    """Resolve the pactile instance directory for this project.
+
+    Mirrors common/paths.py get_repo_root(): finds the nearest .pactile upward
+    from project_dir. Harness sub-repos without a local .pactile resolve to the
+    harness root instance (thin-connect, 2026-08-16 instance-boundary decision).
+    """
+    current = project_dir
+    while True:
+        if (current / ".pactile").is_dir():
+            return current / ".pactile"
+        if current.parent == current:
+            break
+        current = current.parent
+    return project_dir / ".pactile"
+
+
+def _resolve_context_key(pactile_dir: Path, input_data: dict) -> str | None:
+    scripts_dir = pactile_dir / "scripts"
+    if str(scripts_dir) not in sys.path:
+        sys.path.insert(0, str(scripts_dir))
+    from common.active_task import resolve_context_key  # type: ignore[import-not-found]
+
+    return resolve_context_key(input_data, platform=_detect_platform(input_data))
+
+
+def _persist_context_key_for_bash(context_key: str | None) -> None:
+    """Expose Pactile session identity to later Claude Code Bash commands.
+
+    Claude Code SessionStart hooks can append exports to CLAUDE_ENV_FILE; those
+    variables are then available to Bash tools in the same conversation. Without
+    this bridge, `task.py select` has hook stdin during SessionStart but no
+    session identity when the AI later runs it as a normal shell command.
+    """
+    if not context_key:
+        return
+    env_file = os.environ.get("CLAUDE_ENV_FILE")
+    if not env_file:
+        return
+    try:
+        with open(env_file, "a", encoding="utf-8") as handle:
+            handle.write(f"export PACTILE_CONTEXT_ID={shlex.quote(context_key)}\n")
+    except OSError:
+        pass
+
+
+def _resolve_selected_task(pactile_dir: Path, input_data: dict):
+    scripts_dir = pactile_dir / "scripts"
+    if str(scripts_dir) not in sys.path:
+        sys.path.insert(0, str(scripts_dir))
+    from common.active_task import resolve_selected_task  # type: ignore[import-not-found]
+
+    return resolve_selected_task(
+        pactile_dir.parent,
+        input_data,
+        platform=_detect_platform(input_data),
+    )
+
+
+def _load_session_pack_module(pactile_dir: Path):
+    """Load session_pack.py without executing common/__init__.py."""
+    pack_path = pactile_dir / "scripts" / "common" / "session_pack.py"
+    if not pack_path.is_file():
+        return None
+    spec = importlib.util.spec_from_file_location("pactile_session_pack", pack_path)
+    if spec is None or spec.loader is None:
+        return None
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module
+
+
+def _compile_session_pack_text(pactile_dir: Path, input_data: dict) -> str:
+    """Return compiled Session pack XML, or empty string on any failure."""
+    try:
+        module = _load_session_pack_module(pactile_dir)
+        if module is None:
+            return ""
+        selected_path = None
+        selected_stale = False
+        try:
+            active = _resolve_selected_task(pactile_dir, input_data)
+            selected_path = active.task_path
+            selected_stale = bool(active.stale)
+        except Exception:
+            selected_path = None
+            selected_stale = False
+        fact_gap = os.environ.get("PACTILE_SESSION_FACT_GAP") == "1"
+        pack = module.compile_session_pack_from_pactile(
+            pactile_dir,
+            selected_task_path=selected_path,
+            selected_stale=selected_stale,
+            fact_gap=fact_gap,
+        )
+        rendered = module.render_session_pack(pack)
+        return rendered if isinstance(rendered, str) else ""
+    except Exception:
+        return ""
+
+
+def _emit(context_text: str) -> None:
+    result = {
+        # Claude Code / Qoder / CodeBuddy / Droid / Gemini / Copilot format
+        "hookSpecificOutput": {
+            "hookEventName": "SessionStart",
+            "additionalContext": context_text,
+        },
+        # Cursor sessionStart format (top-level snake_case per Cursor docs)
+        "additional_context": context_text,
+    }
+    print(json.dumps(result, ensure_ascii=False), flush=True)
+
+
+def main():
+    enter_root = Path(_normalize_windows_shell_path(os.getcwd())).resolve()
+    _append_hook_log(_resolve_pactile_dir(enter_root), {"phase": "enter"})
+    if should_skip_injection():
+        _append_hook_log(_resolve_pactile_dir(enter_root), {"phase": "skip"})
+        sys.exit(0)
+
+    try:
+        hook_input = json.loads(sys.stdin.read())
+        if not isinstance(hook_input, dict):
+            hook_input = {}
+    except (json.JSONDecodeError, ValueError):
+        hook_input = {}
+
+    # Try platform-specific env vars, hook cwd, fallback to cwd
+    project_dir_env_vars = [
+        "CLAUDE_PROJECT_DIR",
+        "QODER_PROJECT_DIR",
+        "CODEBUDDY_PROJECT_DIR",
+        "FACTORY_PROJECT_DIR",
+        "CURSOR_PROJECT_DIR",
+        "GEMINI_PROJECT_DIR",
+        "KIRO_PROJECT_DIR",
+        "COPILOT_PROJECT_DIR",
+    ]
+    project_dir = None
+    for var in project_dir_env_vars:
+        val = os.environ.get(var)
+        if val:
+            project_dir = Path(_normalize_windows_shell_path(val)).resolve()
+            break
+    if project_dir is None:
+        project_dir = Path(_normalize_windows_shell_path(hook_input.get("cwd", "."))).resolve()
+
+    pactile_dir = _resolve_pactile_dir(project_dir)
+    try:
+        context_key = _resolve_context_key(pactile_dir, hook_input)
+        _persist_context_key_for_bash(context_key)
+    except Exception:
+        pass
+
+    compiled = _compile_session_pack_text(pactile_dir, hook_input)
+    parts = [FIRST_REPLY_NOTICE]
+    if compiled.strip():
+        parts.append(compiled)
+    text = "\n\n".join(parts)
+    _append_hook_log(
+        pactile_dir,
+        {
+            "phase": "emit",
+            "chars": len(text),
+            "has_session_pack": "<session-pack" in text,
+        },
+    )
+    _emit(text)
+
+
+if __name__ == "__main__":
+    try:
+        main()
+    except Exception:
+        # Hook must never crash the host session.
+        try:
+            _emit(FIRST_REPLY_NOTICE)
+        except Exception:
+            pass
+        sys.exit(0)