@blxzer/pactile 0.5.0

package/dist/templates/pactile/scripts/hooks/linear_sync.py

@@ -0,0 +1,243 @@
+#!/usr/bin/env python3
+"""Linear sync hook for Pactile task lifecycle.
+
+Syncs task events to Linear via the `linearis` CLI.
+
+Usage (called automatically by task.py hooks):
+    python3 .pactile/scripts/hooks/linear_sync.py create
+    python3 .pactile/scripts/hooks/linear_sync.py start
+    python3 .pactile/scripts/hooks/linear_sync.py archive
+
+Manual usage:
+    TASK_JSON_PATH=.pactile/tasks/<name>/task.json python3 .pactile/scripts/hooks/linear_sync.py sync
+
+Environment:
+    TASK_JSON_PATH  - Absolute path to task.json (set by task.py)
+
+Configuration:
+    .pactile/hooks.local.json  - Local config (gitignored), example:
+    {
+      "linear": {
+        "team": "TEAM_KEY",
+        "project": "Project Name",
+        "assignees": {
+          "dev-name": "linear-user-id"
+        }
+      }
+    }
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+# ─── Configuration ────────────────────────────────────────────────────────────
+
+# Pactile priority → Linear priority (1=Urgent, 2=High, 3=Medium, 4=Low)
+PRIORITY_MAP = {"P0": 1, "P1": 2, "P2": 3, "P3": 4}
+
+# Linear status names (must match your team's workflow)
+STATUS_IN_PROGRESS = "In Progress"
+STATUS_DONE = "Done"
+
+
+def _load_config() -> dict:
+    """Load local hook config from .pactile/hooks.local.json."""
+    task_json_path = os.environ.get("TASK_JSON_PATH", "")
+    if task_json_path:
+        # Walk up from task.json to find .pactile/
+        pactile_dir = Path(task_json_path).parent.parent.parent
+    else:
+        pactile_dir = Path(".pactile")
+
+    config_path = pactile_dir / "hooks.local.json"
+    try:
+        with open(config_path, encoding="utf-8") as f:
+            return json.load(f)
+    except (OSError, json.JSONDecodeError):
+        return {}
+
+
+CONFIG = _load_config()
+LINEAR_CFG = CONFIG.get("linear", {})
+
+TEAM = LINEAR_CFG.get("team", "")
+PROJECT = LINEAR_CFG.get("project", "")
+ASSIGNEE_MAP = LINEAR_CFG.get("assignees", {})
+
+# ─── Helpers ──────────────────────────────────────────────────────────────────
+
+
+def _read_task() -> tuple[dict, str]:
+    path = os.environ.get("TASK_JSON_PATH", "")
+    if not path:
+        print("TASK_JSON_PATH not set", file=sys.stderr)
+        sys.exit(1)
+    with open(path, encoding="utf-8") as f:
+        return json.load(f), path
+
+
+def _write_task(data: dict, path: str) -> None:
+    with open(path, "w", encoding="utf-8") as f:
+        json.dump(data, f, indent=2, ensure_ascii=False)
+        f.write("\n")
+
+
+def _linearis(*args: str) -> dict | None:
+    result = subprocess.run(
+        ["linearis", *args],
+        capture_output=True,
+        text=True,
+        encoding="utf-8",
+        errors="replace",
+    )
+    if result.returncode != 0:
+        print(f"linearis error: {result.stderr.strip()}", file=sys.stderr)
+        sys.exit(1)
+    stdout = result.stdout.strip()
+    if stdout:
+        return json.loads(stdout)
+    return None
+
+
+def _get_linear_issue(task: dict) -> str | None:
+    meta = task.get("meta")
+    if isinstance(meta, dict):
+        return meta.get("linear_issue")
+    return None
+
+
+# ─── Actions ──────────────────────────────────────────────────────────────────
+
+
+def cmd_create() -> None:
+    if not TEAM:
+        print("No linear.team configured in hooks.local.json", file=sys.stderr)
+        sys.exit(1)
+
+    task, path = _read_task()
+
+    # Skip if already linked
+    if _get_linear_issue(task):
+        print(f"Already linked: {_get_linear_issue(task)}")
+        return
+
+    title = task.get("title") or task.get("name") or "Untitled"
+    args = ["issues", "create", title, "--team", TEAM]
+
+    # Map priority
+    priority = PRIORITY_MAP.get(task.get("priority", ""), 0)
+    if priority:
+        args.extend(["-p", str(priority)])
+
+    # Set project
+    if PROJECT:
+        args.extend(["--project", PROJECT])
+
+    # Assign to Linear user
+    assignee = task.get("assignee", "")
+    linear_user_id = ASSIGNEE_MAP.get(assignee)
+    if linear_user_id:
+        args.extend(["--assignee", linear_user_id])
+
+    # Link to parent's Linear issue if available
+    parent_issue = _resolve_parent_linear_issue(task)
+    if parent_issue:
+        args.extend(["--parent-ticket", parent_issue])
+
+    result = _linearis(*args)
+    if result and "identifier" in result:
+        if not isinstance(task.get("meta"), dict):
+            task["meta"] = {}
+        task["meta"]["linear_issue"] = result["identifier"]
+        _write_task(task, path)
+        print(f"Created Linear issue: {result['identifier']}")
+
+
+def cmd_start() -> None:
+    task, _ = _read_task()
+    issue = _get_linear_issue(task)
+    if not issue:
+        return
+    _linearis("issues", "update", issue, "-s", STATUS_IN_PROGRESS)
+    print(f"Updated {issue} -> {STATUS_IN_PROGRESS}")
+    cmd_sync()
+
+
+def cmd_archive() -> None:
+    task, _ = _read_task()
+    issue = _get_linear_issue(task)
+    if not issue:
+        return
+    _linearis("issues", "update", issue, "-s", STATUS_DONE)
+    print(f"Updated {issue} -> {STATUS_DONE}")
+
+
+def cmd_sync() -> None:
+    """Sync prd.md content to Linear issue description."""
+    task, _ = _read_task()
+    issue = _get_linear_issue(task)
+    if not issue:
+        print("No linear_issue in meta, run create first", file=sys.stderr)
+        sys.exit(1)
+
+    # Find prd.md next to task.json
+    task_json_path = os.environ.get("TASK_JSON_PATH", "")
+    prd_path = Path(task_json_path).parent / "prd.md"
+    if not prd_path.is_file():
+        print(f"No prd.md found at {prd_path}", file=sys.stderr)
+        sys.exit(1)
+
+    description = prd_path.read_text(encoding="utf-8").strip()
+    _linearis("issues", "update", issue, "-d", description)
+    print(f"Synced prd.md to {issue} description")
+
+
+# ─── Parent Issue Resolution ─────────────────────────────────────────────────
+
+
+def _resolve_parent_linear_issue(task: dict) -> str | None:
+    """Find parent task's Linear issue identifier."""
+    parent_name = task.get("parent")
+    if not parent_name:
+        return None
+
+    task_json_path = os.environ.get("TASK_JSON_PATH", "")
+    if not task_json_path:
+        return None
+
+    current_task_dir = Path(task_json_path).parent
+    tasks_dir = current_task_dir.parent
+    parent_json = tasks_dir / parent_name / "task.json"
+
+    if parent_json.exists():
+        try:
+            with open(parent_json, encoding="utf-8") as f:
+                parent_task = json.load(f)
+            return _get_linear_issue(parent_task)
+        except (json.JSONDecodeError, OSError):
+            pass
+    return None
+
+
+# ─── Main ─────────────────────────────────────────────────────────────────────
+
+if __name__ == "__main__":
+    action = sys.argv[1] if len(sys.argv) > 1 else ""
+    actions = {
+        "create": cmd_create,
+        "start": cmd_start,
+        "archive": cmd_archive,
+        "sync": cmd_sync,
+    }
+    fn = actions.get(action)
+    if fn:
+        fn()
+    else:
+        print(f"Unknown action: {action}", file=sys.stderr)
+        print(f"Valid actions: {', '.join(actions)}", file=sys.stderr)
+        sys.exit(1)

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

@@ -0,0 +1,51 @@
+#!/usr/bin/env python3
+"""
+Initialize developer for workflow.
+
+Usage:
+    python3 init_developer.py <developer-name>
+
+This creates:
+    - .pactile/.developer file with developer info
+    - .pactile/workspace/<name>/ directory structure
+"""
+
+from __future__ import annotations
+
+import sys
+
+from common.paths import (
+    DIR_WORKFLOW,
+    FILE_DEVELOPER,
+    get_developer,
+)
+from common.developer import init_developer
+
+
+def main() -> None:
+    """CLI entry point."""
+    if len(sys.argv) < 2:
+        print(f"Usage: {sys.argv[0]} <developer-name>")
+        print()
+        print("Example:")
+        print(f"  {sys.argv[0]} john")
+        sys.exit(1)
+
+    name = sys.argv[1]
+
+    # Check if already initialized
+    existing = get_developer()
+    if existing:
+        print(f"Developer already initialized: {existing}")
+        print()
+        print(f"To reinitialize, remove {DIR_WORKFLOW}/{FILE_DEVELOPER} first")
+        sys.exit(0)
+
+    if init_developer(name):
+        sys.exit(0)
+    else:
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

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

@@ -0,0 +1,69 @@
+#!/usr/bin/env python3
+"""Injection budget probe — measure alwaysApply, AGENTS, jsonl, and Layer 2 dispatch."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+_SCRIPTS = Path(__file__).resolve().parent
+if str(_SCRIPTS) not in sys.path:
+    sys.path.insert(0, str(_SCRIPTS))
+
+from common.injection_budget import (  # noqa: E402
+    budget_violations,
+    collect_budget_report,
+    format_budget_report,
+)
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Measure Pactile injection budget surfaces.")
+    parser.add_argument("--repo-root", default=".", help="Repository root (default: .)")
+    parser.add_argument("--task", default=None, help="Task directory for jsonl/dispatch probes")
+    parser.add_argument(
+        "--dispatch-role",
+        choices=["implement", "check", "research"],
+        default="implement",
+        help="Role when measuring dispatch prompt (default: implement)",
+    )
+    parser.add_argument(
+        "--strict",
+        action="store_true",
+        help="Exit 1 on FAIL thresholds (rules >32KiB) or any WARN",
+    )
+    parser.add_argument("--json", action="store_true", help="Reserved for future machine output")
+    args = parser.parse_args()
+
+    if args.json:
+        print("ERROR: --json not implemented yet", file=sys.stderr)
+        return 2
+
+    repo_root = Path(args.repo_root).resolve()
+    task_dir = None
+    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()
+
+    report = collect_budget_report(
+        repo_root,
+        task_dir=task_dir,
+        dispatch_role=args.dispatch_role if task_dir else None,
+    )
+    print(format_budget_report(report))
+
+    violations = budget_violations(report, strict=args.strict)
+    if violations:
+        print("\n## Violations", file=sys.stderr)
+        for item in violations:
+            print(item, file=sys.stderr)
+        if args.strict or any(item.startswith("FAIL:") for item in violations):
+            return 1
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

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

@@ -0,0 +1,237 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+Review-pool CLI: validate / plan-check / link / unlink / show / status.
+
+Usage:
+    python pool.py validate [--root <repo>]
+    python pool.py plan-check [--root <repo>]
+    python pool.py link <item-id> <task-ref> [--root <repo>]
+    python pool.py unlink <item-id> <task-ref> [--root <repo>]
+    python pool.py show <item-id> [--root <repo>]
+    python pool.py status [--root <repo>]
+
+Exit codes: any error-level finding (or a failed link/unlink/show) -> 1;
+warnings only -> 0.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from common.io import read_json
+from common.log import Colors, colored
+from common.paths import get_repo_root
+from common import pool_store
+
+
+def _print_issue(issue: pool_store.Issue) -> None:
+    color = Colors.RED if issue.is_error else Colors.YELLOW
+    level = "error" if issue.is_error else "warning"
+    location = f" ({issue.path})" if issue.path is not None else ""
+    print(colored(f"[{level}] {issue.code}: {issue.message}{location}", color))
+
+
+def _exit_for_issues(issues: list[pool_store.Issue]) -> int:
+    errors = [issue for issue in issues if issue.is_error]
+    warnings = [issue for issue in issues if not issue.is_error]
+    for issue in issues:
+        _print_issue(issue)
+    if not issues:
+        print(colored("OK", Colors.GREEN))
+    elif not errors:
+        print(colored(f"OK with {len(warnings)} warning(s)", Colors.GREEN))
+    else:
+        print(colored(f"{len(errors)} error(s), {len(warnings)} warning(s)", Colors.RED))
+    return 1 if errors else 0
+
+
+def cmd_validate(args: argparse.Namespace) -> int:
+    issues = pool_store.validate_pool(args.root)
+    return _exit_for_issues(issues)
+
+
+def cmd_plan_check(args: argparse.Namespace) -> int:
+    issues = pool_store.check_plan(args.root)
+    return _exit_for_issues(issues)
+
+
+def cmd_link(args: argparse.Namespace) -> int:
+    result = pool_store.link_item_task(args.root, args.item_id, args.task_ref)
+    for issue in result.errors:
+        _print_issue(issue)
+    if not result.ok:
+        return 1
+    print(colored(f"linked {result.item_id} <-> {result.task_ref}", Colors.GREEN))
+    item = pool_store.load_item(args.root, result.item_id)
+    if item is not None:
+        print(f"  item.linked_tasks: {item.linked_tasks or '[]'}")
+    data = read_json(result.task_path / "task.json") if result.task_path else None
+    if data is not None:
+        print(f"  task.meta.pool_items: {pool_store.get_pool_items(data) or '[]'}")
+    return 0
+
+
+def cmd_unlink(args: argparse.Namespace) -> int:
+    result = pool_store.unlink_item_task(args.root, args.item_id, args.task_ref)
+    for issue in result.errors:
+        _print_issue(issue)
+    if not result.ok:
+        return 1
+    for issue in result.warnings:
+        _print_issue(issue)
+    print(colored(f"unlinked {result.item_id} <-> {result.task_ref}", Colors.GREEN))
+    return 0
+
+
+def cmd_show(args: argparse.Namespace) -> int:
+    item = pool_store.load_item(args.root, args.item_id)
+    if item is None:
+        print(
+            colored(
+                f"[error] item-not-found: pool item {args.item_id!r} not found",
+                Colors.RED,
+            ),
+            file=sys.stderr,
+        )
+        return 1
+    tasks_dir = args.root / ".pactile" / "tasks"
+    print(f"id: {item.id or '<missing>'}")
+    print(f"title: {item.title or '<missing>'}")
+    print(f"status: {item.status or '<missing>'}")
+    print(f"type: {item.type or '<missing>'}")
+    delivery = item.frontmatter.get("delivery")
+    if isinstance(delivery, str) and delivery.strip():
+        print(f"delivery: {delivery.strip()}")
+    else:
+        print("delivery: <unset>")
+    priority = item.frontmatter.get("priority")
+    if isinstance(priority, str) and priority.strip():
+        print(f"priority: {priority.strip()}")
+    else:
+        print("priority: <unlabeled>")
+    print(f"path: {item.path}")
+    if not item.linked_tasks:
+        print("linked_tasks: []")
+    for ref in item.linked_tasks:
+        task_dir = pool_store.find_task_dir(ref, tasks_dir)
+        if task_dir is None:
+            print(f"linked_tasks: {ref} (missing)")
+            continue
+        data = read_json(task_dir / "task.json") or {}
+        status = data.get("status", "?")
+        archived = "archive/" in task_dir.as_posix()
+        suffix = " (archived)" if archived else ""
+        print(f"linked_tasks: {ref} -> {task_dir.name} ({status}){suffix}")
+    return 0
+
+
+def cmd_status(args: argparse.Namespace) -> int:
+    groups = pool_store.delivery_groups(args.root)
+    inbox = [
+        item
+        for item in pool_store.list_items(args.root)
+        if item.status == "inbox"
+    ]
+    print("queue (open / in-slice) — attention board")
+    for key in ("open", "in-slice"):
+        items = groups.get(key) or []
+        print(f"  {key}: {', '.join(item.id for item in items) or '(empty)'}")
+    print("standing — live rules, not a queue")
+    standing = groups.get("standing") or []
+    print(f"  {', '.join(item.id for item in standing) or '(empty)'}")
+    print("closed")
+    for key in ("landed", "deferred"):
+        items = groups.get(key) or []
+        print(f"  {key}: {', '.join(item.id for item in items) or '(empty)'}")
+    unset = groups.get("unset") or []
+    if unset:
+        print("accepted missing delivery")
+        print(f"  {', '.join(item.id for item in unset)}")
+    if inbox:
+        print("inbox hold")
+        print(f"  {', '.join(item.id for item in inbox)}")
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="pool.py",
+        description="Review-pool maintenance CLI: validate, plan-check, link, unlink, show, status.",
+    )
+    parser.add_argument(
+        "--root",
+        type=Path,
+        default=None,
+        help="Repository root. Defaults to nearest parent containing .pactile/.",
+    )
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    def add_root(entry_parser: argparse.ArgumentParser) -> None:
+        # SUPPRESS so a missing subcommand --root never clobbers the global
+        # --root with None (argparse subparser defaults overwrite parent values).
+        entry_parser.add_argument(
+            "--root",
+            type=Path,
+            default=argparse.SUPPRESS,
+            help="Repository root (overrides the global --root).",
+        )
+
+    validate_parser = subparsers.add_parser(
+        "validate",
+        help="Validate pool entries (sections, frontmatter, links, consistency).",
+    )
+    add_root(validate_parser)
+    plan_parser = subparsers.add_parser(
+        "plan-check",
+        help="Check plan.md references against known pool item ids.",
+    )
+    add_root(plan_parser)
+    link_parser = subparsers.add_parser(
+        "link",
+        help="Link a pool item to a task on both sides (idempotent).",
+    )
+    add_root(link_parser)
+    link_parser.add_argument("item_id", help="Pool item id, e.g. P01")
+    link_parser.add_argument("task_ref", help="Task dir name or resolvable ref")
+    unlink_parser = subparsers.add_parser(
+        "unlink",
+        help="Remove the item<->task link on both sides (best-effort).",
+    )
+    add_root(unlink_parser)
+    unlink_parser.add_argument("item_id", help="Pool item id, e.g. P01")
+    unlink_parser.add_argument("task_ref", help="Task dir name or resolvable ref")
+    show_parser = subparsers.add_parser(
+        "show",
+        help="Print one pool item with linked task statuses.",
+    )
+    add_root(show_parser)
+    show_parser.add_argument("item_id", help="Pool item id, e.g. P01")
+    status_parser = subparsers.add_parser(
+        "status",
+        help="Print delivery groups: queue / standing / closed.",
+    )
+    add_root(status_parser)
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    root = getattr(args, "root", None)
+    args.root = root.resolve() if root is not None else get_repo_root()
+
+    handlers = {
+        "validate": cmd_validate,
+        "plan-check": cmd_plan_check,
+        "link": cmd_link,
+        "unlink": cmd_unlink,
+        "show": cmd_show,
+        "status": cmd_status,
+    }
+    return handlers[args.command](args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

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

@@ -0,0 +1,98 @@
+#!/usr/bin/env python3
+"""Quality-layer CLI: rank already-collected path candidates (eval / dogfood).
+
+Three-layer retrieval ABI (frozen; do not merge back into workflow.md):
+
+| Layer    | Owner                 | This script                                      |
+| -------- | --------------------- | ------------------------------------------------ |
+| Intent   | context-progressive   | consumes intent ids; does not invent a 5th one   |
+| Provider | Middleware            | does not take smart-search as a Kernel dependency |
+| Quality  | retrieval-extended    | owner: reorder collected-evidence candidates      |
+
+Does not search. Does not change scoring/ranking algorithms in this freeze.
+Input role: collected-evidence. Output is not AC Evidence.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from common.retrieval_result_ranking import rank_retrieval_result_candidates
+
+ABI_INTENT_OWNER = "context-progressive"
+ABI_PROVIDER_OWNER = "middleware"
+ABI_QUALITY_OWNER = "retrieval-extended"
+ABI_LAYER = "quality"
+INPUT_ROLE = "collected-evidence"
+
+
+def parse_args(argv: list[str] | None = None) -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description="Rank already-collected candidates for neutral V3 intents.",
+    )
+    parser.add_argument(
+        "--candidates",
+        help="Path to JSON array of candidate objects, or '-' for stdin.",
+    )
+    parser.add_argument(
+        "--intents",
+        required=True,
+        help="Comma-separated intent ids: exact,semantic,structural,external.",
+    )
+    parser.add_argument("--top-k", type=int, default=5)
+    parser.add_argument("--expanded-pool-size", type=int, default=None)
+    parser.add_argument(
+        "--caller-pool-expansion",
+        action="store_true",
+        help="Deprecated compatibility option; ignored by the V3 ranker.",
+    )
+    parser.add_argument("--min-concrete-callers", type=int, default=3)
+    parser.add_argument("--json", action="store_true", help="Emit JSON (default).")
+    parser.add_argument("--pretty", action="store_true")
+    return parser.parse_args(argv)
+
+
+def load_candidates(source: str | None) -> list[dict]:
+    if source is None or source == "-":
+        raw = sys.stdin.read()
+    else:
+        raw = Path(source).read_text(encoding="utf-8")
+    parsed = json.loads(raw)
+    if not isinstance(parsed, list):
+        raise ValueError("candidates must be a JSON array")
+    return [item for item in parsed if isinstance(item, dict)]
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = parse_args(argv)
+    try:
+        candidates = load_candidates(args.candidates)
+    except (OSError, json.JSONDecodeError, ValueError) as error:
+        print(f"rank_retrieval_candidates: {error}", file=sys.stderr)
+        return 2
+
+    intents = [part.strip() for part in args.intents.split(",") if part.strip()]
+    expansion = None
+    if args.caller_pool_expansion:
+        expansion = {
+            "enabled": True,
+            "minConcreteCallers": args.min_concrete_callers,
+        }
+
+    result = rank_retrieval_result_candidates(
+        candidates,
+        intents=intents,
+        top_k=args.top_k,
+        expanded_pool_size=args.expanded_pool_size,
+        caller_pool_expansion=expansion,
+    )
+    indent = 2 if args.pretty else None
+    print(json.dumps(result, indent=indent, ensure_ascii=False))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())