@blxzer/pactile 0.5.0

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

@@ -0,0 +1,194 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+Workflow Phase Extraction.
+
+Convenience reader for the human-overview copy of `.pactile/workflow.md`.
+That file is not the runtime SSOT — Kernel extras and `task.json` are.
+
+Extracts step-level content from .pactile/workflow.md and optionally filters
+platform-specific blocks.
+
+Platform marker syntax in workflow.md:
+
+    [Claude Code, Cursor, ...]
+    agent-capable content
+    [/Claude Code, Cursor, ...]
+
+Provides:
+    get_phase_index   - Extract the Phase Index section (no --step)
+    get_step          - Extract a single step (#### X.X) section
+    filter_platform   - Strip platform blocks that don't include the given name
+"""
+
+from __future__ import annotations
+
+import re
+
+from .paths import DIR_WORKFLOW, get_repo_root
+
+
+def _workflow_md_path():
+    return get_repo_root() / DIR_WORKFLOW / "workflow.md"
+
+# Match a line that *is* a platform marker: "[A, B, C]" or "[/A, B, C]"
+_MARKER_RE = re.compile(r"^\[(/?)([A-Za-z][^\[\]]*)\]\s*$")
+
+# Step heading: "#### 1.0 Title" or "#### 1.0 ..."
+_STEP_HEADING_RE = re.compile(r"^####\s+(\d+\.\d+)\b.*$")
+
+# Phase Index starts here; Phase 1/2/3 step bodies follow; ends at Breadcrumbs.
+_PHASE_INDEX_HEADING = "## Phase Index"
+
+
+def _read_workflow() -> str:
+    path = _workflow_md_path()
+    if not path.exists():
+        raise FileNotFoundError(f"workflow.md not found: {path}")
+    return path.read_text(encoding="utf-8")
+
+
+def _parse_marker(line: str) -> tuple[bool, list[str]] | None:
+    """Parse a platform marker line.
+
+    Returns:
+        (is_closing, [platform_names]) if line is a marker, else None.
+    """
+    m = _MARKER_RE.match(line)
+    if not m:
+        return None
+    is_closing = m.group(1) == "/"
+    names = [p.strip() for p in m.group(2).split(",") if p.strip()]
+    return is_closing, names
+
+
+def get_phase_index() -> str:
+    """Return the compact Phase Index summary from workflow.md.
+
+    SessionStart and no-step phase context use this small summary as their
+    orientation payload. Detailed Phase 1/2/3 instructions are loaded with
+    ``get_step`` on demand. ``[workflow-state:STATUS]`` tag blocks are
+    consumed by the per-turn hook, so they're stripped from this output.
+    """
+    text = _read_workflow()
+    lines = text.splitlines()
+
+    start: int | None = None
+    end: int | None = None
+    for i, line in enumerate(lines):
+        stripped = line.strip()
+        if start is None and stripped == _PHASE_INDEX_HEADING:
+            start = i
+            continue
+        if start is not None and stripped == "## Phase 1: Plan":
+            end = i
+            break
+
+    if start is None:
+        return ""
+    if end is None:
+        end = len(lines)
+
+    section = "\n".join(lines[start:end]).rstrip()
+    # Strip [workflow-state:STATUS]...[/workflow-state:STATUS] blocks since
+    # they're injected separately by inject-workflow-state.py per-turn.
+    import re as _re
+    tag_re = _re.compile(
+        r"\[workflow-state:([A-Za-z0-9_-]+)\]\s*\n.*?\n\s*\[/workflow-state:\1\]\n?",
+        _re.DOTALL,
+    )
+    return tag_re.sub("", section).rstrip() + "\n"
+
+
+def get_step(step_id: str) -> str:
+    """Return the `#### X.X` section matching step_id (header + body).
+
+    Body ends at the next `####` or `---` or `##` heading (whichever comes first).
+    """
+    text = _read_workflow()
+    lines = text.splitlines()
+
+    start: int | None = None
+    for i, line in enumerate(lines):
+        m = _STEP_HEADING_RE.match(line)
+        if m and m.group(1) == step_id:
+            start = i
+            break
+    if start is None:
+        return ""
+
+    end: int = len(lines)
+    for j in range(start + 1, len(lines)):
+        line = lines[j]
+        if line.startswith("#### "):
+            end = j
+            break
+        if line.startswith("## "):
+            end = j
+            break
+        # Horizontal rule at column 0
+        if line.strip() == "---":
+            end = j
+            break
+
+    return "\n".join(lines[start:end]).rstrip() + "\n"
+
+
+def _platform_matches(platform: str, block_names: list[str]) -> bool:
+    """Case-insensitive fuzzy match: accept 'cursor' or 'Cursor'."""
+    needle = platform.lower().replace("-", "").replace("_", "").replace(" ", "")
+    for name in block_names:
+        hay = name.lower().replace("-", "").replace("_", "").replace(" ", "")
+        if needle == hay:
+            return True
+    return False
+
+
+def resolve_effective_platform(platform: str, config: dict) -> str:
+    """Return the platform name unchanged (Cursor-only fork)."""
+    _ = config
+    return platform
+
+
+def filter_platform(content: str, platform: str) -> str:
+    """Keep lines outside any `[...]` block + lines inside blocks that include platform.
+
+    Marker lines themselves are dropped from the output.
+    """
+    lines = content.splitlines()
+    out: list[str] = []
+
+    in_block = False
+    keep_block = False
+
+    for line in lines:
+        marker = _parse_marker(line)
+        if marker is not None:
+            is_closing, names = marker
+            if not is_closing:
+                in_block = True
+                keep_block = _platform_matches(platform, names)
+            else:
+                in_block = False
+                keep_block = False
+            continue  # drop the marker line itself
+
+        if in_block:
+            if keep_block:
+                out.append(line)
+            continue
+        out.append(line)
+
+    # Collapse runs of 3+ blank lines that may arise from dropped markers
+    collapsed: list[str] = []
+    blank_run = 0
+    for line in out:
+        if line.strip() == "":
+            blank_run += 1
+            if blank_run <= 2:
+                collapsed.append(line)
+        else:
+            blank_run = 0
+            collapsed.append(line)
+
+    return "\n".join(collapsed).rstrip() + "\n"

package/dist/templates/pactile/scripts/compile_session_pack.py

@@ -0,0 +1,15 @@
+#!/usr/bin/env python3
+"""Compile a five-layer Session pack (`context-progressive`).
+
+Usage:
+    python compile_session_pack.py --json
+    python compile_session_pack.py --json --task .pactile/tasks/<dir>
+"""
+
+from __future__ import annotations
+
+from common.session_pack import main
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/dist/templates/pactile/scripts/cursor_retrieval_probe.py

@@ -0,0 +1,64 @@
+#!/usr/bin/env python3
+"""Compatibility probe for the neutral Pactile retrieval V3 contract.
+
+The probe performs no host discovery. It checks that each canonical intent
+produces a deterministic plan and reports unresolved provider requirements as
+data for the project resolver.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+from typing import cast
+
+from common.codebase_retrieval_router import route_codebase_retrieval
+
+
+def build_report() -> dict[str, object]:
+    probes: list[dict[str, object]] = []
+    for intent in ("exact", "semantic", "structural", "external"):
+        first = route_codebase_retrieval(
+            f"probe {intent}", intents=[intent], minimum_assurance="best-effort", required_evidence_kinds=[]
+        )
+        second = route_codebase_retrieval(
+            f"probe {intent}", intents=[intent], minimum_assurance="best-effort", required_evidence_kinds=[]
+        )
+        probes.append(
+            {
+                "intent": intent,
+                "status": "pass" if first == second else "fail",
+                "fingerprint": first["fingerprint"],
+                "stopReasons": first["stopReasons"],
+            }
+        )
+    return {
+        "schemaVersion": 3,
+        "probeKind": "contract-only",
+        "hostDiscoveryPerformed": False,
+        "probes": probes,
+    }
+
+
+def parse_args(argv: list[str] | None = None) -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--json", action="store_true", help="Emit JSON (default).")
+    parser.add_argument("--out", type=Path, help="Optional report output path.")
+    return parser.parse_args(argv)
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = parse_args(argv)
+    report = build_report()
+    rendered = json.dumps(report, ensure_ascii=False, indent=2)
+    if args.out:
+        args.out.parent.mkdir(parents=True, exist_ok=True)
+        args.out.write_text(rendered + "\n", encoding="utf-8")
+    print(rendered)
+    probes = cast(list[dict[str, object]], report["probes"])
+    return 0 if all(probe["status"] == "pass" for probe in probes) else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/dist/templates/pactile/scripts/cursor_retrieval_probe_prompt.md

@@ -0,0 +1,33 @@
+# Pactile retrieval V3 — manual resolver probe
+
+This compatibility asset probes the neutral request/resolver boundary. It does
+not ask the planner to discover or select a host tool.
+
+## Procedure
+
+1. Generate a V3 plan with one of the four intents: `exact`, `semantic`,
+   `structural`, or `external`.
+2. For every `provider-request` step, pass its `providerRequirement` unchanged
+   to the project resolver.
+3. Record only the returned M0 resolution contract and its repeatable evidence
+   references. Do not insert an implementation identity into the plan.
+4. Treat every returned item as a candidate until source, Git, or repeatable
+   test corroboration succeeds.
+
+## Result form
+
+```text
+RETRIEVAL V3 RESOLVER PROBE
+intent: exact|semantic|structural|external
+plan_fingerprint: sha256:<hex>
+resolver_status: ready|degraded|unavailable|unsupported|not-requested
+minimum_assurance: best-effort|evidence-backed|verified
+evidence_refs: <logical references, or none>
+corroboration: source-reference|git-evidence|repeatable-test|none
+verdict: pass|degraded|fail
+notes: <bounded observations>
+```
+
+A `degraded`, `unavailable`, or `unsupported` result is valid plan data. It must
+produce the corresponding generic stop reason; it must never trigger planner-
+side selection of another implementation.

package/dist/templates/pactile/scripts/generate_dispatch_prompt.py

@@ -0,0 +1,182 @@
+#!/usr/bin/env python3
+"""
+CLI Layer 2 — PRIMARY (guaranteed) context path for pactile-* Task dispatch.
+
+Usage:
+    python ./.pactile/scripts/generate_dispatch_prompt.py --agent research
+    python ./.pactile/scripts/generate_dispatch_prompt.py --agent implement --task .pactile/tasks/06-23-subagent-smoke
+    python ./.pactile/scripts/generate_dispatch_prompt.py --agent research --repo-root d:/MyHarness
+
+Outputs the complete dispatch prompt to stdout. The main session MUST capture
+this output and pass it as the `prompt` parameter to
+`Task(subagent_type=pactile-*, prompt=<generated>)`. This is the ONLY
+guaranteed context channel for custom Task subagents on Cursor.
+
+Hook injection (`preToolUse` / `additional_context`) is best-effort only
+(Cursor #158452; hook does not fire for Task tool in Cursor 3.8.22). Do not
+treat hook-only injection as a substitute for this CLI path.
+
+The generated prompt carries:
+  - Role identity ("You are the Pactile Research/Implement/Check Agent")
+  - Write scope constraints (Write ALLOWED / Write FORBIDDEN)
+  - Recursion guard
+  - Dynamic context (prd.md, design.md, implement.md, spec tree, jsonl files)
+
+Task path resolution:
+  - `--task <path>` is the **primary fallback** when no selected-task pointer exists
+    (e.g. `task.py select` failed due to missing session identity).
+  - When `--task` is omitted, auto-detect via selected pointer is **best-effort** only —
+    dispatch scripts do not hard-depend on a persisted selection.
+"""
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(
+        description="Generate a complete Pactile subagent dispatch prompt."
+    )
+    parser.add_argument(
+        "--agent",
+        required=True,
+        choices=["research", "implement", "check"],
+        help="Subagent role to generate prompt for.",
+    )
+    parser.add_argument(
+        "--task",
+        default=None,
+        help="Task directory path (absolute or relative to repo root). "
+        "Primary fallback when no selected-task pointer exists. "
+        "If omitted, auto-detect via selected pointer is best-effort only.",
+    )
+    parser.add_argument(
+        "--repo-root",
+        default=None,
+        help="Repository root path. If omitted, auto-detect via .pactile or .git.",
+    )
+    parser.add_argument(
+        "--finish",
+        action="store_true",
+        help="Use finish context (check agent only, final pre-PR verification).",
+    )
+    parser.add_argument(
+        "--max-chars",
+        type=int,
+        default=None,
+        help="Truncate injected context at this character count. "
+        "When omitted, uses role default from injection-budget-guide.",
+    )
+    args = parser.parse_args()
+
+    # Resolve repo root
+    if args.repo_root:
+        repo_root = Path(args.repo_root).resolve()
+    else:
+        repo_root = _find_repo_root(Path.cwd())
+        if not repo_root:
+            print("ERROR: could not find repo root (no .pactile or .git upward)", file=sys.stderr)
+            return 1
+
+    from common.paths import DIR_WORKFLOW  # type: ignore[import-not-found]
+
+    # Make scripts importable — workspace root first (subagent_dispatch.py lives there),
+    # then repo_root's own scripts (may be a subproject with different common/)
+    workspace_root = _find_workspace_root(repo_root, DIR_WORKFLOW)
+    if workspace_root and workspace_root != repo_root:
+        ws_scripts = workspace_root / DIR_WORKFLOW / "scripts"
+        if str(ws_scripts) not in sys.path:
+            sys.path.insert(0, str(ws_scripts))
+
+    scripts_dir = repo_root / DIR_WORKFLOW / "scripts"
+    if str(scripts_dir) not in sys.path:
+        sys.path.insert(1, str(scripts_dir))
+
+    from common.subagent_dispatch import build_dispatch_prompt  # type: ignore[import-not-found]
+    from common.injection_budget import DISPATCH_DEFAULT_MAX_CHARS  # type: ignore[import-not-found]
+
+    # Resolve task directory
+    if args.task:
+        task_dir = Path(args.task)
+        if not task_dir.is_absolute():
+            task_dir = repo_root / task_dir
+        task_dir = task_dir.resolve()
+    else:
+        task_dir = _resolve_selected_task(repo_root)
+        if not task_dir:
+            print(
+                "ERROR: no --task specified and no selected task found. "
+                "Run `python ./.pactile/scripts/task.py select <task>` first.",
+                file=sys.stderr,
+            )
+            return 1
+
+    if not task_dir.is_dir():
+        print(f"ERROR: task directory not found: {task_dir}", file=sys.stderr)
+        return 1
+
+    max_chars = args.max_chars
+    if max_chars is None:
+        max_chars = DISPATCH_DEFAULT_MAX_CHARS.get(args.agent)
+
+    prompt, warnings, errors = build_dispatch_prompt(
+        repo_root,
+        task_dir,
+        args.agent,
+        finish=args.finish,
+        max_chars=max_chars,
+        require_in_progress=False,
+    )
+
+    for w in warnings:
+        print(f"WARN: {w}", file=sys.stderr)
+    for e in errors:
+        print(f"ERROR: {e}", file=sys.stderr)
+
+    if not prompt:
+        print("ERROR: failed to generate prompt (see errors above)", file=sys.stderr)
+        return 1
+
+    # Output the prompt to stdout — the caller captures this
+    print(prompt)
+    return 0
+
+
+def _find_repo_root(start: Path) -> Path | None:
+    current = start.resolve()
+    while current != current.parent:
+        if (current / ".pactile").is_dir() or (current / ".git").exists():
+            return current
+        current = current.parent
+    return None
+
+
+def _find_workspace_root(start: Path, dir_workflow: str) -> Path | None:
+    """Find the outermost directory with workflow dir (workspace root, not subproject)."""
+    found = None
+    current = start.resolve()
+    while current != current.parent:
+        if (current / dir_workflow).is_dir():
+            found = current
+        current = current.parent
+    return found
+
+
+def _resolve_selected_task(repo_root: Path) -> Path | None:
+    try:
+        from common.active_task import resolve_selected_task  # type: ignore[import-not-found]
+        result = resolve_selected_task(repo_root, {}, platform="cursor")
+        if result.task_path:
+            task_path = Path(result.task_path)
+            if not task_path.is_absolute():
+                task_path = repo_root / task_path
+            return task_path
+    except Exception:
+        pass
+    return None
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/dist/templates/pactile/scripts/get_context.py

@@ -0,0 +1,19 @@
+#!/usr/bin/env python3
+"""
+Get Session Context for AI Agent.
+
+Usage:
+    python3 get_context.py                              Output context in text format
+    python3 get_context.py --json                       Output context in JSON format
+    python3 get_context.py --mode lite --json           Personal Lite budgeted pack
+    python3 get_context.py --mode session --json        Five-layer Session pack (context-progressive)
+    python3 get_context.py --mode retrieval-pack --json Output scored retrieval pack JSON
+"""
+
+from __future__ import annotations
+
+from common.git_context import main
+
+
+if __name__ == "__main__":
+    main()

package/dist/templates/pactile/scripts/get_developer.py

@@ -0,0 +1,26 @@
+#!/usr/bin/env python3
+"""
+Get current developer name.
+
+This is a wrapper that uses common/paths.py
+"""
+
+from __future__ import annotations
+
+import sys
+
+from common.paths import get_developer
+
+
+def main() -> None:
+    """CLI entry point."""
+    developer = get_developer()
+    if developer:
+        print(developer)
+    else:
+        print("Developer not initialized", file=sys.stderr)
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()