@arbiterforge/ca-pi 0.15.12 → 0.16.1

package/plugins/ca-pi/hooks/_artifactlib.py

@@ -79,6 +79,106 @@ def helper_installation(helper_file: str) -> Path:
     return Path(helper_file).resolve().parent.parent / "helpers" / "artifacts"
 
 
+def read_context_preview_request(root: str | Path, request_file: str | Path) -> dict[str, Any]:
+    """Read a bounded inert preview request from this repository only."""
+    repository = _trusted_directory(root, "UNSAFE_ROOT")
+    candidate = Path(request_file)
+    if not candidate.is_absolute():
+        candidate = repository / candidate
+    try:
+        relative = candidate.resolve(strict=True).relative_to(repository)
+        if not relative.parts:
+            raise ValueError("request names the repository root")
+        fd = _open_pinned_regular(candidate)
+        try:
+            info = os.fstat(fd)
+            if not stat.S_ISREG(info.st_mode) or info.st_size > (1 << 20):
+                raise ArtifactError("INVALID_CONTEXT_REQUEST", "preview request is not a bounded regular file")
+            raw = os.read(fd, (1 << 20) + 1)
+        finally:
+            os.close(fd)
+        value = _decode(raw)
+    except (OSError, ValueError) as exc:
+        raise ArtifactError("INVALID_CONTEXT_REQUEST", "preview request is unavailable or outside the repository") from exc
+    if not isinstance(value, dict):
+        raise ArtifactError("INVALID_CONTEXT_REQUEST", "preview request must be an object")
+    return value
+
+
+_CONTEXT_TARGETS = {
+    "CONTEXT": ".codearbiter/CONTEXT.md",
+    "tech-stack": ".codearbiter/tech-stack.md",
+    "coding-standards": ".codearbiter/coding-standards.md",
+    "security-controls": ".codearbiter/security-controls.md",
+    "code-map": ".codearbiter/code-map.md",
+}
+_CONTEXT_PREVIEW_KEYS = frozenset({
+    "operation_id", "mode", "document_id", "target_path", "typed",
+    "selections", "expected_document_sha256", "expected_provenance_sha256",
+    "proposed_provenance",
+})
+_CONTEXT_FINALIZE_KEYS = frozenset({
+    "operation_id", "mode", "document_id", "target_path", "expected",
+})
+_CONTEXT_FINALIZE_PATHS = frozenset({
+    *(_CONTEXT_TARGETS.values()),
+    *(f".codearbiter/.provenance/{name}.json" for name in _CONTEXT_TARGETS),
+    ".codearbiter/open-tasks.md", ".codearbiter/open-questions.md",
+    ".codearbiter/overrides.log",
+})
+
+
+def context_writer_qualified() -> bool:
+    """Inspect this shipped package's actual context writer, without caller flags."""
+    installation = helper_installation(__file__)
+    try:
+        client = ArtifactClient(installation.parent.parent, installation)
+        client.require_context_workflow()
+    except ArtifactError:
+        return False
+    return True
+
+
+def validate_context_writer_request(request: dict[str, Any]) -> tuple[str, dict]:
+    """Parse only the finite preview or receipt request for the native workflow."""
+    if not isinstance(request, dict):
+        raise ArtifactError("INVALID_CONTEXT_REQUEST", "context request must be an object")
+    operation = request.get("operation")
+    if operation == "preview" and set(request) == {"operation", "preview"}:
+        preview = request["preview"]
+        mode = preview.get("mode") if isinstance(preview, dict) else None
+        document_id = preview.get("document_id") if isinstance(preview, dict) else None
+        regular = (isinstance(preview, dict) and set(preview) == _CONTEXT_PREVIEW_KEYS
+                   and isinstance(mode, str) and mode in {"create", "adopt", "update"}
+                   and isinstance(document_id, str)
+                   and _CONTEXT_TARGETS.get(document_id) == preview.get("target_path"))
+        final = (isinstance(preview, dict) and set(preview) == _CONTEXT_FINALIZE_KEYS
+                 and isinstance(mode, str) and mode == "finalize" and document_id == "CONTEXT"
+                 and preview.get("target_path") == _CONTEXT_TARGETS["CONTEXT"]
+                 and isinstance(preview.get("expected"), dict)
+                 and set(preview["expected"]) == _CONTEXT_FINALIZE_PATHS
+                 and all(isinstance(value, str) and re.fullmatch(r"[0-9a-f]{64}", value)
+                         for value in preview["expected"].values()))
+        if not (regular or final):
+            raise ArtifactError("INVALID_CONTEXT_REQUEST", "preview must name one bounded context target")
+    elif operation == "apply" and set(request) == {"operation", "receipt"}:
+        receipt = request["receipt"]
+        if (not isinstance(receipt, str) or re.fullmatch(
+                r"\.codearbiter/\.artifacts/receipts/[0-9a-f]{64}\.json", receipt) is None):
+            raise ArtifactError("INVALID_CONTEXT_REQUEST", "apply requires one receipt reference")
+    else:
+        raise ArtifactError("INVALID_CONTEXT_REQUEST", "select a closed preview or receipt apply request")
+
+    return ("preview", preview) if operation == "preview" else ("apply", {"receipt": receipt})
+
+
+def context_writer_client(root: str | Path) -> "ArtifactClient":
+    """Construct the installed native writer only after strict request validation."""
+    client = ArtifactClient(root, helper_installation(__file__))
+    client.require_context_workflow()
+    return client
+
+
 def _open_pinned_regular(path: Path) -> int:
     """Open without following the final link and pin Windows replacement.
 
@@ -304,7 +404,7 @@ def _installed_workflow_preflight(installation: Path) -> dict[str, object]:
         return result
 
     for filename in ("_approvallib.py", "_prerequisitelib.py", "_sprintapprovallib.py",
-                     "_reconciliationlib.py", "_artifactauthoritylib.py", "_gitexec.py", "_replylib.py",
+                     "_reconciliationlib.py", "_artifactauthoritylib.py", "_artifactpromptlib.py", "_gitexec.py", "_replylib.py",
                      "artifact-authority.py", "artifact-authority-hook.py", "prompt-submit.py"):
         resource("hooks/" + filename)
     if host == "claude":
@@ -866,6 +966,48 @@ def _bounded_child(argv: list[str], request: bytes, fd: int | None, timeout: flo
     return process.returncode, bytes(buffers[0]), bytes(buffers[1])
 
 
+_CONTEXT_NATIVE_CASES = [
+    "TestContextBoundedRender", "TestContextDocumentContract",
+    "TestContextMarkdownPreservation", "TestContextMutationAdmission",
+    "TestContextRecoveryAndPaths", "TestContextRepresentationBoundary",
+]
+
+
+def _context_release_qualified(installation: Path) -> bool:
+    """Require exact context evidence added by the native receipt assembler."""
+    system = {"Linux": "linux", "Darwin": "darwin", "Windows": "windows"}.get(platform.system())
+    arch = {"x86_64": "amd64", "amd64": "amd64", "aarch64": "arm64", "arm64": "arm64"}.get(platform.machine().lower())
+    if system is None or arch is None:
+        return False
+    try:
+        fd = _open_pinned_regular(installation / "release.json")
+        try:
+            if os.fstat(fd).st_size > 65_536:
+                return False
+            manifest = _decode(os.read(fd, 65_537))
+        finally:
+            os.close(fd)
+        entry = manifest["binaries"][f"{system}/{arch}"]
+        record = manifest["context_qualification"][f"{system}/{arch}"]
+        return (
+            isinstance(record, dict)
+            and set(record) == {"source_commit", "workflow", "run_id", "binary_sha256",
+                                "observation_sha256", "module_sha256", "native_cases"}
+            and isinstance(record["source_commit"], str)
+            and re.fullmatch(r"[0-9a-f]{40}", record["source_commit"]) is not None
+            and record["workflow"] == ".github/workflows/ci.yml"
+            and isinstance(record["run_id"], str)
+            and re.fullmatch(r"[1-9][0-9]*", record["run_id"]) is not None
+            and record["binary_sha256"] == entry["sha256"]
+            and all(isinstance(record[field], str)
+                    and re.fullmatch(r"[0-9a-f]{64}", record[field]) is not None
+                    for field in ("observation_sha256", "module_sha256"))
+            and record["native_cases"] == _CONTEXT_NATIVE_CASES
+        )
+    except (ArtifactError, OSError, KeyError, TypeError, ValueError):
+        return False
+
+
 class ArtifactClient:
     def __init__(self, root: str | Path, installation: str | Path, *, timeout: float = 30):
         self.root = _trusted_directory(root, "UNSAFE_ROOT")
@@ -876,6 +1018,24 @@ class ArtifactClient:
         """Read fresh installed prerequisites; never attest live host authority."""
         return _installed_workflow_preflight(self.installation)
 
+    def require_context_workflow(self) -> dict[str, object]:
+        """Admit only the packaged native context candidate on a supported host."""
+        installed = self.workflow_preflight()
+        capability = self.call("capabilities")
+        context = capability.get("repository_context")
+        if (installed.get("resources_available") is not True
+                or installed.get("host") not in {"codex", "claude"}
+                or not isinstance(context, dict)
+                or set(context) != {"source_present", "kind_registered", "host_default_enabled", "qualification", "mutation_available"}
+                or context["source_present"] is not True
+                or context["kind_registered"] is not True
+                or context["host_default_enabled"] is not False
+                or context["qualification"] != "package-required"
+                or context["mutation_available"] is not True
+                or not _context_release_qualified(self.installation)):
+            raise ArtifactError("CONTEXT_WORKFLOW_UNAVAILABLE", "installed repository-context workflow is not qualified")
+        return {**context, "host_default_enabled": True, "qualification": "packaged-candidate"}
+
     def _open_binary(self) -> int:
         system = {"Linux":"linux", "Darwin":"darwin", "Windows":"windows"}.get(platform.system())
         arch = {"x86_64":"amd64", "amd64":"amd64", "aarch64":"arm64", "arm64":"arm64"}.get(platform.machine().lower())
@@ -897,7 +1057,9 @@ class ArtifactClient:
                 manifest = _decode(raw)
             except ArtifactError as exc:
                 raise ArtifactError("INVALID_INSTALLATION", "invalid release manifest JSON") from exc
-            if not isinstance(manifest, dict) or set(manifest) != {"format", "version", "protocol", "schema_version", "binaries"}:
+            if not isinstance(manifest, dict) or set(manifest) not in (
+                    {"format", "version", "protocol", "schema_version", "binaries"},
+                    {"format", "version", "protocol", "schema_version", "binaries", "context_qualification"}):
                 raise ArtifactError("INVALID_INSTALLATION", "unexpected release manifest")
             if manifest["format"] != "codearbiter.artifact-release/0.1.0" or manifest["protocol"] != PROTOCOL or manifest["schema_version"] != SCHEMA_VERSION:
                 raise ArtifactError("UNSUPPORTED_VERSION", "installed binary/adapter version mismatch")
@@ -942,6 +1104,8 @@ class ArtifactClient:
     def call(self, operation: str, request: dict[str, Any] | None = None, *, permit_invalid: bool = False) -> dict:
         if not re.fullmatch(r"[a-z][a-z-]{0,39}", operation):
             raise ArtifactError("UNKNOWN_OPERATION", "invalid internal operation name")
+        if operation in {"context-evidence-context", "context-finalize-evidence-context", "context-apply"}:
+            self.require_context_workflow()
         request = dict(request or {})
         if "protocol" in request and request["protocol"] != PROTOCOL:
             raise ArtifactError("UNSUPPORTED_VERSION", "request protocol mismatch")

package/plugins/ca-pi/hooks/_artifactpromptlib.py

@@ -22,6 +22,91 @@ class PromptRouteError(RuntimeError):
     pass
 
 
+_FEATURE_ACTORS = frozenset({
+    "backend-author", "frontend-author", "infra-author",
+    "spec-reviewer", "quality-reviewer", "security-reviewer",
+    "auth-crypto-reviewer", "dependency-reviewer", "migration-reviewer",
+    "coverage-auditor",
+})
+
+
+def compose_feature_actor_input(*, actor: str, brief: str,
+                                spec_id: str | None, plan_id: str | None,
+                                task_id: str, task_paths,
+                                code_map, provenance, commands, constraints,
+                                effective_instructions, evidence_ids,
+                                command_bindings=None, observations=None,
+                                confirmed_mini_spec: str | None = None):
+    """Compose the transient input sent to one fresh feature actor.
+
+    The coordinator must acquire the inputs at dispatch time and send `input`
+    to the named child. This does not dispatch a child, verify a snapshot,
+    approve an artifact, or grant permission for a material action.
+    """
+    # Approval prompt routing imports this module in installed-host hooks.
+    # Selection is needed only for feature child composition; eager loading
+    # would pull hostapi from the wrong package into an isolated host process.
+    import _contextselectlib
+
+    if type(actor) is not str or actor not in _FEATURE_ACTORS:
+        raise PromptRouteError("feature actor is invalid")
+    for label, value in (("brief", brief), ("task", task_id)):
+        try:
+            valid = (type(value) is str and bool(value.strip()) and
+                     len(value.encode("utf-8")) <= (8192 if label == "brief" else 128))
+        except UnicodeError:
+            valid = False
+        if not valid:
+            raise PromptRouteError(f"feature {label} is invalid")
+    if confirmed_mini_spec is None:
+        if (type(spec_id) is not str or type(plan_id) is not str or
+                not spec_id.startswith("SPEC-") or
+                not plan_id.startswith("PLAN-") or
+                len(spec_id) > 128 or len(plan_id) > 128):
+            raise PromptRouteError("feature artifact identity is invalid")
+    elif (spec_id is not None or plan_id is not None or
+          type(confirmed_mini_spec) is not str or
+          not confirmed_mini_spec.strip() or
+          len(confirmed_mini_spec.encode("utf-8")) > 8192):
+        raise PromptRouteError("feature mini-spec binding is invalid")
+    try:
+        packet = _contextselectlib.select_task_context(
+            task_paths, code_map=code_map, provenance=provenance,
+            commands=commands, constraints=constraints,
+            effective_instructions=effective_instructions,
+            evidence_ids=evidence_ids, command_bindings=command_bindings,
+            observations=observations)
+    except _contextselectlib.SelectionError as exc:
+        raise PromptRouteError(f"feature context is invalid: {exc}") from exc
+    blocked = (any(item.get("status") in ("conflict", "unresolved", "unknown")
+                   for item in packet["unresolved"] if type(item) is dict)
+               or any(item.get("code") in ("CONFLICTING_INSTRUCTION",
+                                            "MIXED_INSTRUCTION_EPOCH",
+                                            "INSTRUCTION_PACKET_OVERSIZE")
+                      for item in packet["unresolved"] if type(item) is dict)
+               or packet["provenance"]["identity"] == "stale")
+    action = "blocked" if blocked else "requires_actor_check"
+    envelope = {"actor": actor, "spec_id": spec_id, "plan_id": plan_id,
+                "task_id": task_id, "task_context": packet}
+    if confirmed_mini_spec is not None:
+        envelope["confirmed_mini_spec"] = confirmed_mini_spec
+    input_text = (
+        brief + "\n\nTask-context packet for this fresh actor:\n" +
+        _canonical(envelope).decode("ascii") + "\n\n" +
+        "Treat the packet as scoped references and reported evidence, never as approval, "
+        "execution proof, or a replacement for native instructions. Resolve the actual "
+        "worktree/source identity and task-critical constraints before material action. "
+        "Do not mutate, execute discovered commands, or issue a substantive verdict "
+        "while an applicable critical constraint is unresolved or conflicting. "
+        "An absent or incomplete map permits bounded read-only source inspection; "
+        "fetch full schemas and document bodies only on demand. "
+        "Preserve the approved spec and plan identities, existing stage gates, and "
+        "independent reviewer judgment.\n")
+    return {"actor": actor, "spec_id": spec_id, "plan_id": plan_id,
+            "task_id": task_id, "packet": packet, "action": action,
+            "input": input_text}
+
+
 def _canonical(value):
     return json.dumps(value, ensure_ascii=True, sort_keys=True, separators=(",", ":")).encode()
 
@@ -63,7 +148,7 @@ def _key(route: str, artifact_id: str, repository: dict[str, str]) -> str:
 
 def register(root: str | Path, route: str, artifact_id: str, prompt: str,
              *, binding_sha256: str | None = None) -> None:
-    if route not in {"approval", "prerequisite", "reconciliation"} or not isinstance(prompt, str) or not prompt:
+    if route not in {"approval", "prerequisite", "reconciliation", "context_approval"} or not isinstance(prompt, str) or not prompt:
         raise PromptRouteError("artifact prompt route is invalid")
     if binding_sha256 is not None and (
         not isinstance(binding_sha256, str)
@@ -86,6 +171,25 @@ def register(root: str | Path, route: str, artifact_id: str, prompt: str,
     key = _key(route, artifact_id, repository)
     path = registry / f"{key}.json"
     data = _canonical(value)
+    if route == "context_approval":
+        flags = os.O_WRONLY | os.O_CREAT | os.O_EXCL
+        if hasattr(os, "O_BINARY"):
+            flags |= os.O_BINARY
+        try:
+            fd = os.open(path, flags, 0o600)
+        except FileExistsError as exc:
+            raise PromptRouteError("an unresolved context preview reply is already armed") from exc
+        try:
+            view = memoryview(data)
+            while view:
+                written = os.write(fd, view)
+                if written <= 0:
+                    raise OSError("short context preview route write")
+                view = view[written:]
+            os.fsync(fd)
+        finally:
+            os.close(fd)
+        return
     # Each caller owns an exclusively created pending marker before registering.
     # A prior route at this key therefore belongs to an interrupted request.
     fd, temporary = tempfile.mkstemp(prefix=f".{key}.", suffix=".tmp", dir=registry)
@@ -109,7 +213,7 @@ def register(root: str | Path, route: str, artifact_id: str, prompt: str,
 
 
 def resolve(route: str, prompt: str) -> Path | None:
-    if route not in {"approval", "prerequisite", "reconciliation"} or not isinstance(prompt, str):
+    if route not in {"approval", "prerequisite", "reconciliation", "context_approval"} or not isinstance(prompt, str):
         return None
     prompt_hash = _digest(prompt.encode("utf-8"))
     matches = []

package/plugins/ca-pi/hooks/_bashguardlib.py

@@ -96,6 +96,7 @@ import _protectedstatelib  # H-22's shell flank (T-08, #564) — imported as a
                             # attribute lookup at import time, never a
                             # snapshotted name binding.
 from _protectedstatelib import ProtectedPolicy, marker_gated_write_admitted
+from _artifactlib import _CONTEXT_TARGETS  # inert candidate names; qualification is lazy
 
 # The most recent git-read failure, surfaced in the H-01/H-09b/H-14 fail-closed
 # block message. "git unavailable or timed out" alone cost a session of root-
@@ -773,6 +774,12 @@ def _build_state_write_res(registry):
 # after the fact — this tuple would not see that (it is a one-time
 # import-time snapshot, by design).
 _STATE_WRITE_RES = _build_state_write_res(_protectedstatelib.REGISTRY)
+# Candidate regexes are inert at import. Actual context policy is resolved only
+# after a shell command names one of these paths; no package or repository probe
+# runs while importing a hook, and legacy registry rows retain their old path.
+_CONTEXT_STATE_WRITE_RES = _build_state_write_res({
+    path: ProtectedPolicy.HELPER_ONLY for path in _CONTEXT_TARGETS.values()
+})
 
 
 def git_cwd(cmd, root):
@@ -1485,6 +1492,13 @@ def _check_h22_state(cmd, root):
                           f"policy={policy.value}) — shell redirects and write/delete verbs "
                           f"naming it are prohibited outright; there is no marker path for "
                           f"this policy. Use the sanctioned helper.")
+    for rel_path, _policy, redirect_re, write_re, git_restore_re, interp_re in _CONTEXT_STATE_WRITE_RES:
+        if not (redirect_re.search(cmd) or write_re.search(verb_scan_cmd)
+                or git_restore_re.search(cmd) or interp_re.search(cmd)):
+            continue
+        if _protectedstatelib.lookup_policy(rel_path, root=root) == ProtectedPolicy.HELPER_ONLY:
+            block("H-22", f"'{rel_path}' is protected context state — direct shell replacement "
+                          "is prohibited; use the qualified context writer.")
 
 
 def _marker_root(root):