@blxzer/pactile 0.5.0

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

@@ -0,0 +1,268 @@
+#!/usr/bin/env python3
+"""Suggest Development Strategy Contract execution_mode and isolation from task signals."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import asdict, dataclass, field
+from pathlib import Path
+from typing import Any
+
+from .git import run_git
+from .task_gates import read_strategy_contract, task_closeout_profile
+
+_RULES_CACHE: dict | None = None
+
+
+@dataclass
+class ExecutionStrategySuggestion:
+    skipped: bool = False
+    profile: str = ""
+    execution_mode: str = ""
+    isolation: str = ""
+    reasons: list[str] = field(default_factory=list)
+    warnings: list[str] = field(default_factory=list)
+    signals: dict[str, Any] = field(default_factory=dict)
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+
+def _rules_path() -> Path:
+    return Path(__file__).resolve().parent.parent.parent / "config" / "execution-strategy-rules.json"
+
+
+def load_execution_strategy_rules() -> dict:
+    global _RULES_CACHE
+    if _RULES_CACHE is not None:
+        return _RULES_CACHE
+    path = _rules_path()
+    if not path.is_file():
+        _RULES_CACHE = {
+            "version": 1,
+            "doc_only_capabilities": ["markdown-documentation"],
+            "code_capabilities": [],
+            "code_path_segments": ["src", "packages", "scripts"],
+            "pair_warnings": [],
+        }
+        return _RULES_CACHE
+    _RULES_CACHE = json.loads(path.read_text(encoding="utf-8"))
+    return _RULES_CACHE
+
+
+def resolve_git_package_root(repo_root: Path, task_data: dict) -> Path | None:
+    """Return a directory inside a git worktree suitable for prepare-child-worktree."""
+    candidates: list[Path] = []
+    package = task_data.get("package")
+    if isinstance(package, str) and package.strip():
+        candidates.append(repo_root / package.strip().replace("\\", "/"))
+    scope = task_data.get("scope")
+    if isinstance(scope, str) and scope.strip():
+        first = scope.strip().replace("\\", "/").split("/")[0]
+        if first:
+            candidates.append(repo_root / first)
+    candidates.append(repo_root)
+
+    seen: set[str] = set()
+    for candidate in candidates:
+        key = str(candidate.resolve()) if candidate.exists() else str(candidate)
+        if key in seen:
+            continue
+        seen.add(key)
+        if not candidate.is_dir():
+            continue
+        rc, out, _ = run_git(["rev-parse", "--is-inside-work-tree"], cwd=candidate)
+        if rc == 0 and out.strip().lower() == "true":
+            return candidate
+    return None
+
+
+def _path_hits_code_segment(repo_root: Path, rel: str, segments: list[str]) -> bool:
+    parts = [p for p in rel.replace("\\", "/").split("/") if p]
+    return any(part in segments for part in parts)
+
+
+def _capabilities_list(contract: dict) -> list[str]:
+    raw = contract.get("optional_capabilities")
+    if not isinstance(raw, list):
+        return []
+    return [str(item).strip() for item in raw if isinstance(item, str) and item.strip()]
+
+
+def collect_signals(repo_root: Path, task_dir: Path, task_data: dict) -> dict[str, Any]:
+    rules = load_execution_strategy_rules()
+    profile = task_closeout_profile(task_dir, task_data)
+    contract, _ = read_strategy_contract(task_dir)
+    caps = _capabilities_list(contract)
+    doc_only_set = set(rules.get("doc_only_capabilities") or [])
+    code_cap_set = set(rules.get("code_capabilities") or [])
+    segments = list(rules.get("code_path_segments") or [])
+
+    has_parent = bool(task_data.get("parent"))
+    children = task_data.get("children")
+    has_children = isinstance(children, list) and any(isinstance(c, str) for c in children)
+
+    touches_code = False
+    if caps and any(c in code_cap_set for c in caps):
+        touches_code = True
+    package = task_data.get("package")
+    if isinstance(package, str) and package.strip():
+        if _path_hits_code_segment(repo_root, package.strip(), segments):
+            touches_code = True
+    scope = task_data.get("scope")
+    if isinstance(scope, str) and scope.strip():
+        if _path_hits_code_segment(repo_root, scope.strip(), segments):
+            touches_code = True
+    if (
+        profile == "full"
+        and (task_dir / "design.md").is_file()
+        and caps
+        and not all(c in doc_only_set for c in caps)
+    ):
+        touches_code = True
+    if profile == "full" and (task_dir / "design.md").is_file() and not caps:
+        touches_code = True
+
+    doc_only = bool(caps) and all(c in doc_only_set for c in caps)
+    if profile == "full" and caps and doc_only and not touches_code:
+        doc_only = True
+
+    git_root = resolve_git_package_root(repo_root, task_data)
+    return {
+        "profile": profile,
+        "has_parent": has_parent,
+        "has_children": has_children,
+        "touches_code": touches_code,
+        "doc_only": doc_only,
+        "git_package_root": git_root.as_posix() if git_root else None,
+        "package": package if isinstance(package, str) else None,
+        "scope": scope if isinstance(scope, str) else None,
+        "optional_capabilities": caps,
+    }
+
+
+def validate_strategy_pair(execution_mode: str, isolation: str) -> list[str]:
+    rules = load_execution_strategy_rules()
+    warnings: list[str] = []
+    for entry in rules.get("pair_warnings") or []:
+        if not isinstance(entry, dict):
+            continue
+        if (
+            entry.get("execution_mode") == execution_mode
+            and entry.get("isolation") == isolation
+        ):
+            msg = entry.get("message")
+            if isinstance(msg, str) and msg.strip():
+                warnings.append(msg.strip())
+    return warnings
+
+
+def suggest_execution_strategy(
+    repo_root: Path,
+    task_dir: Path,
+    task_data: dict,
+) -> ExecutionStrategySuggestion:
+    signals = collect_signals(repo_root, task_dir, task_data)
+    profile = signals["profile"]
+    if profile == "lite":
+        return ExecutionStrategySuggestion(
+            skipped=True,
+            profile=profile,
+            reasons=["Lite task: no full Development Strategy Contract required"],
+            signals=signals,
+        )
+
+    reasons: list[str] = []
+    warnings: list[str] = []
+
+    if signals["has_parent"]:
+        mode = "child-task"
+        if signals["git_package_root"]:
+            iso = "git-worktree"
+            reasons.append("Child task with git package root → git-worktree isolation")
+        else:
+            iso = "main-worktree"
+            reasons.append("Child task without resolvable git root → main-worktree (degraded)")
+            warnings.append("No git package root; child git-worktree not recommended")
+    elif signals["has_children"] or profile == "parent":
+        mode = "inline"
+        iso = "main-worktree"
+        reasons.append("Parent task orchestrates children in main session")
+    elif profile == "full" and signals["doc_only"] and not signals["touches_code"]:
+        mode = "inline"
+        iso = "main-worktree"
+        reasons.append("Full task with documentation-only capabilities")
+    elif profile == "full":
+        mode = "worker"
+        iso = "main-worktree"
+        reasons.append("Full task touching code → worker (pactile-implement / check sub-agents)")
+    else:
+        mode = "inline"
+        iso = "main-worktree"
+        reasons.append(f"Default for profile={profile}")
+
+    warnings.extend(validate_strategy_pair(mode, iso))
+    return ExecutionStrategySuggestion(
+        profile=profile,
+        execution_mode=mode,
+        isolation=iso,
+        reasons=reasons,
+        warnings=warnings,
+        signals=signals,
+    )
+
+
+def format_contract_yaml_block(suggestion: ExecutionStrategySuggestion) -> str:
+    if suggestion.skipped:
+        return "# Lite task: Development Strategy Contract not required\n"
+    lines = [
+        "## Development Strategy Contract (suggested — paste into implement.md)",
+        "",
+        "```yaml",
+        f"execution_mode: {suggestion.execution_mode}",
+        f"isolation: {suggestion.isolation}",
+        "verification_profile: standard",
+        "retrieval_profile: structure",
+        "optional_capabilities: []",
+        "quality_gates:",
+        "  mode: profile",
+        "  profile: standard",
+        "  enabled: []",
+        "  disabled: []",
+        "```",
+        "",
+    ]
+    if suggestion.reasons:
+        lines.append("Reasons:")
+        for item in suggestion.reasons:
+            lines.append(f"- {item}")
+    if suggestion.warnings:
+        lines.append("")
+        lines.append("Warnings:")
+        for item in suggestion.warnings:
+            lines.append(f"- {item}")
+    lines.append("")
+    return "\n".join(lines)
+
+
+def contract_drift_warnings(
+    repo_root: Path,
+    task_dir: Path,
+    task_data: dict,
+    contract: dict,
+) -> list[str]:
+    """Compare approved contract to suggestion; advisory only."""
+    if not contract:
+        return []
+    suggestion = suggest_execution_strategy(repo_root, task_dir, task_data)
+    if suggestion.skipped:
+        return []
+    warnings: list[str] = []
+    for key in ("execution_mode", "isolation"):
+        approved = contract.get(key)
+        suggested = getattr(suggestion, key, "")
+        if approved and suggested and approved != suggested:
+            warnings.append(
+                f"contract {key}={approved!r} differs from suggestion {suggested!r}"
+            )
+    return warnings

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

@@ -0,0 +1,237 @@
+"""Stage 4 Full Quality helpers (controls, AC ledger, graded Independent Check).
+
+Python projection of the Kernel Full Quality contract. Kernel remains the
+writer; these helpers validate extras before archive and prefer persisted
+required_controls over inferring Rigor from files.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import re
+from pathlib import Path
+from typing import Any
+
+FULL_QUALITY_SOURCE = "full-quality-contract"
+FULL_QUALITY_SCHEMA_VERSION = 1
+FULL_BASELINE_CONTROLS = (
+    "definition",
+    "execution-contract",
+    "verification-plan",
+    "evidence",
+    "independent-check",
+)
+DEFAULT_CONTROL_SURFACES = {
+    "definition": "prd.md",
+    "execution-contract": "implement.md",
+    "verification-plan": "implement.md",
+    "evidence": "verify.md",
+    "design": "design.md",
+}
+DESIGN_RISK_SIGNALS = {
+    "architecture",
+    "public-contract",
+    "schema",
+    "security",
+    "secret",
+    "framework-semantics",
+    "runtime-semantics",
+}
+PLACEHOLDER_VALUE_RE = re.compile(
+    r"(?i)^(TBD|TODO|待定|待补充|N/?A|NA|NONE|-|\.\.\.)$"
+)
+AC_ITEM_RE = re.compile(r"(?im)^\s*-\s*\[[ xX]\]\s+(.+)$")
+
+
+class FullQualityError(RuntimeError):
+    """Full Quality contract rejected a start/close request."""
+
+
+def quality_fingerprint(payload: str) -> str:
+    digest = hashlib.sha256(payload.encode("utf-8")).hexdigest()
+    return f"sha256:{digest}"
+
+
+def resolve_required_controls(
+    *,
+    rigor: str = "lite",
+    verification_profile: str | None = None,
+    risk_signals: list[str] | None = None,
+    policy_requires_design: bool = False,
+    explicit_controls: list[str] | None = None,
+    surfaces: dict[str, str] | None = None,
+) -> dict[str, Any]:
+    normalized = "full" if rigor == "full" else "lite"
+    signals = [str(item).strip().lower() for item in (risk_signals or []) if item]
+    design_required = normalized == "full" and (
+        policy_requires_design
+        or verification_profile == "architecture"
+        or any(signal in DESIGN_RISK_SIGNALS for signal in signals)
+    )
+    if explicit_controls:
+        controls = _unique(explicit_controls)
+    elif normalized == "full":
+        controls = list(FULL_BASELINE_CONTROLS)
+        if design_required:
+            controls.append("design")
+    else:
+        controls = ["definition", "evidence"]
+    if design_required and "design" not in controls:
+        controls.append("design")
+    return {
+        "schema_version": FULL_QUALITY_SCHEMA_VERSION,
+        "source": FULL_QUALITY_SOURCE,
+        "rigor": normalized,
+        "controls": controls,
+        "surfaces": {**DEFAULT_CONTROL_SURFACES, **(surfaces or {})},
+        "resolved_from": {
+            "verification_profile": verification_profile,
+            "risk_signals": signals,
+            "policy_requires_design": policy_requires_design,
+        },
+    }
+
+
+def rigor_from_required_controls(task_data: dict | None) -> str | None:
+    extras = task_data or {}
+    bundle = extras.get("required_controls")
+    if not isinstance(bundle, dict):
+        return None
+    rigor = bundle.get("rigor")
+    if rigor in ("lite", "full"):
+        return rigor
+    return None
+
+
+def parse_acceptance_items(prd_text: str) -> list[dict[str, str]]:
+    items: list[dict[str, str]] = []
+    index = 0
+    for match in AC_ITEM_RE.finditer(prd_text):
+        statement = match.group(1).strip()
+        if not statement or PLACEHOLDER_VALUE_RE.match(statement):
+            continue
+        index += 1
+        items.append({"id": f"AC-{index}", "statement": statement})
+    return items
+
+
+def evaluate_independent_check(
+    *,
+    mode: str,
+    independent_worker_available: bool,
+    evidence: str,
+    code_fingerprint: str,
+    attempted_writes: bool = False,
+) -> dict[str, Any]:
+    if attempted_writes:
+        raise FullQualityError("Independent Check is read-only; repairs return to Execute")
+    if mode not in ("self-review", "true-independent"):
+        raise FullQualityError("Independent Check mode must be self-review or true-independent")
+    if mode == "true-independent" and not independent_worker_available:
+        return {
+            "schema_version": FULL_QUALITY_SCHEMA_VERSION,
+            "mode": "true-independent",
+            "readonly": True,
+            "result": "BLOCKED",
+            "evidence": evidence.strip(),
+            "independent_worker": False,
+            "code_fingerprint": code_fingerprint,
+        }
+    if not evidence.strip() or PLACEHOLDER_VALUE_RE.match(evidence.strip()):
+        raise FullQualityError(
+            "Independent Check PASS/FAIL requires non-empty evidence (no fake-green)"
+        )
+    return {
+        "schema_version": FULL_QUALITY_SCHEMA_VERSION,
+        "mode": mode,
+        "readonly": True,
+        "result": "PASS",
+        "evidence": evidence.strip(),
+        "independent_worker": independent_worker_available,
+        "code_fingerprint": code_fingerprint,
+    }
+
+
+def full_quality_archive_errors(task_dir: Path, task_data: dict | None) -> list[str]:
+    """Return archive errors for persisted Full required_controls only.
+
+    Lite and legacy file-heuristic Full are unchanged: this does not force
+    Independent Check onto Lite.
+    """
+    data = task_data or {}
+    bundle = data.get("required_controls")
+    if not isinstance(bundle, dict) or bundle.get("rigor") != "full":
+        return []
+    errors: list[str] = []
+    controls = bundle.get("controls")
+    if not isinstance(controls, list):
+        controls = list(FULL_BASELINE_CONTROLS)
+    surfaces = bundle.get("surfaces") if isinstance(bundle.get("surfaces"), dict) else {}
+    seen: set[str] = set()
+    for control in controls:
+        if control in ("independent-check",):
+            continue
+        relative = surfaces.get(control) or DEFAULT_CONTROL_SURFACES.get(control)
+        if not relative or relative in seen:
+            continue
+        seen.add(relative)
+        path = task_dir / relative
+        if not path.is_file() or not path.read_text(encoding="utf-8").strip():
+            errors.append(f"Full required control {control} missing surface {relative}")
+
+    ledger = data.get("ac_evidence_ledger")
+    if not isinstance(ledger, dict):
+        errors.append("Full Close requires a machine-readable AC → Evidence ledger")
+    else:
+        definition = surfaces.get("definition") or DEFAULT_CONTROL_SURFACES["definition"]
+        prd_path = task_dir / definition
+        prd_text = prd_path.read_text(encoding="utf-8") if prd_path.is_file() else ""
+        acceptance = parse_acceptance_items(prd_text)
+        mapped = {
+            item.get("ac_id"): item
+            for item in ledger.get("items", [])
+            if isinstance(item, dict)
+        }
+        if not acceptance:
+            errors.append(f"{definition} has no Acceptance Criteria items to map")
+        for item in acceptance:
+            mapping = mapped.get(item["id"])
+            ref = mapping.get("evidence_ref") if isinstance(mapping, dict) else ""
+            if not isinstance(ref, str) or not ref.strip() or PLACEHOLDER_VALUE_RE.match(ref.strip()):
+                errors.append(f"AC → Evidence ledger missing mapping for {item['id']}")
+        current_source = quality_fingerprint(prd_text)
+        if ledger.get("source_fingerprint") and ledger.get("source_fingerprint") != current_source:
+            errors.append("AC → Evidence ledger is stale after Definition/code change")
+
+    check = data.get("independent_check")
+    if not isinstance(check, dict):
+        errors.append("Full Close requires a graded Independent Check verdict")
+    else:
+        if check.get("readonly") is False:
+            errors.append("Independent Check is read-only; repairs return to Execute")
+        mode = check.get("mode") or check.get("assurance")
+        if mode == "true-independent" and check.get("independent_worker") is not True:
+            errors.append("true-independent Check cannot be satisfied without an independent worker")
+        if check.get("result") != "PASS":
+            errors.append("Full Close requires Independent Check result PASS")
+        evidence = check.get("evidence")
+        if not isinstance(evidence, str) or not evidence.strip():
+            errors.append("Independent Check PASS requires non-empty evidence (no fake-green)")
+        ledger = data.get("ac_evidence_ledger")
+        if (
+            isinstance(ledger, dict)
+            and isinstance(ledger.get("tested_code_fingerprint"), str)
+            and isinstance(check.get("code_fingerprint"), str)
+            and check.get("code_fingerprint") != ledger.get("tested_code_fingerprint")
+        ):
+            errors.append("Independent Check verdict is stale after code change")
+    return errors
+
+
+def _unique(values: list[str]) -> list[str]:
+    out: list[str] = []
+    for value in values:
+        item = value.strip()
+        if item and item not in out:
+            out.append(item)
+    return out

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

@@ -0,0 +1,37 @@
+"""
+Git command execution utility.
+
+Single source of truth for running git commands across all Pactile scripts.
+"""
+
+from __future__ import annotations
+
+import subprocess
+from pathlib import Path
+
+
+def run_git(args: list[str], cwd: Path | None = None) -> tuple[int, str, str]:
+    """Run a git command and return (returncode, stdout, stderr).
+
+    Uses UTF-8 encoding with -c i18n.logOutputEncoding=UTF-8 to ensure
+    consistent output across all platforms (Windows, macOS, Linux).
+    """
+    try:
+        git_args = ["git", "-c", "i18n.logOutputEncoding=UTF-8"] + args
+        result = subprocess.run(
+            git_args,
+            cwd=cwd,
+            capture_output=True,
+            text=True,
+            encoding="utf-8",
+            errors="replace",
+        )
+        return result.returncode, result.stdout, result.stderr
+    except Exception as e:
+        return 1, "", str(e)
+
+
+def is_git_worktree(path: Path) -> bool:
+    """Return True when path is inside a Git worktree. VCS is On-demand."""
+    rc, out, _ = run_git(["rev-parse", "--is-inside-work-tree"], cwd=path)
+    return rc == 0 and out.strip().lower() == "true"