@ccoalm/ccl-skills 0.15.5 → 0.16.0

package/dist/assets/marketplace/plugins/ccl-skills/skills/code-review/SKILL.md

@@ -134,17 +134,16 @@ echo "code_review_skill_dir=$CODE_REVIEW_SKILL_DIR" >&2
 : "${REVIEW_CHAIN_ID:?set REVIEW_CHAIN_ID to a task-scoped chain id: letters, digits, dot, underscore, hyphen only}"
 : "${REVIEW_STAGE:?set REVIEW_STAGE to the stage this candidate is actually at: explore, build, or release}"
 : "${REVIEW_EVIDENCE_DIR:?set REVIEW_EVIDENCE_DIR to a durable directory you control for the per-round result rows}"
-# Exactly one frozen packet source: a packet you composed (REVIEW_DIFF_FILE, see the
-# packet-composition rules below) or a base ref (REVIEW_BASE). The gate rejects both.
-if [ -n "${REVIEW_DIFF_FILE:-}" ] && [ -n "${REVIEW_BASE:-}" ]; then
-  echo "set exactly one of REVIEW_DIFF_FILE or REVIEW_BASE" >&2; exit 1
-elif [ -n "${REVIEW_DIFF_FILE:-}" ]; then
-  PACKET_ARGS=(--diff-file "$REVIEW_DIFF_FILE")
-elif [ -n "${REVIEW_BASE:-}" ]; then
-  PACKET_ARGS=(--base "$REVIEW_BASE")
-else
-  echo "set exactly one of REVIEW_DIFF_FILE or REVIEW_BASE" >&2; exit 1
+# REVIEW_BASE names the candidate, REVIEW_DIFF_FILE widens what the reviewer reads,
+# and BOTH is a widened packet that must BEGIN with the candidate (composition
+# rules: references/staged-review-contract.md). if-blocks, not `[ -n ... ] && ...`: a
+# trailing false test returns non-zero and `set -e` would kill the caller.
+if [ -z "${REVIEW_DIFF_FILE:-}" ] && [ -z "${REVIEW_BASE:-}" ]; then
+  echo "set REVIEW_BASE, REVIEW_DIFF_FILE, or both" >&2; exit 1
 fi
+PACKET_ARGS=()
+if [ -n "${REVIEW_BASE:-}" ]; then PACKET_ARGS+=(--base "$REVIEW_BASE"); fi
+if [ -n "${REVIEW_DIFF_FILE:-}" ]; then PACKET_ARGS+=(--diff-file "$REVIEW_DIFF_FILE"); fi
 # REVIEW_RUN_DIR holds the raw round-1 result only for the chain handoff; the durable
 # per-round evidence is persisted to REVIEW_EVIDENCE_DIR, whose confidentiality you own.
 REVIEW_RUN_DIR="$(mktemp -d "${TMPDIR:-/tmp}/review-run.XXXXXX")" || exit 1
@@ -199,10 +198,11 @@ bash "$CODE_REVIEW_SKILL_DIR/scripts/review_gate.sh" \
   >"$REVIEW_RUN_DIR/round2.json"
 require_tracked_result "$REVIEW_RUN_DIR/round2.json" challenge 2
 # Both rounds must bind the SAME candidate: the chain accepts older candidate hashes,
-# so a packet edited between rounds would otherwise be persisted as one coherent pair.
+# so a candidate edited between rounds would otherwise be persisted as one coherent
+# pair. Their packets may differ; each receipt records the packet it actually read.
 python3 -c 'import json,sys; a=json.load(open(sys.argv[1])); b=json.load(open(sys.argv[2])); h=a.get("candidate_sha256"); sys.exit(0 if h and h==b.get("candidate_sha256") else 1)' \
   "$ROUND1_RESULT_FILE" "$REVIEW_RUN_DIR/round2.json" \
-  || { echo "round 2 reviewed a different packet than round 1; rerun the pair on one frozen candidate" >&2; exit 1; }
+  || { echo "round 2 bound a different candidate than round 1; rerun the pair on one frozen candidate" >&2; exit 1; }
 cp "$REVIEW_RUN_DIR/round2.json" "$EVIDENCE_RUN_DIR/round2-challenge.json" || exit 1
 cat "$EVIDENCE_RUN_DIR/round2-challenge.json"
 # A secret-free diff egresses to non-Claude reviewers automatically; add
@@ -216,10 +216,10 @@ Run the script by path while keeping `--cwd` pointed at the product repository u
 **The packet is the reviewer's whole world — compose it deliberately.** Review and challenge are built packet-bounded — Claude runs `--tools ""` with no `--add-dir`, and the other wrappers run in an isolated run workspace or a packet-only read surface. Treat the packet as the reviewer's whole world when deciding coverage: it is the only content bound by the packet hash and scanned before egress, so anything outside it is neither reliably visible to the reviewer nor covered by the verdict; a diff-only packet surfaces defects visible inside the changed lines and little else, and `--paths` only narrows it further. Whatever is absent from the packet is unreachable, not merely missed: a contradiction with an unchanged sibling clause, drift against a carrier outside the diff, or a silent weakening of upstream wording cannot be found by a reviewer who never saw the other side — that is the packet's shape, not the reviewer's weakness.
 
 - Codex permits frozen-packet read/search; see [tool boundaries](references/development-completion.md#review-tools).
-- To widen the packet, assemble it yourself and pass `--diff-file`: it replaces base-derived generation, is mutually exclusive with `--base`/`--paths`, and must name a regular file (no symlink or hardlink) holding text without NUL bytes. Worth adding beyond the diff — the canonical rule or contract text the changed lines must not contradict, the sibling clauses in the same file, the derived carriers that restate the change (commit message, MR/PR body), and the actual output of a gate or script under review. The gate hard-caps a packet at 200,000 bytes; split a larger candidate as described in the next bullet.
-- A verdict covers exactly the packet it was taken on, because the recorded packet hash is the reviewed identity. Within a packet, added context sits on top of the candidate diff and never in place of part of it. A candidate too large for one packet is split by file group or risk class into a partition that still covers the whole candidate — every part in some packet, none dropped — each partition's verdict recorded against its own packet hash, and the candidate-wide claim withheld until every partition is conclusive; one partition's `no blocking findings` is never a verdict on the landing candidate. Cross-partition contradictions are unreachable by construction, so repeat the shared canonical context in every partition's packet and review anything that spans partitions as its own packet.
+- To widen the packet, assemble it yourself and pass `--diff-file`, plus `--base` whenever the round must bind a landing candidate ([composition rules](references/staged-review-contract.md#the-packet-and-the-candidate)). It must name a regular file (no symlink or hardlink) holding text without NUL bytes. The gate hard-caps a packet at 200,000 bytes; split a larger candidate as described in the next bullet.
+- A verdict covers exactly the packet it was taken on; the receipt records `packet_sha256` for those bytes and `candidate_sha256` for the base-derived candidate that will land, equal unless the packet was widened. A candidate too large for one packet is split by file group or risk class into a partition that still covers the whole candidate — every part in some packet, none dropped — each partition's verdict recorded against its own packet hash, and the candidate-wide claim withheld until every partition is conclusive; one partition's `no blocking findings` is never a verdict on the landing candidate. Cross-partition contradictions are unreachable by construction, so repeat the shared canonical context in every partition's packet and review anything that spans partitions as its own packet.
 - Added context egresses to the selected reviewer exactly like the diff does, through the same credential tripwire — which catches machine-detectable secrets only. Paste rule text, carriers, and tool output; never paste credentials or material you would not send to that provider.
-- A finding that the input is insufficient to judge the change is an input defect, not a candidate defect: widen the packet and rerun that lane rather than editing the candidate to satisfy it.
+- A finding that the input is insufficient to judge the change is an input defect, not a candidate defect: widen the packet and rerun that lane, keeping `--base` so it still binds the same candidate, rather than editing the candidate to satisfy it.
 
 When intentionally reviewing `code-review` itself, override the resolver from the ccl-skills repo under review before invoking the gate:
 

package/dist/assets/marketplace/plugins/ccl-skills/skills/code-review/references/staged-review-contract.md

@@ -184,6 +184,46 @@ commit an in-scope path when Git should represent it; or compose complete
 `--diff-file` partitions when the candidate must be split. Never omit a path
 and report the remaining packet as the whole candidate.
 
+## The packet and the candidate
+
+They are two objects. The **packet** is what the reviewer reads; the **candidate**
+is what will land and what `review_ledger_binding.py` recomputes at merge time.
+A receipt records both hashes.
+
+They hold the same value when the packet came from `--base` alone. Pass
+`--diff-file` **with** `--base`/`--paths` to widen what the reviewer reads while
+the round still binds the landing candidate — the shape an evidence-gap finding
+needs, since editing the candidate would answer an input defect with a candidate
+change. `--diff-file` alone binds no landing; only the combined form rejects a
+`--wording-only-proof-file`.
+
+What makes the widened form safe is a **prefix requirement**: the packet begins
+with the base-derived candidate, byte for byte, so nothing lands unread.
+
+- **Append context after the candidate diff.** Putting anything before the
+  candidate fails, and that is not cosmetic: a packet preceding it with a decoy
+  diff would read as the change while the real candidate read as context.
+  Interleaving context inside the candidate fails, as does dropping any part of
+  it. The reviewer is told where the candidate ends — the profile carries
+  `candidate_bytes` and states that exactly the first N packet bytes land — so
+  appended hunks that continue or seem to revert the diff cannot pass as it.
+- **Keep the packet file outside the repository, and put nothing else in the
+  tree while the rounds run.** The controller counts every untracked path into
+  the candidate; the binder counts only committed content minus the receipt JSON
+  a round adds. A packet file, a superseded round's receipt, or any scratch
+  artifact in the worktree therefore moves the candidate the rounds bind and the
+  binder never computes it — the mirror of committing a plain-text attestation
+  after the rounds. Bound evidence lands before the rounds, receipts after,
+  nothing else present.
+- **Read the candidate identity, do not reconstruct it.** `--print-candidate`
+  is the authority: its base is a fork point, its paths carry the round's
+  exclusions, and it refuses an uncommitted tree.
+- Worth adding beyond the diff — the canonical rule the changed lines must not
+  contradict, sibling clauses, the carriers restating the change, gate output.
+
+Rounds in one chain agree on the **candidate**, not the packet, which lets a
+later round read more than an earlier one.
+
 ## Proof-bound wording-only single review
 
 The wording-only exception is one untracked `review` with

package/dist/assets/marketplace/plugins/ccl-skills/skills/code-review/scripts/codex_review.sh

@@ -16,7 +16,7 @@ MAX_PROMPT_BYTES=245000
 CHALLENGE_CLASSES="race conditions, data loss, security holes, auth bypass, lost or duplicated work, operational footguns"
 
 emit_inconclusive() {
-  python3 - "$MODE" "$1" "${2:-invalid_input}" "${3:-false}" "${4:-}" <<'PY'
+  python3 - "$MODE" "$1" "${2:-invalid_input}" "${3:-false}" "${4:-}" "${5:-}" "${6:-}" <<'PY'
 import json, sys
 payload = {
     "reviewer": "codex",
@@ -31,6 +31,10 @@ payload = {
 }
 if sys.argv[5]:
     payload["transport_exit_code"] = int(sys.argv[5]) if sys.argv[5].isdigit() else sys.argv[5]
+if sys.argv[6]:
+    payload["transport_diagnostic"] = sys.argv[6]
+if sys.argv[7]:
+    payload["transport_run_dir"] = sys.argv[7]
 print(json.dumps(payload, ensure_ascii=False, separators=(",", ":")))
 PY
 }
@@ -179,7 +183,15 @@ if [ "$REVIEW_SKILL_COUNT" -gt 0 ]; then
     || die_inconclusive codex_installed_skill_binding_invalid binding_mismatch false
 fi
 RUN_ROOT="$(mktemp -d "${TMPDIR:-/tmp}/codex-review.XXXXXX")"
-cleanup() { rm -rf "$RUN_ROOT"; }
+# A failure that deletes its own evidence is the defect this round started from:
+# rounds 122 and 123 left six receipts and no account of why the lane failed,
+# because both captured streams went out with the run directory. On a transport
+# failure the directory stays, and the receipt names it. It is mode 0700 under
+# TMPDIR and holds exactly what it held while the run was in flight, so nothing
+# is exposed that was not already; reclaiming it is the platform's temp-directory
+# lifetime, as it is for every other run directory here.
+PRESERVE_RUN_ROOT=0
+cleanup() { [ "$PRESERVE_RUN_ROOT" = 1 ] || rm -rf "$RUN_ROOT"; }
 trap cleanup EXIT
 signal_inconclusive() {
   emit_inconclusive codex_review_terminated operator_interrupt false
@@ -515,26 +527,102 @@ if [ -n "$AUTH_LINK_TARGET" ]; then
     || die_inconclusive codex_runtime_home_credential_moved binding_mismatch false
 fi
 if [ "$run_rc" != 0 ]; then
+  # `codex exec --json` reports supply and credential failures as structured
+  # events on stdout, not on stderr, so a classifier reading only stderr sees a
+  # quota exhaustion as an unclassifiable failure and stops the reviewer lane
+  # instead of cascading.
+  #
+  # Only TOP-LEVEL error events are read. Model-authored content arrives nested
+  # under `item`, and the model quotes the packet, which is untrusted candidate
+  # data -- grepping the raw stream would let a reviewed diff pick the verdict
+  # for this lane by writing quota vocabulary into itself.
+  TRANSPORT_ERRORS="$RUN_ROOT/transport-errors.txt"
+  : >"$TRANSPORT_ERRORS"
+  python3 - "$EVENTS" >"$TRANSPORT_ERRORS" 2>/dev/null <<'PY_TRANSPORT_ERRORS'
+import json, sys
+from pathlib import Path
+
+try:
+    lines = Path(sys.argv[1]).read_text(encoding="utf-8", errors="replace").splitlines()
+except OSError:
+    sys.exit(0)
+seen = set()
+for line in lines:
+    try:
+        event = json.loads(line)
+    except ValueError:
+        continue
+    if not isinstance(event, dict):
+        continue
+    kind = event.get("type")
+    if not isinstance(kind, str) or not (kind == "error" or kind.endswith(".failed")):
+        continue
+    message = event.get("message")
+    if not isinstance(message, str):
+        nested = event.get("error")
+        message = nested.get("message") if isinstance(nested, dict) else None
+    if not isinstance(message, str) or not message:
+        continue
+    # A failing turn repeats the error event verbatim, and the diagnostic is
+    # bounded: relaying both would spend half the budget on one sentence.
+    message = " ".join(message.split())
+    if message not in seen:
+        seen.add(message)
+        print(message)
+PY_TRANSPORT_ERRORS
+  PRESERVE_RUN_ROOT=1
+  # Physical paths on both sides, not the literal `$HOME` string: a home spelled
+  # with a trailing slash, or reached through a symlink, is the same directory
+  # and must elide the same way. Comparing the raw variable would put the
+  # username into a committed receipt on exactly those hosts.
+  TRANSPORT_RUN_DIR="$(cd "$RUN_ROOT" 2>/dev/null && pwd -P)" || TRANSPORT_RUN_DIR="$RUN_ROOT"
+  [ -n "$TRANSPORT_RUN_DIR" ] || TRANSPORT_RUN_DIR="$RUN_ROOT"
+  transport_home_real=""
+  if [ -n "${HOME:-}" ]; then
+    transport_home_real="$(cd "$HOME" 2>/dev/null && pwd -P)" || transport_home_real=""
+  fi
+  case "$transport_home_real" in
+    "" | */) transport_home_real="" ;;
+  esac
+  if [ -n "$transport_home_real" ]; then
+    case "$TRANSPORT_RUN_DIR" in
+      "$transport_home_real"/*)
+        TRANSPORT_RUN_DIR="~${TRANSPORT_RUN_DIR#"$transport_home_real"}" ;;
+    esac
+  fi
+  # The receipt carries NO text derived from the run. Eight review chains each
+  # found a different escape from a filter over that text -- an unlisted key
+  # name, an assignment form, URL userinfo, a password containing the separator,
+  # an escaped quote, an uppercase scheme -- because "nothing secret-shaped
+  # survives" is not a decidable property of free text, and an adversarial
+  # reviewer can always spell one more. So the free text is gone: what the
+  # transport said stays in the preserved run directory, and the receipt says
+  # where that is. The classifier still reads the extracted error messages
+  # above; those are matched against fixed patterns and never persisted.
+  TRANSPORT_DIAGNOSTIC="the transport output for this failure is in transport_run_dir"
+
   if bash "$TIMEOUT_CLASSIFIER" "$run_rc" "$run_elapsed" "$TIMEOUT"; then
-    die_inconclusive codex_timeout timeout true "$run_rc"
+    die_inconclusive codex_timeout timeout true "$run_rc" "$TRANSPORT_DIAGNOSTIC" "$TRANSPORT_RUN_DIR"
   fi
   case "$run_rc" in
-    129|130|137|143) die_inconclusive codex_process_interrupted operator_interrupt false "$run_rc" ;;
+    129|130|137|143) die_inconclusive codex_process_interrupted operator_interrupt false "$run_rc" "$TRANSPORT_DIAGNOSTIC" "$TRANSPORT_RUN_DIR" ;;
   esac
-  if grep -qiE '429|rate.?limit|quota' "$STDERR_FILE"; then
-    die_inconclusive codex_quota quota true "$run_rc"
+  # `usage limit` is the wording the CLI actually uses for an exhausted account;
+  # none of the older patterns match it.
+  if grep -qiE '429|rate.?limit|quota|usage limit' "$STDERR_FILE" "$TRANSPORT_ERRORS"; then
+    die_inconclusive codex_quota quota true "$run_rc" "$TRANSPORT_DIAGNOSTIC" "$TRANSPORT_RUN_DIR"
   fi
-  if grep -qiE 'unauthori[sz]ed|authentication|login|api key' "$STDERR_FILE"; then
-    die_inconclusive codex_auth_unavailable provider_unavailable true "$run_rc"
+  if grep -qiE 'unauthori[sz]ed|authentication|login|api key' "$STDERR_FILE" "$TRANSPORT_ERRORS"; then
+    die_inconclusive codex_auth_unavailable provider_unavailable true "$run_rc" "$TRANSPORT_DIAGNOSTIC" "$TRANSPORT_RUN_DIR"
   fi
   if [ ! -s "$EVENTS" ] && [ ! -s "$RESULT_FILE" ] \
     && grep -qiE 'failed to initialize in-process app-server client: Operation not permitted' "$STDERR_FILE"; then
     if [ "$HOST_REMEDIATION_ATTEMPTED" -eq 1 ]; then
-      die_inconclusive codex_host_path_unavailable_after_host_retry host_path_unavailable_after_host_retry true "$run_rc"
+      die_inconclusive codex_host_path_unavailable_after_host_retry host_path_unavailable_after_host_retry true "$run_rc" "$TRANSPORT_DIAGNOSTIC" "$TRANSPORT_RUN_DIR"
     fi
-    die_inconclusive codex_host_path_unavailable host_path_unavailable false "$run_rc"
+    die_inconclusive codex_host_path_unavailable host_path_unavailable false "$run_rc" "$TRANSPORT_DIAGNOSTIC" "$TRANSPORT_RUN_DIR"
   fi
-  die_inconclusive codex_run_failed unknown_client_failure false "$run_rc"
+  die_inconclusive codex_run_failed unknown_client_failure false "$run_rc" "$TRANSPORT_DIAGNOSTIC" "$TRANSPORT_RUN_DIR"
 fi
 
 python3 "$PARSER" --client codex --mode "$MODE" --implementer-family "$IMPL_FAMILY" \