@blxzer/pactile 0.5.0

package/dist/templates/pactile/scripts/retrieval_probe_matrix_template.json

@@ -0,0 +1,43 @@
+{
+  "schemaVersion": 3,
+  "description": "Host-neutral Pactile retrieval resolver evidence matrix.",
+  "hostDiscoveryPerformed": false,
+  "probes": [
+    {
+      "intent": "exact",
+      "plannerKind": "local-exact",
+      "resolverStatus": "not-requested",
+      "minimumAssurance": "evidence-backed",
+      "evidenceRefs": [],
+      "corroboration": [],
+      "probedAt": null
+    },
+    {
+      "intent": "semantic",
+      "plannerKind": "provider-request",
+      "resolverStatus": null,
+      "minimumAssurance": "evidence-backed",
+      "evidenceRefs": [],
+      "corroboration": [],
+      "probedAt": null
+    },
+    {
+      "intent": "structural",
+      "plannerKind": "provider-request",
+      "resolverStatus": null,
+      "minimumAssurance": "evidence-backed",
+      "evidenceRefs": [],
+      "corroboration": [],
+      "probedAt": null
+    },
+    {
+      "intent": "external",
+      "plannerKind": "provider-request",
+      "resolverStatus": null,
+      "minimumAssurance": "evidence-backed",
+      "evidenceRefs": [],
+      "corroboration": [],
+      "probedAt": null
+    }
+  ]
+}

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

@@ -0,0 +1,72 @@
+#!/usr/bin/env python3
+"""
+Emit a deterministic codebase retrieval plan JSON envelope for a query string.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from common.codebase_retrieval_router import route_codebase_retrieval
+from common.retrieval_agent_instructions import render_agent_instructions
+
+
+def parse_args(argv: list[str] | None = None) -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description="Route a codebase retrieval question to a structured plan envelope.",
+    )
+    parser.add_argument("query", nargs="?", default="", help="Natural-language retrieval question.")
+    parser.add_argument(
+        "--capabilities",
+        help="Deprecated compatibility option; capability binding is resolver-owned.",
+    )
+    parser.add_argument(
+        "--no-codebase-retrieval",
+        action="store_true",
+        help="Deprecated compatibility option; does not change the V3 plan.",
+    )
+    parser.add_argument(
+        "--project-file-count",
+        default="auto",
+        metavar="N|auto",
+        help="Deprecated compatibility option; does not change the V3 plan.",
+    )
+    parser.add_argument(
+        "--locale",
+        default="zh",
+        choices=["zh", "en"],
+        help="Language for agent instructions (default: zh).",
+    )
+    parser.add_argument(
+        "--instructions",
+        action="store_true",
+        help="Print agent-executable instructions only (no JSON).",
+    )
+    parser.add_argument("--json", action="store_true", help="Emit JSON to stdout (default).")
+    parser.add_argument("--pretty", action="store_true", help="Pretty-print JSON.")
+    return parser.parse_args(argv)
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = parse_args(argv)
+    try:
+        plan = route_codebase_retrieval(args.query)
+    except ValueError as error:
+        print(f"route_codebase_retrieval: {error}", file=sys.stderr)
+        return 2
+    instructions = render_agent_instructions(
+        plan,
+        locale=args.locale,
+    )
+    if args.instructions:
+        sys.stdout.write(instructions)
+        return 0
+    payload: dict[str, object] = {**plan, "agentInstructions": instructions}
+    indent = 2 if args.pretty else None
+    print(json.dumps(payload, indent=indent, ensure_ascii=False))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

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

@@ -0,0 +1,12 @@
+#!/usr/bin/env python3
+"""
+Run Smart Search and capture Pactile evidence.
+"""
+
+from __future__ import annotations
+
+from common.smart_search_evidence import main
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

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

@@ -0,0 +1,131 @@
+#!/usr/bin/env python3
+"""Quality-layer eval helper: derive evidence_score (0-2) from telemetry.
+
+Three-layer retrieval ABI (frozen; do not merge back into workflow.md):
+
+| Layer    | Owner                 | This script                                      |
+| -------- | --------------------- | ------------------------------------------------ |
+| Intent   | context-progressive   | does not own intents                             |
+| Provider | Middleware            | does not take smart-search as a Kernel dependency |
+| Quality  | retrieval-extended    | owner: score already-collected evidence records   |
+
+REC-11 eval proxy only. Does not search. Does not implement a new ranking
+algorithm in this freeze. Input role: collected-evidence. Output is not
+AC Evidence / Close Evidence (that remains verify-basic).
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+ABI_INTENT_OWNER = "context-progressive"
+ABI_PROVIDER_OWNER = "middleware"
+ABI_QUALITY_OWNER = "retrieval-extended"
+ABI_LAYER = "quality"
+INPUT_ROLE = "collected-evidence"
+
+_SCRIPT_DIR = Path(__file__).resolve().parent
+if str(_SCRIPT_DIR) not in sys.path:
+    sys.path.insert(0, str(_SCRIPT_DIR))
+
+from common.retrieval_tool_classification import classify_tool_calls  # noqa: E402
+
+
+def evidence_score_from_record(record: dict[str, Any]) -> int:
+    """
+    Pactile verified layer proxy for eval (R-CR-014):
+    0 = no Read on candidates
+    1 = Read used but no corroborated_files / weak verify
+    2 = read_verification_done and (corroborated_files or read_count >= 1 with top1)
+    """
+    if not record.get("read_verification_done") and int(record.get("read_count") or 0) <= 0:
+        return 0
+    corroborated = record.get("corroborated_files") or []
+    if isinstance(corroborated, list) and len(corroborated) > 0:
+        return 2
+    if record.get("read_verification_done") or int(record.get("read_count") or 0) > 0:
+        top1 = str(record.get("top1") or record.get("top_1") or "").strip()
+        if top1:
+            return 2
+        return 1
+    return 0
+
+
+def enrich_record(raw: dict[str, Any]) -> dict[str, Any]:
+    platform = str(raw.get("platform", "cursor"))
+    tools = raw.get("tools_called") or []
+    if not isinstance(tools, list):
+        tools = []
+    classified = classify_tool_calls([str(t) for t in tools], platform=platform)
+    out = dict(raw)
+    out["platform_semantic_executed"] = bool(
+        raw.get("platform_semantic_executed", classified.platform_semantic_executed)
+    )
+    out["semantic_executed"] = bool(raw.get("semantic_executed", classified.semantic_executed))
+    out["read_count"] = int(raw.get("read_count", classified.read_count))
+    if "read_verification_done" not in out:
+        out["read_verification_done"] = classified.read_count > 0
+    out["evidence_score"] = evidence_score_from_record(out)
+    ans = raw.get("answer_score")
+    if isinstance(ans, (int, float)):
+        out["combined_score"] = float(ans) + float(out["evidence_score"])
+    return out
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("jsonl", type=Path, help="Per-query telemetry JSONL")
+    parser.add_argument("--pretty", action="store_true")
+    parser.add_argument("--markdown", action="store_true")
+    args = parser.parse_args(argv)
+
+    if not args.jsonl.is_file():
+        print(f"error: not found: {args.jsonl}", file=sys.stderr)
+        return 1
+
+    rows: list[dict[str, Any]] = []
+    for line in args.jsonl.read_text(encoding="utf-8").splitlines():
+        stripped = line.strip()
+        if not stripped:
+            continue
+        raw = json.loads(stripped)
+        if isinstance(raw, dict):
+            rows.append(enrich_record(raw))
+
+    evidence_total = sum(int(r.get("evidence_score", 0)) for r in rows)
+    combined: list[float] = []
+    for r in rows:
+        c = r.get("combined_score")
+        if isinstance(c, (int, float)):
+            combined.append(float(c))
+
+    summary = {
+        "n": len(rows),
+        "evidence_score_total": evidence_total,
+        "evidence_score_max": len(rows) * 2,
+        "avg_evidence_score": 0.0 if not rows else evidence_total / len(rows),
+        "avg_combined_score": 0.0 if not combined else sum(combined) / len(combined),
+    }
+
+    if args.markdown:
+        print("## Evidence scores (REC-11)\n")
+        print("| query_id | evidence_score | read_verify | semantic_exec |")
+        print("| --- | ---: | --- | --- |")
+        for r in rows:
+            print(
+                f"| {r.get('query_id','')} | {r.get('evidence_score',0)} | "
+                f"{r.get('read_verification_done')} | {r.get('semantic_executed')} |"
+            )
+        print(f"\nTotal evidence: **{evidence_total}** / {summary['evidence_score_max']}")
+    else:
+        payload = {"summary": summary, "records": rows}
+        print(json.dumps(payload, ensure_ascii=False, indent=2 if args.pretty else None))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

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

@@ -0,0 +1,13 @@
+#!/usr/bin/env python3
+"""
+Search durable Pactile markdown artifacts.
+"""
+
+from __future__ import annotations
+
+from common.artifact_search import main
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
+

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

@@ -0,0 +1,12 @@
+#!/usr/bin/env python3
+"""
+Search Pactile workspace session memory.
+"""
+
+from __future__ import annotations
+
+from common.session_memory import main
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

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

@@ -0,0 +1,160 @@
+#!/usr/bin/env python3
+"""S1 spec-health outcomes — read-only durable-learning distribution over archive verify.md.
+
+Maintainer observability only — NOT a blocking gate or KPI.
+See .pactile/spec/guides/durable-learning-decision-guide.md for outcome definitions.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from collections import defaultdict
+from pathlib import Path
+from typing import Any
+
+_SCRIPT_DIR = Path(__file__).resolve().parent
+if str(_SCRIPT_DIR) not in sys.path:
+    sys.path.insert(0, str(_SCRIPT_DIR))
+
+from common.task_gates import NO_DURABLE_LEARNING_RE  # noqa: E402
+
+BUCKET_NAMES = ("no_only", "spec", "artifact", "ambiguous_multi", "legacy_none")
+
+MONTH_RE = re.compile(r"^(\d{4}-\d{2})$")
+
+
+def detect_signals(content: str) -> dict[str, bool]:
+    """Return which durable-learning signal families appear in verify.md text.
+
+    Uses the same substring probes as spec-health-signals.md S1 baseline (2026-08-06).
+    """
+    lower = content.lower()
+    return {
+        "no": bool(NO_DURABLE_LEARNING_RE.search(content)),
+        "spec": "spec update evidence" in lower,
+        "artifact": "learning artifact" in lower,
+    }
+
+
+def classify_bucket(content: str) -> str:
+    """Assign exactly one mutually-exclusive S1 outcome bucket."""
+    active = [name for name, present in detect_signals(content).items() if present]
+    if not active:
+        return "legacy_none"
+    if len(active) > 1:
+        return "ambiguous_multi"
+    return {"no": "no_only", "spec": "spec", "artifact": "artifact"}[active[0]]
+
+
+def extract_month(verify_path: Path, archive_root: Path) -> str | None:
+    """Derive YYYY-MM from archive folder layout (e.g. archive/2026-08/<task>/verify.md)."""
+    try:
+        rel = verify_path.relative_to(archive_root)
+    except ValueError:
+        return None
+    if rel.parts and MONTH_RE.match(rel.parts[0]):
+        return rel.parts[0]
+    return None
+
+
+def empty_counts() -> dict[str, int]:
+    return {name: 0 for name in BUCKET_NAMES}
+
+
+def scan_archive(root: Path) -> tuple[dict[str, int], dict[str, dict[str, int]], int]:
+    totals = empty_counts()
+    by_month: dict[str, dict[str, int]] = defaultdict(empty_counts)
+    total_files = 0
+
+    for verify_path in sorted(root.rglob("verify.md")):
+        if not verify_path.is_file():
+            continue
+        total_files += 1
+        try:
+            content = verify_path.read_text(encoding="utf-8")
+        except OSError:
+            content = ""
+        bucket = classify_bucket(content)
+        totals[bucket] += 1
+        month = extract_month(verify_path, root)
+        if month:
+            by_month[month][bucket] += 1
+
+    return totals, dict(sorted(by_month.items())), total_files
+
+
+def build_report(root: Path, *, by_month: bool) -> dict[str, Any]:
+    totals, monthly, total_files = scan_archive(root)
+    report: dict[str, Any] = {
+        "root": str(root),
+        "total": total_files,
+        "buckets": totals,
+        "note": "Maintainer observability only — not a blocking gate or KPI.",
+    }
+    if by_month:
+        report["by_month"] = monthly
+    return report
+
+
+def format_text_report(report: dict[str, Any]) -> str:
+    lines = [
+        f"Spec health S1 outcomes — {report['total']} verify.md files",
+        f"Root: {report['root']}",
+        "",
+    ]
+    total = int(report["total"])
+    for name in BUCKET_NAMES:
+        count = int(report["buckets"][name])
+        pct = (count / total * 100) if total else 0.0
+        lines.append(f"  {name}: {count} ({pct:.1f}%)")
+    lines.extend(["", str(report["note"])])
+    if report.get("by_month"):
+        lines.append("")
+        lines.append("By month:")
+        for month, counts in report["by_month"].items():
+            month_total = sum(int(v) for v in counts.values())
+            lines.append(f"  {month}: {month_total} files — {counts}")
+    return "\n".join(lines)
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        description=(
+            "S1 spec-health: durable-learning outcome distribution in archive verify.md "
+            "(read-only; not a gate)."
+        ),
+    )
+    parser.add_argument(
+        "--root",
+        type=Path,
+        default=Path(".pactile/tasks/archive"),
+        help="Archive root to scan (default: .pactile/tasks/archive)",
+    )
+    parser.add_argument("--json", action="store_true", help="Emit JSON report on stdout")
+    parser.add_argument(
+        "--by-month",
+        action="store_true",
+        help="Include per YYYY-MM bucket counts (from archive folder names)",
+    )
+    args = parser.parse_args(argv)
+
+    root = args.root.resolve()
+    if not root.is_dir():
+        print(f"error: archive root not found: {root}", file=sys.stderr)
+        return 1
+
+    report = build_report(root, by_month=args.by_month)
+
+    if args.json:
+        print(json.dumps(report, indent=2, ensure_ascii=False))
+    else:
+        print(format_text_report(report))
+
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())