@arbiterforge/ca-pi 0.15.10 → 0.16.0

package/plugins/ca-pi/hooks/init-codearbiter.py

@@ -12,11 +12,16 @@
 # Usage:
 #   python init-codearbiter.py [--root PATH] [--stage N]
 #   python init-codearbiter.py --check        # report state, create nothing
+#   python init-codearbiter.py --check --passive --root PATH  # external pre-session read
 #   python init-codearbiter.py --repair-lock-exclusion [--root PATH]
+#   python init-codearbiter.py --root PATH --context-request FILE  # bounded writer bridge, including initialized refresh
 
 import argparse
+import json
 import subprocess
 import os
+import re
+import stat
 import sys
 
 sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
@@ -25,6 +30,8 @@ from _taskboardlib import DONE_TASKS  # noqa: E402 — shared archive template (
 import hostapi  # noqa: E402 — host seam (ADR-0011)
 import _hooklib  # noqa: E402 — set_host DI seam (#257)
 import _entrylib  # noqa: E402 — shared run() dispatch (jscpd dedup)
+from _activationlib import passive_activation_inventory  # noqa: E402
+import _artifactlib  # noqa: E402
 
 # NOTE: this stub deliberately does NOT contain the initialization sentinel
 # (an HTML comment wrapping the word INITIALIZED). The SessionStart hook greps
@@ -122,17 +129,132 @@ def project_root(opt):
     return os.path.abspath(os.getcwd())
 
 
+def _regular_scaffold_entry(path, *, directory):
+    """Reject aliases and reparse points before reading or creating scaffold state."""
+    try:
+        info = os.lstat(path)
+    except OSError:
+        return False
+    reparse = getattr(info, "st_file_attributes", 0) & getattr(
+        stat, "FILE_ATTRIBUTE_REPARSE_POINT", 0)
+    return not reparse and (stat.S_ISDIR(info.st_mode) if directory
+                            else stat.S_ISREG(info.st_mode))
+
+
+def _scaffold_inventory(cad, ctx, requested_stage):
+    """Return absent scaffold names only when surviving state is safe to retain."""
+    names = ("CONTEXT.md", *FILES)
+    if os.path.lexists(cad) and not _regular_scaffold_entry(cad, directory=True):
+        raise SystemExit(f"REFUSING: {cad} is not a regular project-state directory.")
+    present = {name for name in names if os.path.lexists(os.path.join(cad, name))}
+    if not present:
+        if os.path.isdir(cad) and os.listdir(cad):
+            raise SystemExit(f"REFUSING: {cad} has existing state without a scaffold; inspect it first.")
+        return list(names), False
+    for name in present:
+        path = os.path.join(cad, name)
+        if not _regular_scaffold_entry(path, directory=False):
+            raise SystemExit(f"REFUSING: {path} is not a regular scaffold file.")
+    if "CONTEXT.md" not in present:
+        # A missing stub amid content/provenance may be an interrupted native
+        # transaction. Only the known scaffold prefix can be resumed here.
+        unexpected = set(os.listdir(cad)) - set(FILES)
+        if unexpected:
+            raise SystemExit(f"REFUSING: {ctx} is absent amid other project state; inspect prior write outcome.")
+    else:
+        try:
+            with open(ctx, encoding="utf-8") as handle:
+                body = handle.read()
+        except (OSError, UnicodeError) as exc:
+            raise SystemExit(f"REFUSING: cannot inspect {ctx}: {exc}") from None
+        enabled, malformed = _hooklib.frontmatter_enabled_text(body)
+        lines = body.splitlines()
+        boundary = next((index for index, line in enumerate(lines[1:], 1)
+                         if line.strip() == "---"), None)
+        stages = ([match.group(1) for line in lines[1:boundary]
+                   if (match := re.fullmatch(r"\s*stage:\s*([1-9][0-9]*)\s*", line))]
+                  if boundary is not None else [])
+        if (not enabled or malformed or len(stages) != 1 or
+                _hooklib.initialized_body_text(body)):
+            raise SystemExit(f"REFUSING: {ctx} is invalid or initialized; inspect before recovery.")
+        if requested_stage is not None and int(stages[0]) != requested_stage:
+            raise SystemExit(f"REFUSING: {ctx} stage differs from --stage; preserve existing context.")
+    headers = {"open-tasks.md": "# Open tasks", "done-tasks.md": "# Done tasks",
+               "open-questions.md": "# Open questions",
+               "overrides.log": "# codeArbiter override log"}
+    for name in present & headers.keys():
+        path = os.path.join(cad, name)
+        try:
+            with open(path, encoding="utf-8") as handle:
+                valid = handle.readline().rstrip("\r\n").startswith(headers[name])
+        except (OSError, UnicodeError):
+            valid = False
+        if not valid:
+            raise SystemExit(f"REFUSING: {path} has an unrecognized header; preserve it for review.")
+    if "last-checkpoint" in present:
+        try:
+            with open(os.path.join(cad, "last-checkpoint"), encoding="utf-8") as handle:
+                valid = bool(re.fullmatch(r"[0-9]+\s*", handle.read()))
+        except (OSError, UnicodeError):
+            valid = False
+        if not valid:
+            raise SystemExit("REFUSING: last-checkpoint is malformed; preserve it for review.")
+    return [name for name in names if name not in present], True
+
+
+def _create_scaffold_file(path, content, *, newline=None):
+    """Create once; a concurrent new file is a conflict, never an overwrite."""
+    flags = os.O_WRONLY | os.O_CREAT | os.O_EXCL
+    flags |= getattr(os, "O_NOFOLLOW", 0)
+    try:
+        fd = os.open(path, flags, 0o666)
+    except FileExistsError:
+        raise SystemExit(f"REFUSING: {path} appeared during scaffold recovery.") from None
+    with os.fdopen(fd, "w", encoding="utf-8", newline=newline) as handle:
+        handle.write(content)
+
+
 def main(argv=None):
     ap = argparse.ArgumentParser(add_help=True)
     ap.add_argument("--root")
     ap.add_argument("--stage", type=int)
     ap.add_argument("--check", action="store_true")
+    ap.add_argument("--passive", action="store_true", help=(
+        "inspect explicit root before host activation; no Git or network probes"))
+    ap.add_argument("--context-request", help=argparse.SUPPRESS)
     ap.add_argument("--repair-lock-exclusion", action="store_true", help=(
         "repair only Git-local info/exclude for an existing scaffold; retain the "
         "task-board OS lock, never rewrite project state (cannot combine with --check/--stage)"))
     args = ap.parse_args(argv)
+    if args.context_request:
+        if not args.root or args.stage is not None or args.check or args.passive or args.repair_lock_exclusion:
+            ap.error("--context-request requires --root and excludes scaffold flags")
+        try:
+            root = _artifactlib._trusted_directory(args.root, "UNSAFE_ROOT")
+            request = _artifactlib.read_context_preview_request(root, args.context_request)
+            operation, payload = _artifactlib.validate_context_writer_request(request)
+            client = _artifactlib.context_writer_client(root)
+            if operation == "preview":
+                from _artifactauthoritylib import arm_context_preview
+                result = arm_context_preview(root, client, payload)
+            else:
+                result = client.call("context-apply", payload)
+        except RuntimeError as exc:
+            raise SystemExit(f"REFUSING context request: {exc}") from None
+        print(json.dumps(result, sort_keys=True))
+        return
+    if args.passive:
+        if not args.check or not args.root or args.stage is not None or args.repair_lock_exclusion:
+            ap.error("--passive requires --check and --root; excludes --stage and repair")
+        try:
+            report = passive_activation_inventory(args.root)
+        except (OSError, UnicodeError, ValueError) as exc:
+            raise SystemExit(f"REFUSING passive inspection: {exc}") from None
+        print(json.dumps(report, sort_keys=True))
+        return
     if args.repair_lock_exclusion and (args.check or args.stage is not None):
         ap.error("--repair-lock-exclusion cannot combine with --check or --stage")
+    requested_stage = args.stage
     if args.stage is None:
         args.stage = 1
 
@@ -149,13 +271,17 @@ def main(argv=None):
     name = os.path.basename(root.rstrip("/\\")) or "project"
 
     if args.check:
+        if os.path.lexists(cad) and not _regular_scaffold_entry(cad, directory=True):
+            raise SystemExit(f"REFUSING: {cad} is not a regular project-state directory.")
+        if os.path.lexists(ctx) and not _regular_scaffold_entry(ctx, directory=False):
+            raise SystemExit(f"REFUSING: {ctx} is not a regular scaffold file.")
         if os.path.exists(ctx):
             print(f"ALREADY SCAFFOLDED: {ctx} exists.")
             with open(ctx, encoding="utf-8", errors="replace") as f:
                 text = f.read()
-            import re
-            initd = bool(re.search(r"(?m)^\s*<!--\s*INITIALIZED\s*-->\s*$", text))
-            print("arbiter: " + ("enabled" if re.search(r"(?m)^arbiter:\s*enabled\s*$", text) else "not enabled"))
+            initd = _hooklib.initialized_body_text(text)
+            enabled, _malformed = _hooklib.frontmatter_enabled_text(text)
+            print("arbiter: " + ("enabled" if enabled else "not enabled"))
             print("initialized body: " + ("yes" if initd else
                   "no (run " + _cc + " or " + _dc + ")"))
         else:
@@ -164,7 +290,8 @@ def main(argv=None):
 
     from _taskexcludelib import ensure_task_lock_excluded, TaskExclusionError
     if args.repair_lock_exclusion:
-        if not os.path.isfile(ctx) or os.path.islink(ctx):
+        if (not _regular_scaffold_entry(cad, directory=True) or
+                not _regular_scaffold_entry(ctx, directory=False)):
             raise SystemExit("REFUSING: task lock exclusion repair requires an existing scaffold.")
         try:
             result = ensure_task_lock_excluded(root, required=True)
@@ -173,7 +300,8 @@ def main(argv=None):
         print(f"task lock exclusion: {result}")
         return
 
-    if os.path.exists(ctx):
+    absent, recovering = _scaffold_inventory(cad, ctx, requested_stage)
+    if recovering and not absent:
         raise SystemExit(
             f"REFUSING: {ctx} already exists. .codearbiter/ is already scaffolded here. "
             f"To populate it, run {_cc} or {_dc}; to repair, edit by hand.")
@@ -187,19 +315,16 @@ def main(argv=None):
 
     os.makedirs(cad, exist_ok=True)
     created = []
-    if not os.path.exists(ctx):
-        with open(ctx, "w", encoding="utf-8") as f:
-            f.write(CONTEXT.format(stage=args.stage, name=name,
-                                   create_context=_cc, decompose=_dc))
+    if "CONTEXT.md" in absent:
+        _create_scaffold_file(ctx, CONTEXT.format(stage=args.stage, name=name,
+                              create_context=_cc, decompose=_dc))
         created.append("CONTEXT.md")
     for fname, content in FILES.items():
-        fp = os.path.join(cad, fname)
-        if not os.path.exists(fp):
+        if fname in absent:
             # Match taskwrite's LF output for this shared append-only template
             # on Windows too; other scaffold files retain their existing EOLs.
             newline = "\n" if fname == "done-tasks.md" else None
-            with open(fp, "w", encoding="utf-8", newline=newline) as f:
-                f.write(content)
+            _create_scaffold_file(os.path.join(cad, fname), content, newline=newline)
             created.append(fname)
 
     # #161: install the git-level enforcement backstop (pre-commit/pre-push) so
@@ -215,9 +340,12 @@ def main(argv=None):
     except Exception as e:  # noqa: BLE001
         print(f"git hooks: install skipped ({e})", file=sys.stderr)
 
-    print(f"SCAFFOLDED .codearbiter/ at {cad}")
+    print(f"{'RECOVERED' if recovering else 'SCAFFOLDED'} .codearbiter/ at {cad}")
     print("created: " + ", ".join(created))
-    print(f"arbiter: enabled (stage {args.stage}); CONTEXT.md is a stub (no <!--INITIALIZED--> sentinel).")
+    if recovering and "CONTEXT.md" not in created:
+        print("arbiter: enabled; existing uninitialized CONTEXT.md and history retained.")
+    else:
+        print(f"arbiter: enabled (stage {args.stage}); CONTEXT.md is a stub (no <!--INITIALIZED--> sentinel).")
     print(f"Next: run {_cc} (source exists) or {_dc} (greenfield) to populate.")
 
 

package/plugins/ca-pi/hooks/prompt-submit.py

@@ -65,6 +65,7 @@ import sys
 sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
 import hostapi  # noqa: E402 — host seam (ADR-0011)
 import _approvallib  # noqa: E402 — host-owned artifact approval capture
+import _artifactauthoritylib  # noqa: E402 — exact context preview approval capture
 import _hooklib  # noqa: E402
 import _modelib  # noqa: E402 — mode plane core (T-06..T-16, Lane A)
 import _prerequisitelib  # noqa: E402 — host-owned prerequisite capture
@@ -485,6 +486,15 @@ def _handle_user_prompt_submit(payload, host):
         )
         if reconciliation:
             contexts.append(reconciliation)
+        context_preview = _artifactauthoritylib.capture_context_preview_from_hook(
+            root=root,
+            plugin_root=host.plugin_root(),
+            prompt=prompt,
+            host=host.name,
+            session_id=session_id,
+        )
+        if context_preview:
+            contexts.append(context_preview)
         approval_context = "\n".join(contexts)
     if not active:
         if not approval_context:
@@ -513,6 +523,10 @@ def _handle_precompact(payload, host):
     if not _hooklib.arbiter_active(root):
         return 0
     _bump_compaction_generation(_hooklib.marker_root(payload), session_id)
+    # Read-time context pointers have their own worktree-local epoch. A
+    # surviving read marker cannot prove that a compacted actor still carries
+    # those pointers. Keep this separate from the persona generation above.
+    _readinjectlib.bump_context_generation(root, session_id)
     return 0
 
 

package/plugins/ca-pi/hooks/session-start.py

@@ -34,7 +34,7 @@ sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
 import hostapi  # noqa: E402 — host seam (ADR-0011): plugin root + capability flags
 from _durabilitylib import is_ephemeral_path  # noqa: E402
 from _hooklib import (  # noqa: E402
-    frontmatter_enabled, get_host, marker_root, project_root, set_host,
+    frontmatter_enabled, get_host, initialized_body_text, marker_root, project_root, set_host,
     utf8_stdio, write_text_atomic,
 )
 from _standuplib import (  # noqa: E402
@@ -59,7 +59,6 @@ import _updatelib  # noqa: E402 — update-available notifier (cache read + noti
 from _modelib import _DEV_PENDING_CLOSE_MAX, _settle_dev_close  # noqa: E402,F401
 import _modelib  # noqa: E402
 
-INITIALIZED_RE = re.compile(r"<!--\s*INITIALIZED\s*-->")
 STAGE_RE = re.compile(r"^stage:\s*([0-9]+)", re.I | re.M)
 CONFIRM_RE = re.compile(r"CONFIRM-[0-9]+")
 
@@ -853,7 +852,7 @@ def clear_mode_marker(root, host_name=None, session_id=None, now=None):
     _settle_dev_close(root, marker=marker, new_line=line, host_name=host_name)
 
 
-def provenance_drift_line(root, runner=None):
+def provenance_drift_line(root, runner=None, report_unknown=False):
     """One-line SessionStart drift notice, or "" when clean/degraded.
 
     Wraps _provenancelib.startup_drift_line; any failure degrades to "" so the
@@ -861,12 +860,26 @@ def provenance_drift_line(root, runner=None):
     injectable so tests are deterministic/offline; production passes None which
     lets the lib bind its default `git -C root hash-object` runner. (T-16)"""
     try:
-        return _provenancelib.startup_drift_line(
-            root, runner=runner, cmd_ref=get_host().cmd_ref)
+        unknown = [] if report_unknown else None
+        line = _provenancelib.startup_drift_line(
+            root, runner=runner, cmd_ref=get_host().cmd_ref, unknown=unknown)
+        if report_unknown and unknown:
+            return "context coverage: unknown ({}) -- run {}".format(
+                unknown[0], get_host().cmd_ref("context-check"))
+        return line
     except Exception:  # noqa: BLE001 — never crash session startup
         return ""
 
 
+def context_coverage_line(root):
+    """Bounded provenance coverage notice; no source hash or authority claim."""
+    try:
+        return _provenancelib.startup_context_coverage_line(
+            root, cmd_ref=get_host().cmd_ref)
+    except Exception:  # noqa: BLE001 — never crash session startup
+        return "context coverage: unknown -- run /ca:context-check"
+
+
 # --- Update-available notifier (spec: update-available-notifier.md) ---------
 # codeArbiter ships via a third-party marketplace, which Claude Code does NOT
 # auto-update by default. This surfaces a single line when the cached "latest"
@@ -1110,6 +1123,11 @@ def emit_daily_briefing(root, summary, date_iso, marker_present, ctx_text=None,
 
 
 def main():
+    # This is the ACTIVE host startup path. It may settle mode state, heal a
+    # host-owned statusline pin, install Git enforcement, and spawn fetch/update
+    # children. An unfamiliar repository must be inspected by the explicit-root
+    # init --check --passive route BEFORE entering a host session; a later skill
+    # cannot retroactively prevent SessionStart effects.
     utf8_stdio()
     # get_host() (#257): resolves the SAME Host run(host) already primed via
     # set_host(), instead of a second hostapi.load_host() disk/probe.
@@ -1231,7 +1249,7 @@ def main():
     emit_banner(getattr(host, "name", "unknown"), mode)
 
     ctx_text = read_text(ctx) or ""
-    if not INITIALIZED_RE.search(ctx_text):
+    if not initialized_body_text(ctx_text):
         emit_not_initialized(root, host, mode)
         sys.exit(0)
 
@@ -1246,8 +1264,9 @@ def main():
     emit_task_summary(ot_text)
 
     # --- Passive provenance drift notice (T-16, spec pillar 4) ---
-    _drift = provenance_drift_line(root)
+    _drift = provenance_drift_line(root, report_unknown=True)
     emit_provenance_drift(_drift)
+    emit_provenance_drift(context_coverage_line(root))
 
     # --- Update-available notice (AC-1/AC-2/AC-3) --------------------------
     _update = update_notice_line(plugin)

package/plugins/ca-pi/includes/artifacts.md

@@ -301,6 +301,47 @@ rewrite the returned envelope yourself.
 The host hooks bind the exact launch call, child start and
 the child's first stop; a pasted or coordinator-authored decision is not review
 authority.
+
+When reviewing completed work that relies on a verification run, linked
+worktrees or supporting evidence, explicitly select the completion path. Add
+`--completion-receipt <exact-published-receipt>` once per task and
+`--supporting-file <absolute-regular-file>` for each supporting document to the
+review `arm` command. A task review selects one verification receipt; a scope
+review selects the exact receipt for every member. Supporting files require a
+receipt selection. The existing review-before-verification path remains
+available; it does not satisfy an explicitly requested completion review.
+
+The native engine validates the selected published verification chain and
+derives the worktree mappings from its qualified observation. It retains the
+selected identities, worktree closure and supporting bytes in the immutable
+context. Supporting material is data for review, not authority. Selection is
+explicit: no newest-receipt search, directory import or attachment execution.
+At most 16 regular files are admitted, each at most 64 KiB and together at most
+256 KiB; links, reparse indirection, duplicate paths and changed content fail
+closed. Read canonical spec and plan artifacts through the native artifact API;
+they cannot be imported as supporting files. The generated prompt directs the reviewer to assess performed work
+against each criterion, step and `done_when` obligation, using selected evidence
+and source references. A consistent plan or an empty diff is insufficient.
+
+Use the returned `completion_sha256` in the native `task-review` or
+`accept-scope` request. The completed review and its exact verification run must
+agree; a definition-only review or a different successful run is rejected.
+The recorded task selection remains required by downstream freshness and scope
+acceptance. Scope review uses validated task completion bindings. If verification
+is rerun, obtain and record its completed task review before selecting that run
+for scope review; do not infer equivalence between receipts.
+
+Creating the first completion context recomputes the current raw worktree
+fingerprint and requires it to match the selected verifier's recorded fingerprint.
+Later freshness checks allow native task-status and execution bookkeeping updates
+in validated canonical artifacts while retaining their normative content hashes.
+Changes to task definitions, other HTML or other governance files still affect
+freshness under the normal snapshot policy. The closure covers
+tracked working-tree bytes and non-ignored untracked files, not ignored
+dependencies or outputs. The completion assessment is still an independent
+reviewer's judgment; schema validation does not prove that every file was read
+or every conclusion is correct. Preserve the unchanged launch envelope and
+genuine host capture throughout this path.
 Publish the completed request through the same `publish` command. `task-review`
 records the separate verification and spec-review receipts. After every task in
 the scope reaches `REVIEW`, reverify against one current source snapshot, run the

package/plugins/ca-pi/includes/author-tdd-workflow.md

@@ -1,15 +1,27 @@
 # Author TDD workflow — non-negotiable, fixed order
 
-Canonical for the author agents (`backend-author`, `frontend-author`). Loaded via each agent's
+Canonical for the author agents (`backend-author`, `frontend-author`, `infra-author`). Loaded via each agent's
 Required Reading; the agent bodies do not restate it. This is the worker's execution order for
 one task — the tdd skill's phase gates govern the lane above it.
 Apply `<plugin-root>/includes/verification-boundary.md` throughout.
 
+Use the Phase 1 checklist for the owning route. For a bug-origin `/fix`, carry the
+current expectation, cited evidence, supported cause, and regression oracle into
+the existing obligation ledger; confirm the original caller's repair authority and
+source freshness through the fix owner. Do not fabricate a feature artifact. For
+`/feature`, keep the approved spec and its criteria; for `/refactor`, keep its
+approved surface and parity contract. An ADR remains a user-attributed decision
+through `/adr`, never an author shortcut.
+
 Fixed order. Do not skip or reorder.
 
-1. **Write failing tests** — one test per obligation in the Phase 1 checklist
-2. **Confirm tests fail for the right reason** — run the test command from `tech-stack.md`; the failure must match the obligation, not an unrelated error
+1. **Map failing tests** — bind each Phase 1 obligation to a test ID. For `/fix`, assess an existing failing test against target red using the current regression oracle and evidence. Name the existing test ID in the ledger and reuse that named existing target-red test when its oracle is adequate and the assertion matches the defect. Do not duplicate a test because of its age or because it predates repair. Add tests only for uncovered obligations.
+2. **Confirm tests are red for the right reason** — run the test command from `tech-stack.md`; the target failure must match the obligation. Record unrelated existing failures in the baseline; an unrelated failure is not target red. An import or setup error is not target red. Preserve and report their identities and outputs. Required commit gates remain blocked while required checks fail. Do not skip tests, suppress failures, or waive gates to proceed.
 3. **Write minimum implementation** — only enough code to make the failing tests pass; no extra scope
-4. **Run impact-bounded local suite** — every affected test green; exhaustive and cross-platform proof runs in exact-head hosted CI before merge
+4. **Run impact-bounded local suite** — rerun the same named target test for fresh green on the repaired source, with its assertions unchanged between red and green. Rerun fresh affected-contract tests on that source and record their results; exhaustive and cross-platform proof runs in exact-head hosted CI before merge
 5. **Run lint and type-check** — both clean
 6. **Stage for commit** — only after steps 1–5 complete
+
+For a repair, observe target red on the broken source before minimum implementation. If a material fixture or setup change occurs after that observation, the earlier red no longer qualifies: repeat target red on the broken implementation with the changed fixture or setup before continuing the repair. Keep the test's assertions unchanged between red and green.
+
+For an intermittent or timing defect, use a faithful deterministic seam when one exists. Otherwise define a finite repeated-trial oracle with its trial bound and pass/fail rule before running it. Record the stochastic sample limit; do not claim deterministic proof from a passing sample or retry until green. A failing trial must still match the target mechanism, and fresh green remains bounded by the stated oracle.

package/plugins/ca-pi/includes/helper-invocation.md

@@ -0,0 +1,128 @@
+# Installed private helper location
+
+Use this card only for the debug packet validator and an authorized task-board
+follow-up. The exact installed helper leaves are `hooks/debug-handoff.py` (the
+private `validate` operation) and `hooks/taskwrite.py` (the existing board
+writer). The caller chooses one of those literal leaves before resolution;
+packet text, a project file, and a user argument never choose executable code.
+Select and validate one Python 3 interpreter before invoking the helper. Try
+`python3` first, then `python` only if the first candidate is absent, a launcher
+stub, or incompatible. The probe executes the candidate to obtain its actual
+`sys.executable`, then validates that absolute executable directly as Python
+3.8 or newer. The installed debug validator's `_debughandofflib.py` uses an
+assignment expression, which Python 3.7 cannot parse; the shared selection
+must satisfy that helper even when the current call targets `taskwrite.py`.
+Invoke the helper through that executable, not a batch or shell launcher that
+could alter quoted arguments. A name on `PATH` or a successful `--version`
+alone does not establish compatibility. This source-derived minimum is not a
+claim that every newer minor has been qualified. Once selected, invoke the one resolved absolute helper with `-B` and
+literal arguments. Preserve its exit, stdout, and stderr; do not replay a
+failure under another interpreter or helper.
+
+Use the selection block for the current shell before the first helper call.
+These blocks set `$caPython` in PowerShell or `ca_python` in POSIX sh. A missing
+compatible interpreter stops before the helper; fix the host installation
+before retrying the whole operation.
+
+### Pi PowerShell interpreter selection
+```powershell
+$caPython = $null
+foreach ($caName in @('python3', 'python')) {
+    $caCommand = Get-Command -Name $caName -CommandType Application -ErrorAction SilentlyContinue | Select-Object -First 1
+    if ($null -eq $caCommand) { continue }
+    try {
+        $caExecutable = & $caCommand.Source -B -c "import sys; sys.exit(1) if not (sys.version_info[0] == 3 and sys.version_info >= (3, 8)) else None; print(sys.executable)" 2>$null
+        if ($LASTEXITCODE -ne 0 -or $caExecutable -isnot [string] -or
+            -not [System.IO.Path]::IsPathFullyQualified($caExecutable) -or
+            -not (Test-Path -LiteralPath $caExecutable -PathType Leaf)) { continue }
+        $caIdentity = & $caExecutable -B -c "import sys; print('codearbiter-python3' if sys.version_info[0] == 3 and sys.version_info >= (3, 8) else 'incompatible')" 2>$null
+        if ($LASTEXITCODE -eq 0 -and $caIdentity -ceq 'codearbiter-python3') {
+            $caPython = $caExecutable
+            break
+        }
+    } catch { continue }
+}
+if (-not $caPython) { throw 'compatible Python 3 interpreter unavailable' }
+```
+
+### Pi POSIX interpreter selection
+```sh
+ca_python=
+for ca_candidate in python3 python; do
+  ca_path=$(command -v "$ca_candidate" 2>/dev/null) || continue
+  case "$ca_path" in /*) ;; *) continue;; esac
+  [ -f "$ca_path" ] || continue
+  ca_executable=$("$ca_path" -B -c 'import sys; sys.exit(1) if not (sys.version_info[0] == 3 and sys.version_info >= (3, 8)) else None; print(sys.executable)' 2>/dev/null) || continue
+  case "$ca_executable" in
+    /*) ;;
+    [A-Za-z]:'\'*)
+      command -v cygpath >/dev/null 2>&1 || continue
+      ca_executable=$(cygpath -u "$ca_executable") || continue ;;
+    *) continue ;;
+  esac
+  [ -f "$ca_executable" ] && [ -x "$ca_executable" ] || continue
+  ca_identity=$("$ca_executable" -B -c 'import sys; print("codearbiter-python3" if sys.version_info[0] == 3 and sys.version_info >= (3, 8) else "incompatible")' 2>/dev/null) || continue
+  if [ "$ca_identity" = codearbiter-python3 ]; then ca_python=$ca_executable; break; fi
+done
+if [ -z "$ca_python" ]; then printf '%s\n' 'compatible Python 3 interpreter unavailable' >&2; exit 2; fi
+```
+
+Start from the absolute path of the **loaded installed entry resource** that
+the host actually supplied: `commands/task.md` or `commands/debug.md` on
+Claude, `skills/ca-task/SKILL.md` or `skills/ca-debug/SKILL.md` on Codex and
+Pi. The Codex and Pi skill directories are two levels below the package root;
+Claude's command directory is one level below it. Do not use the current directory, a project checkout,
+an unset `PLUGIN_ROOT`/`CLAUDE_PLUGIN_ROOT` token from a hook runner, `/hooks`,
+a source clone, or a recursive cache search. If the loaded resource, package
+identity, or exact helper is absent, report that failure and stop. Keep the
+current working directory at the intended project when invoking `taskwrite.py`.
+
+
+Pi's loaded `skills/ca-task/SKILL.md` or `skills/ca-debug/SKILL.md` is the
+anchor. `package.json` is the installed package identity marker; a written
+`<plugin-root>` string is not an executable path. Bind the selected resource
+and one literal helper leaf as above.
+
+### Pi PowerShell resolution
+```powershell
+$caResolvedResource = (Resolve-Path -LiteralPath $caLoadedResource -ErrorAction Stop).ProviderPath
+$caResourceDirectory = Split-Path -Parent $caResolvedResource
+$caInstalledRoot = (Resolve-Path -LiteralPath (Join-Path $caResourceDirectory '..\..') -ErrorAction Stop).ProviderPath
+$caManifest = Join-Path $caInstalledRoot 'package.json'
+if (-not (Test-Path -LiteralPath $caManifest -PathType Leaf)) { throw "installed ca-pi package identity missing" }
+$caHelper = Join-Path $caInstalledRoot $caHelperRelative
+if (-not (Test-Path -LiteralPath $caHelper -PathType Leaf)) { throw "installed helper missing: $caHelper" }
+```
+
+### Pi POSIX resolution
+```sh
+case "$ca_loaded_resource" in /*) ;; *) printf '%s\n' 'loaded installed resource must be absolute' >&2; exit 2;; esac
+if [ ! -f "$ca_loaded_resource" ]; then printf '%s\n' 'loaded installed resource missing' >&2; exit 2; fi
+ca_installed_root=$(CDPATH= cd -P "$(dirname "$ca_loaded_resource")/../.." && pwd -P) || exit 2
+if [ ! -f "$ca_installed_root/package.json" ]; then printf '%s\n' 'installed ca-pi package identity missing' >&2; exit 2; fi
+ca_helper=$ca_installed_root/$ca_helper_relative
+if [ ! -f "$ca_helper" ]; then printf '%s\n' 'installed helper missing' >&2; exit 2; fi
+```
+
+
+Never repair a missing installed helper by selecting a similarly named file
+from a checkout or cache. A missing or partial package blocks the operation.
+
+For private debug validation, select the literal leaf
+`hooks/debug-handoff.py` with the resolution block above. Supply one finite
+packet of at most 65,536 bytes through the host execution tool's stdin and
+retain that tool's timeout and output controls. The helper owns rejection of
+oversize input; never build a shell pipeline, command string, path argument,
+or unbounded read to transport the packet. Invoke only once with the literal
+`validate` operation and retain its original exit, stdout, and stderr.
+
+### Pi PowerShell validate invocation
+```powershell
+& $caPython -B $caHelper validate
+if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
+```
+
+### Pi POSIX validate invocation
+```sh
+"$ca_python" -B "$ca_helper" validate
+```

package/plugins/ca-pi/includes/pi-host-notes.md

@@ -22,6 +22,19 @@ file maps those actions to Pi's extension API.
   silently allows classified reads. Plan mode is read-only except for the
   current canonical spec, plan, and plan-ledger files; source, configuration,
   unrelated project-state, and external mutations deny.
+- For an authorized debug validator or task-board writer call, load
+  [helper-invocation.md](helper-invocation.md) relative to this installed host
+  note. Derive the installed package
+  from the absolute path of the currently loaded `ca-debug` or `ca-task`
+  `SKILL.md`, then check the exact helper and run the card's PowerShell or POSIX
+  Python 3 selection block before invoking it. Select once by an executed
+  identity probe; preserve a failed helper's original output and exit status
+  without a second-interpreter attempt. Put task options before `--` and pass
+  user text as one literal argument. Feed validation one finite packet of at
+  most 65,536 bytes through the host tool's stdin using the card's direct
+  `validate` call. The literal `<plugin-root>` spelling
+  is not a shell path. A missing helper blocks the call; preserve the current
+  project working directory for board writes.
 - `codearbiter_background_bash` and `/ca-jobs list|tail|cancel` are bounded,
   session-only parent capabilities. Jobs and their metadata terminate at
   shutdown and are never restored from Pi session entries.

package/plugins/ca-pi/includes/routing-table.md

@@ -27,7 +27,7 @@ reached the same way.
 | Docs edit / dep bump / revert | `/chore` (type-scaled gates) | `dependency-reviewer` for deps | No behavioral code; suite green for deps/revert; exits via `commit-gate` |
 | Exploratory throwaway spike | `/spike` (self-contained command) → `spike/<slug>` branch | — | Never merges or PRs; `commit-gate`-exempt (nothing on the branch can land); exits to a findings note or `/feature` |
 | Behavior-preserving restructure | `refactor` skill at `<plugin-root>/routines/refactor/SKILL.md` (explicit `/refactor` uses the same owner) | `tdd` Phase 1 (coverage backfill or new seams) | No refactor without parity-coverage proof |
-| Unknown defect / investigation | `debug` skill at `<plugin-root>/routines/debug/SKILL.md` (explicit `/debug` uses the same owner) | — | No code change in the skill; one named exit |
+| Unknown defect / investigation | `debug` skill at `<plugin-root>/routines/debug/SKILL.md` (explicit `/debug` uses the same owner) | — | No code change in the skill; one of confirmed_code_defect, confirmed_noncode_cause, design_question, no_action, or unresolved with evidence; continuation retains caller authority |
 | Commit | `commit-gate` skill at `<plugin-root>/routines/commit-gate/SKILL.md` (explicit `/commit` uses the same owner) | — | No commit without all nine gates green |
 | Open a PR / finish a branch | `finishing-a-development-branch` at `<plugin-root>/routines/finishing-a-development-branch/SKILL.md`; select direct-open or caller mode first | reviewer fleet per path; PR-body prose applies `anti-slop-design` (`core` + `medium-documents` §7.A.1) | PR only; no direct-to-default, no force-push |
 | Watch a PR's CI / babysit checks | `/watch` → detached `gh pr checks --watch` | on-red diagnose (propose\|branch) | Never auto-merges; green → notify + offer; merge-to-default routes through the hard gate; no poll loop |

package/plugins/ca-pi/includes/security-gate-record.md

@@ -14,9 +14,11 @@ code instead of the first's (#577) — then run:
 
 It writes `<project-root>/.codearbiter/.markers/security-gate-passed` containing a digest of
 every sensitive added line it approved. The PreToolUse commit hook (**H-09b** for crypto/TLS, **H-10b**
-for secrets) blocks any commit whose staged diff touches a guarded pattern until this marker is fresh
-(< 30 min) AND covers every sensitive line being committed — a pass recorded for one diff cannot
-launder a later, different change through the freshness window.
+for secrets) blocks any commit whose staged diff touches a guarded pattern until this marker exists
+AND covers every sensitive line being committed. There is no time window: a pass stays valid for
+exactly the lines it reviewed, in the files it reviewed them in. Any new or changed sensitive line,
+or a reviewed line moved to another file, is uncovered and blocks, so a pass recorded for one diff
+cannot launder a later, different change.
 
 On any BLOCK, do **not** record the pass — the commit stays blocked until the finding is resolved and
 the gate genuinely passes. A premature or unconditional recording defeats the gate.

package/plugins/ca-pi/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arbiterforge/ca-pi",
-  "version": "0.15.10",
+  "version": "0.16.0",
   "private": true,
   "license": "AGPL-3.0-only",
   "type": "module",

package/plugins/ca-pi/routines/INDEX.md

@@ -15,7 +15,7 @@ not both merely to repeat the same procedure. This index lists what each skill O
 | [tdd](tdd/SKILL.md) | `/feature` (after spec approval), `/fix`, `/refactor` | The test-first gate: six phases — obligation scan → red → green → obligation verify → coverage → lint. No implementation before Phase 1; no path to `commit-gate` until all six gates are green. |
 | [commit-gate](commit-gate/SKILL.md) | `/commit` | The commit gate: nine phases — permission, branch, classification, impact-bounded local verification under the shared [verification boundary](../includes/verification-boundary.md), behavioral proof, diff review, selective stage, message, commit. No commit while an applicable check is red, the behavior unproven, or secrets/cruft present; exhaustive exact-head proof remains a hosted-CI merge gate. |
 | [decision-variance](decision-variance/SKILL.md) | Architectural reconciliation or variance report; explicit `/reconcile` retained | One SMARTS arbitration owner; report-only is non-mutating. Analysis card loads on demand; only explicit user choices enter the append-only log. |
-| [debug](debug/SKILL.md) | Diagnosis intent or `/debug` | Investigate-then-decide root-cause analysis: five phases. Investigation only, no code change here; forces one named exit — `/fix`, `/adr`, or a no-action close. |
+| [debug](debug/SKILL.md) | Diagnosis intent or `/debug` | Investigate-then-decide root-cause analysis: five phases. Investigation only, no code change here; returns one evidence-backed result: confirmed_code_defect, confirmed_noncode_cause, design_question, no_action, or unresolved. Follow-up action retains caller authority; no default task or ADR write. |
 | [refactor](refactor/SKILL.md) | Behavior-preserving restructure intent or `/refactor` | Behavior-preserving change behind a parity-coverage proof gate; routes to `tdd` Phase 1 for coverage backfill or new test seams. |
 | [context-creation](context-creation/SKILL.md) | `/create-context` (brownfield) | Back-fills `.codearbiter/` from existing source via parallel scouts; writes `CONTEXT.md` (`arbiter: enabled` + `stage:`) and locks it `<!--INITIALIZED-->`. |
 | [decompose](decompose/SKILL.md) | greenfield startup, `/decompose` | Six-layer senior-architect interview, compaction-resilient via per-layer disk drafts + DRAFT ADRs; populates `.codearbiter/` and locks it initialized. |