@ccoalm/ccl-skills 0.1.0 → 0.2.0

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

@@ -0,0 +1,394 @@
+#!/usr/bin/env bash
+# Proves an aborted test_review_gate.sh leaves no reviewer wrapper behind, by both of
+# the mechanisms that keep that true.
+#
+# The suite's reviewer wrappers are deliberately TERM-immune and the controller starts
+# them with start_new_session=True, so they sit in their own session where no signal
+# aimed at the suite's process group can reach them. That makes the controller the only
+# party that reaps them on the happy path. Both legs below remove the controller FIRST —
+# the way a tree-kill, a CI cancellation, or a host suspend does — and then abort the
+# suite two different ways:
+#
+#   leg 1  SIGTERM the suite: its cleanup trap runs and must reap the abandoned wrapper.
+#   leg 2  SIGKILL the suite: nothing can trap that, so no reaper runs at all and the
+#          wrapper must die on the fixture's own lifetime bound instead.
+#
+# Leg 2 exists because leg 1 alone stays green if the fixture's bound were restored to
+# an unbounded loop: the trap would still reap it. It was an unbounded loop that turned
+# this defect into a wrapper observed alive for 39 hours with ppid=1, ignoring SIGTERM.
+#
+# Each leg runs the suite under a private TMPDIR so every process this probe may signal
+# is identified by a path no other run can share. Nothing here matches on the shared
+# `review-gate-test.` prefix: a concurrent lane running the same suite would be killed
+# by that, which is precisely the class scripts/test_lane_isolation.py keeps out of the
+# parallel lanes.
+set -uo pipefail
+
+DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd -P)"
+SUITE="$DIR/test_review_gate.sh"
+# How long an abandoned wrapper may still be alive after the suite is gone.
+GRACE="${ABORT_LEAK_PROBE_GRACE:-30}"
+# Bound on reaching the target case. The suite reaches it in ~2min on an idle host; the
+# headroom is for a slow runner, NOT for sharing one — this probe runs in its own job
+# precisely because a shared runner stretches that round past any budget.
+REACH="${ABORT_LEAK_PROBE_REACH:-420}"
+# Leg 2 shortens the fixture's own bound so the leg does not have to wait out the 300s
+# default; leg 2's runtime is essentially this number, because the leg ends by watching
+# the abandoned wrapper reach it. The constraint is the budget each case gives ITS
+# WRAPPER — the `--timeout` the controller passes down, which is 5s for the claude hang
+# case this probe aborts in and under 12s for the fallback hang cases that run before it
+# (per those cases' own assertions) — NOT the case's `--total-timeout`, which bounds the
+# whole gate rather than the wrapper. 25 keeps ~2x margin over the largest of those while
+# taking 20s off the job: measured on CI, this job was the longest branch at 213s against
+# 188s for the previous longest, so that 20s is the difference between adding a critical
+# path and landing inside the existing one.
+LEG2_HANG_BOUND="${ABORT_LEAK_PROBE_HANG_BOUND:-25}"
+# Which leg(s) to run: `1`, `2`, or `all`. Each leg needs its OWN full run of the suite —
+# one abort must be trappable and the other must not — and that pair, not the leg-2 wait,
+# is what makes this the longest CI branch. Measured: cutting the leg-2 bound 45s -> 25s
+# moved the job 213s -> 214s, i.e. not at all. So CI runs the legs as two parallel jobs
+# and each stays well under the next-longest branch; `all` remains the local default.
+ABORT_LEAK_PROBE_LEG="${ABORT_LEAK_PROBE_LEG:-all}"
+case "$ABORT_LEAK_PROBE_LEG" in
+  1|2|all) : ;;
+  *) echo "ABORT_LEAK_PROBE_LEG must be 1, 2, or all" >&2; exit 2 ;;
+esac
+# Which fixture stub to orphan. The suite generates TWO of them — the claude stub and the
+# shared candidate stub the fallback clients run — and they carry the same hang behavior
+# and the same lifetime bound. A probe pinned to one leaves the other's bound revertible
+# with the probe still green, so CI points its two jobs at different stubs.
+ABORT_LEAK_PROBE_CLIENT="${ABORT_LEAK_PROBE_CLIENT:-claude}"
+case "$ABORT_LEAK_PROBE_CLIENT" in
+  claude) PROBE_BEHAVIOR_FILE=claude_behavior; PROBE_WRAPPER=claude_review.sh ;;
+  fallback) PROBE_BEHAVIOR_FILE=kimi_behavior; PROBE_WRAPPER=kimi_review.sh ;;
+  *) echo "ABORT_LEAK_PROBE_CLIENT must be claude or fallback" >&2; exit 2 ;;
+esac
+
+fails=0
+check() {
+  if eval "$2"; then echo "ok   - $1"; else echo "FAIL - $1"; fails=$((fails+1)); fi
+}
+
+PROBE_TMP=""
+PROBE_TMP_REAL=""
+suite_pid=""
+suite_pgid=""
+suite_start=""
+wrapper_pid=""
+wrapper_pgid=""
+
+# Every process a leg starts carries that leg's private tmp path in argv. The needles go
+# through the environment, not `awk -v`: `ps -e` lists this very awk, and an argv-passed
+# needle makes the scanner match itself.
+probe_processes() {
+  [ -n "$PROBE_TMP_REAL" ] || return 0
+  ps -eo pid=,stat=,command= 2>/dev/null |
+    PROBE_A="$PROBE_TMP/" PROBE_B="$PROBE_TMP_REAL/" \
+    awk 'BEGIN { a = ENVIRON["PROBE_A"]; b = ENVIRON["PROBE_B"] }
+         (index($0, a) || index($0, b)) && $2 !~ /Z/ { print $1 }'
+}
+
+# Never let the probe become the leak it tests for — and never on someone else's
+# processes: `suite_pgid` and any pid read earlier are cached numbers the OS recycles,
+# so ownership is re-proved against the live process table at the moment of signalling.
+# A group is signalled only while it still contains a process carrying this probe's
+# private tmp path; everything else is signalled by pid, which `probe_processes` has
+# just re-matched by that same path.
+probe_group_is_ours() {
+  ps -eo pgid=,stat=,command= 2>/dev/null |
+    PROBE_A="$PROBE_TMP/" PROBE_B="$PROBE_TMP_REAL/" PROBE_PGID="$1" \
+    awk 'BEGIN { a = ENVIRON["PROBE_A"]; b = ENVIRON["PROBE_B"]; g = ENVIRON["PROBE_PGID"]; found = 1 }
+         $1 == g && $2 !~ /Z/ && (index($0, a) || index($0, b)) { found = 0; exit }
+         END { exit found }'
+}
+# The suite's pid and group id were captured minutes earlier and the OS recycles both,
+# so every signal aimed at them re-proves identity first: the pid must still be running
+# THIS suite script and must still lead the group we recorded. Validating the group
+# through a live member we can name is what makes the group signal safe — a
+# tmp-path-membership test would not do here, because by design the controller (the one
+# group member carrying that path) has just been killed.
+suite_is_ours() {
+  case "${suite_pid:-}" in ''|*[!0-9]*) return 1 ;; esac
+  case "${suite_pgid:-}" in ''|*[!0-9]*) return 1 ;; esac
+  kill -0 "$suite_pid" 2>/dev/null || return 1
+  case "$(ps -o command= -p "$suite_pid" 2>/dev/null || true)" in
+    *"$SUITE"*) : ;;
+    *) return 1 ;;
+  esac
+  [ "$(ps -o pgid= -p "$suite_pid" 2>/dev/null | tr -d ' ')" = "$suite_pgid" ] || return 1
+  # Start time, not just argv and group: with job control the suite's pgid equals its
+  # own pid, so those two conditions collapse into "this pid is running this script" —
+  # which a recycled pid on another run of the SAME suite would also satisfy. The launch
+  # instant is what separates our process from its namesake.
+  [ -n "$suite_start" ] || return 1
+  [ "$(ps -o lstart= -p "$suite_pid" 2>/dev/null || true)" = "$suite_start" ] || return 1
+  return 0
+}
+signal_suite() {
+  suite_is_ours || return 0
+  kill -"$1" -"$suite_pgid" 2>/dev/null || true
+  kill -"$1" "$suite_pid" 2>/dev/null || true
+}
+cleanup() {
+  local pid probe_cmd
+  signal_suite KILL
+  for pid in $(probe_processes); do
+    # Re-check immediately before signalling: a pid read even a moment ago can already be
+    # a stranger's. This narrows the window to the width of one `ps`; a shell cannot close
+    # it entirely, because there is no portable kill-by-handle, and that residual TOCTOU
+    # is a documented boundary rather than an oversight.
+    # Match BOTH spellings, like probe_processes does: on a host where the temp dir is a
+    # symlink (macOS /var -> /private/var) a process can carry either form, and a check
+    # that knows only one silently skips a process this probe started.
+    probe_cmd="$(ps -o command= -p "$pid" 2>/dev/null || true)"
+    case "$probe_cmd" in
+      *"$PROBE_TMP/"*|*"$PROBE_TMP_REAL/"*) : ;;
+      *) continue ;;
+    esac
+    probe_group_is_ours "$pid" && kill -KILL -"$pid" 2>/dev/null || true
+    kill -KILL "$pid" 2>/dev/null || true
+  done
+  [ -z "$PROBE_TMP" ] || rm -rf "$PROBE_TMP"
+}
+trap cleanup EXIT
+trap 'exit 130' INT
+trap 'exit 143' TERM HUP
+
+# Selecting the target reads the suite's OWN state rather than pattern-matching an argv
+# tail. Two earlier selectors failed here and each failure is the reason for this shape:
+# picking by lifetime chose one of the behaviors that merely sleeps and then exits on its
+# own (`quota_slow` 2s, `passed_slow` 5s), so the probe was green against a broken suite;
+# and matching `--focus process-group-timeout` in the command line depends on how ps
+# renders a long argv — it found the case when the probe ran alone and found nothing at
+# all under `make`, burning the whole reach budget twice. The behavior file is written by
+# the suite before it starts the case, so "a hang case is running now" is a fact to read,
+# not a shape to guess. It also matches the FIRST hang case rather than the last, so the
+# probe reaches its target sooner.
+#
+# The wrapper and the `( ... ) &` child it backgrounds share a command line, so "the
+# first matching ps row" is whichever the kernel lists first. Picking the child would
+# make the next step read the WRAPPER as the controller — and the wrapper's own command
+# line satisfies the tmp-path validation, so that mistake would sail through and the leg
+# would kill the wrong process. Select by ancestry: the wrapper is the match whose parent
+# is the controller.
+suite_work_dir() {
+  local dir
+  for dir in "$PROBE_TMP_REAL"/review-gate-test.*; do
+    [ -d "$dir" ] && printf '%s\n' "$dir" && return 0
+  done
+  return 1
+}
+live_wrapper() {
+  local work behavior pid parent_cmd
+  work="$(suite_work_dir)" || return 0
+  behavior="$(cat "$work/state/$PROBE_BEHAVIOR_FILE" 2>/dev/null || true)"
+  [ "$behavior" = "hang" ] || return 0
+  for pid in $(ps -eo pid=,command= 2>/dev/null |
+      grep -e "$PROBE_TMP/" -e "$PROBE_TMP_REAL/" -F |
+      grep -F "$PROBE_WRAPPER" |
+      grep -v '[g]rep' |
+      awk '{print $1}'); do
+    parent_cmd="$(ps -o command= -p "$(ps -o ppid= -p "$pid" 2>/dev/null | tr -d ' ')" 2>/dev/null || true)"
+    case "$parent_cmd" in
+      *review_gate.py*) printf '%s\n' "$pid"; return 0 ;;
+    esac
+  done
+  return 0
+}
+
+# Runs the suite until the target wrapper is in flight, then removes its controller so
+# the wrapper is orphaned with no reaper but the suite itself. Sets wrapper_pid.
+# $1 is the value for the fixture's lifetime bound, or empty for its default.
+orphan_target_wrapper() {
+  local hang_bound="$1" candidate controller_pid controller_ok deadline suite_died
+  PROBE_TMP="$(mktemp -d "${TMPDIR:-/tmp}/review-gate-abort-probe.XXXXXX")" || return 1
+  PROBE_TMP_REAL="$(cd "$PROBE_TMP" && pwd -P)" || return 1
+  wrapper_pid=""
+
+  # Job control so the suite gets its own process group and the probe can signal that
+  # group without signalling itself.
+  set -m
+  TMPDIR="$PROBE_TMP" REVIEW_GATE_TEST_HANG_SECONDS="$hang_bound" \
+    bash "$SUITE" >/dev/null 2>&1 &
+  suite_pid=$!
+  suite_pgid="$(ps -o pgid= -p "$suite_pid" 2>/dev/null | tr -d ' ')"
+  suite_start="$(ps -o lstart= -p "$suite_pid" 2>/dev/null || true)"
+
+  deadline=$(( $(date +%s) + REACH ))
+  suite_died=0
+  while [ "$(date +%s)" -lt "$deadline" ]; do
+    candidate="$(live_wrapper)"
+    if [ -n "$candidate" ]; then wrapper_pid="$candidate"; break; fi
+    kill -0 "$suite_pid" 2>/dev/null || { suite_died=1; break; }
+    sleep 0.1
+  done
+  if [ -z "$wrapper_pid" ]; then
+    # Say WHICH failure this is. "unreached" alone cannot distinguish a suite that ran
+    # fine but never got to a hang case inside the budget from a suite that died early —
+    # and a run of this probe under `make` failed exactly here with no way to tell them
+    # apart, which is why the distinction is printed rather than inferred.
+    if [ "$suite_died" = 1 ]; then
+      wait "$suite_pid" 2>/dev/null
+      printf 'abort_leak_probe_unreached: the suite exited (status %s) before any hang case was observed\n' "$?" >&2
+    else
+      printf 'abort_leak_probe_unreached: %ss budget elapsed with the suite still running; last behavior=%s\n' \
+        "$REACH" "$(cat "$(suite_work_dir 2>/dev/null)/state/claude_behavior" 2>/dev/null || printf unknown)" >&2
+    fi
+    return 1
+  fi
+
+  # Validate the target before signalling it, never after. Between selecting the wrapper
+  # and reading its parent the wrapper can be reaped and its pid reused, so this value is
+  # untrustworthy by construction: it can be 1 (already orphaned) or an unrelated
+  # process. `kill -KILL 1` is harmless for an unprivileged user but not for a root
+  # container, and no probe should be the thing that finds that out.
+  controller_pid="$(ps -o ppid= -p "$wrapper_pid" 2>/dev/null | tr -d ' ')"
+  controller_ok=0
+  case "$controller_pid" in
+    ''|*[!0-9]*) : ;;
+    *)
+      if [ "$controller_pid" -gt 1 ] \
+        && [ "$(ps -o ppid= -p "$wrapper_pid" 2>/dev/null | tr -d ' ')" = "$controller_pid" ] \
+        && { case "$(ps -o command= -p "$controller_pid" 2>/dev/null || true)" in
+               *"$PROBE_TMP/"*|*"$PROBE_TMP_REAL/"*) true ;; *) false ;; esac; }; then
+        controller_ok=1
+      fi
+      ;;
+  esac
+  if [ "$controller_ok" != 1 ]; then
+    printf 'abort leak setup: refusing to signal pid=%s (not this run'"'"'s controller)\n' \
+      "${controller_pid:-none}" >&2
+    return 1
+  fi
+  # Order matters: the controller must die BEFORE the suite, or its own timeout path
+  # reaps the wrapper and the leg proves nothing about the suite. `kill` returning is
+  # not that proof: confirm here, once, that the controller is really gone and the
+  # wrapper really was reparented, so BOTH legs inherit a verified precondition instead
+  # of each re-deriving it (leg 2 had no such check, and its later kill of the suite
+  # group could have removed the controller itself — making every remaining assertion
+  # pass without the required ordering ever holding).
+  wrapper_pgid="$(ps -o pgid= -p "$wrapper_pid" 2>/dev/null | tr -d ' ')"
+  kill -KILL "$controller_pid" 2>/dev/null || true
+  deadline=$(( $(date +%s) + 10 ))
+  while :; do
+    if ! kill -0 "$controller_pid" 2>/dev/null ||
+       [ -n "$(ps -o stat= -p "$controller_pid" 2>/dev/null | grep Z || true)" ]; then
+      break
+    fi
+    if [ "$(date +%s)" -ge "$deadline" ]; then
+      echo "abort leak setup: controller $controller_pid survived SIGKILL" >&2
+      return 1
+    fi
+    sleep 0.5
+  done
+  while :; do
+    [ "$(ps -o ppid= -p "$wrapper_pid" 2>/dev/null | tr -d ' ')" = "1" ] && return 0
+    kill -0 "$wrapper_pid" 2>/dev/null || {
+      echo "abort leak setup: wrapper $wrapper_pid died with its controller" >&2
+      return 1
+    }
+    if [ "$(date +%s)" -ge "$deadline" ]; then
+      echo "abort leak setup: wrapper $wrapper_pid was never reparented" >&2
+      return 1
+    fi
+    sleep 0.5
+  done
+}
+
+await_suite_exit() {
+  local deadline
+  deadline=$(( $(date +%s) + GRACE ))
+  while kill -0 "$suite_pid" 2>/dev/null; do
+    [ "$(date +%s)" -ge "$deadline" ] && break
+    sleep 0.5
+  done
+  kill -0 "$suite_pid" 2>/dev/null && return 1
+  return 0
+}
+
+# The verdict is about the GROUP, not the leader. The wrapper backgrounds a TERM-immune
+# child in that same group; a cleanup that kills the session leader but misses the child
+# leaves the leak in place while "the wrapper is gone" reads true — and the probe's own
+# cleanup would then erase the very evidence the leg exists to surface. Residue under the
+# leg's private tmp path is checked too, so a survivor that left the group still counts.
+wrapper_group_members_alive() {
+  [ -n "$wrapper_pgid" ] || return 0
+  ps -eo pid=,pgid=,stat= 2>/dev/null |
+    awk -v want="$wrapper_pgid" '$2 == want && $3 !~ /Z/ { print $1 }'
+}
+wrapper_gone_within() {
+  local deadline members residue
+  deadline=$(( $(date +%s) + $1 ))
+  while :; do
+    members="$(wrapper_group_members_alive | tr '\n' ' ')"
+    residue="$(probe_processes | tr '\n' ' ')"
+    case "$members$residue" in
+      *[0-9]*) : ;;
+      *) return 0 ;;
+    esac
+    [ "$(date +%s)" -ge "$deadline" ] && break
+    sleep 1
+  done
+  printf 'abort leak: group members alive: %s | private-path residue: %s\n' \
+    "${members:-none}" "${residue:-none}" >&2
+  return 1
+}
+
+diagnose_wrapper() {
+  printf 'abort leak diagnostic (%s): wrapper=%s %s\n' "$1" "$wrapper_pid" \
+    "$(ps -o pid=,ppid=,etime=,stat= -p "$wrapper_pid" 2>/dev/null | tr -s ' ')" >&2
+}
+
+# ---- leg 1: a trappable abort — the suite's own cleanup must reap the wrapper --------
+if [ "$ABORT_LEAK_PROBE_LEG" = 1 ] || [ "$ABORT_LEAK_PROBE_LEG" = all ]; then
+leg1_orphaned=0
+orphan_target_wrapper "" && leg1_orphaned=1
+check "leg1: the controller was removed and the wrapper reparented to init" '[ "$leg1_orphaned" = 1 ]'
+if [ "$leg1_orphaned" = 1 ]; then
+  signal_suite TERM
+  leg1_suite_gone=0; await_suite_exit && leg1_suite_gone=1
+  check "leg1: the aborted suite exits" '[ "$leg1_suite_gone" = 1 ]'
+  leg1_reaped=0; wrapper_gone_within "$GRACE" && leg1_reaped=1
+  [ "$leg1_reaped" = 1 ] || diagnose_wrapper leg1
+  check "leg1: a terminated suite reaps the reviewer wrapper it started" '[ "$leg1_reaped" = 1 ]'
+fi
+cleanup; PROBE_TMP=""; PROBE_TMP_REAL=""; suite_pgid=""
+fi
+
+# ---- leg 2: an untrappable abort — only the fixture's own bound can end the wrapper --
+if [ "$ABORT_LEAK_PROBE_LEG" = 2 ] || [ "$ABORT_LEAK_PROBE_LEG" = all ]; then
+leg2_orphaned=0
+orphan_target_wrapper "$LEG2_HANG_BOUND" && leg2_orphaned=1
+check "leg2: the controller was removed and the wrapper reparented to init" '[ "$leg2_orphaned" = 1 ]'
+if [ "$leg2_orphaned" = 1 ]; then
+  signal_suite KILL
+  leg2_suite_gone=0; await_suite_exit && leg2_suite_gone=1
+  check "leg2: the killed suite exits without running any cleanup" '[ "$leg2_suite_gone" = 1 ]'
+  # Precondition: with no trap able to run, the wrapper must still be here. If it is
+  # already gone, something else reaped it and the bound was never exercised.
+  # `kill -0` succeeds for a zombie, and the verdict below excludes zombies — so a wrapper
+  # that had already died would satisfy "still alive" here and "gone" there, passing the
+  # leg without the bound ever being exercised. Require a live, non-zombie process.
+  leg2_survived_abort=0
+  if kill -0 "$wrapper_pid" 2>/dev/null; then
+    case "$(ps -o stat= -p "$wrapper_pid" 2>/dev/null || true)" in
+      ''|*Z*) : ;;
+      *) leg2_survived_abort=1 ;;
+    esac
+  fi
+  check "leg2: no reaper ran, so the wrapper is still alive right after the kill" \
+    '[ "$leg2_survived_abort" = 1 ]'
+  leg2_self_exit=0; wrapper_gone_within "$(( LEG2_HANG_BOUND + GRACE ))" && leg2_self_exit=1
+  [ "$leg2_self_exit" = 1 ] || diagnose_wrapper leg2
+  check "leg2: an unreaped wrapper still exits on the fixture's own lifetime bound" \
+    '[ "$leg2_self_exit" = 1 ]'
+fi
+
+fi
+
+if [ "$fails" -eq 0 ]; then
+  echo "review_gate_abort_leak_ok leg=$ABORT_LEAK_PROBE_LEG client=$ABORT_LEAK_PROBE_CLIENT"
+  exit 0
+fi
+echo "review_gate_abort_leak_failed=$fails" >&2
+exit 1

package/dist/assets/marketplace/plugins/ccl-skills/skills/go-microservice-architecture/references/architecture-playbook.md

@@ -17,6 +17,8 @@ Do not create a service only because:
 - A team wants a cleaner folder.
 - A future scale concern is speculative.
 
+- External grounding (adopted in part): the criteria above take [Bounded Context](https://martinfowler.com/bliki/BoundedContext.html) (Fowler's overview of the central DDD strategic-design pattern; origin credited there to Eric Evans, *Domain-Driven Design*) as an input to boundary drawing — a boundary is where one internally consistent model stops being valid, so boundaries follow model and responsibility lines, never noun or table count — and [Conway's Law](https://martinfowler.com/bliki/ConwaysLaw.html) (Melvin Conway, ["How Do Committees Invent?", 1968](https://www.melconway.com/Home/Committees_Paper.html); Fowler's overview) — a system's structure mirrors the communication structure of the organization that builds it, which is why team ownership and communication structure are a legitimate split input. Two limits: the transactional-data-ownership, scaling, deployment-cadence, and rollback tests above are this skill's own operational criteria, attributed to neither source; and a bounded context does not require its own deployable service — several contexts can ship inside one modular monolith (this skill's monolith-first default), so these sources justify model/ownership boundaries, not a service-per-context split. Borrowed scope: boundary-input criteria only; no claim to the full DDD strategic-design method (context maps, ubiquitous language) or an inverse-Conway process. Sibling: `python-service-architecture/references/architecture-playbook.md` ("Architecture Decisions") carries the same grounding; keep the two in sync.
+
 ## Recommended Service Types
 
 ### API Gateway / HTTP Service

package/dist/assets/marketplace/plugins/ccl-skills/skills/go-microservice-architecture/references/cross-cutting-concerns.md

@@ -70,3 +70,9 @@
 - Every ctx key has a typed accessor; bare-string `ctx.Value(...)` returning `any` is an architecture finding, not an idiom to spread. Type assertion lives behind helpers, not in domain code.
 - For frameworks that propagate metadata over the wire, define which keys travel persistently (every downstream hop forwards them) versus transiently (one hop only). Lane, stress tag, and trace identity are typically persistent; one-off control flags should not be promoted to persistent.
 - Dual-injection compatibility: when one binary serves multiple transports (TTHeader Thrift + HTTP/2 gRPC), the propagation layer writes to both the framework's persistent value (`metainfo.WithPersistentValue`) and the transport's outgoing metadata so the framework's meta handler picks the right wire format at send time. Application code stays transport-agnostic.
+
+## Topic-extension backlog
+
+Entries here are registered candidates, not adopted guidance. Each names the candidate, its evidence status, and the condition that unblocks adoption; the round that evaluates one records keep/narrow/discard against its entry.
+
+- **Package-owned runtime-invariant registries (weak-keep candidate).** Observed form, from one agent-native product repository (evolving portfolio): each package contributes its own invariant checks from a companion module, normal entrypoints do not depend on the diagnostics layer, and allowlist/blocklist configuration selects which checks run. Evidence status: weak — single source; whether this generalizes as a cross-cutting pattern, and which reference should own it, is undecided. Evaluate the generalization at the next architecture round touching diagnostics, invariant checking, or startup validation, and record the outcome against this entry. The Python-stack sibling registration lives in `../python-service-architecture/references/packaging-runtime-readiness.md`.

package/dist/assets/marketplace/plugins/ccl-skills/skills/llm-inference-integration/SKILL.md

@@ -24,7 +24,8 @@ Use this for product backend work that calls, hosts, evaluates, or operates LLM
   - Core: model/version registry, prompt lifecycle, request schema, safety boundaries, streaming protocol, retry/fallback, eval datasets, replay/shadow rollout, token/cost metrics, batch/concurrency control, audit trails.
   - agent-skill-system runtime (progressive-disclosure loading, description-driven skill routing, skill trust/sandbox boundary)
   - MCP integration (server primitives, server-as-untrusted-domain trust boundary, OAuth 2.1 / audience-binding auth)
-  - agent command-execution sandbox (OS-sandbox composition, command-policy DSL, approval/escalation state machine, loopback-only egress proxy — see `references/agent-command-sandbox.md`)
+  - agent capability composition (seam/provider/model-facing-tool decomposition, reversible registration with scope-owned disposal, policy-plugin-vs-enforcement split, sub-agent provider seam with one-shot/continuable separation — see `references/agent-capability-composition.md`)
+  - agent command-execution sandbox (OS-sandbox composition, single-owner policy resolution consumed by every enforcement backend, command-policy DSL, approval/escalation state machine, loopback-only egress proxy — see `references/agent-command-sandbox.md`)
   - agent session persistence (append-only event-log source of truth, background-writer flush-before-finality, resume/fork with restored token accounting, context-window compaction — see `references/agent-session-persistence.md`)
   - agent ambient context freshness (diffable world-state sections vs one-shot fragments, comparison-snapshot-vs-rendered-text staleness detection, supersede-stale-in-band-not-retract, self-recognizing injections, derivable baseline + merge-patch re-derive on resume, budget-signaling-vs-compaction-enforcement — see `references/agent-context-freshness.md`)
   - robust model-driven file-edit (context-anchored hunks over line numbers, graduated-strictness matching, resolve-all-before-write, honest partial-failure reporting — see `references/agent-file-edit-protocol.md`)
@@ -72,6 +73,7 @@ Use this for product backend work that calls, hosts, evaluates, or operates LLM
    - Trace representative turns through every state transformation: at minimum the normal allow path, deny/ask permission path, resume/recovery path, and dynamic-tool-change path. Each trace must cover user input normalization, context construction, budget or compaction projection, model streaming, tool-call validation, permission decision, tool-result insertion, continuation, terminal stop condition, transcript write, and usage/cost accounting.
    - Each runtime concern below gets layer-separation, and its gate / assertions / routing live in the named reference (read before gating that concern):
      - Runtime startup & config bootstrap -> `references/agent-runtime-bootstrap.md`
+     - Capability composition — module/plugin boundaries, registration lifecycle, sub-agent providers -> `references/agent-capability-composition.md`
      - Turn lifecycle — per-turn loop, fg/bg handoff, progress, plan-to-execute, recap -> `references/agent-turn-lifecycle.md`
      - Session & transport — discovery/fork, history sync, workspace scope, protocol/stdout, settings migration -> `references/agent-session-persistence.md`
      - Hooks — hook/classifier output trust, hook config control plane, post-turn hooks -> `references/agent-lifecycle-hooks.md`

package/dist/assets/marketplace/plugins/ccl-skills/skills/llm-inference-integration/references/agent-capability-composition.md

@@ -0,0 +1,128 @@
+# Agent Capability Composition (Seams, Providers, Reversible Registration)
+
+How an agent runtime packages its capabilities so they can be swapped, unloaded, and extended
+without a privileged core: the decomposition unit, the registration lifecycle, and the sub-agent
+provider seam. This is the composition layer *around* the frameworks the sibling references own —
+`agent-tool-dispatch.md` owns how a call reaches a handler; `agent-runtime-bootstrap.md` owns
+config/trust at startup; this reference owns how the handler's capability is packaged, installed,
+and torn down.
+
+Patterns observed in one agent-native product repository (an evolving portfolio — treat as one
+industry form, not a standard) and consistent with general plugin-architecture practice. Use when
+designing or reviewing an agent runtime's module boundaries, plugin/extension system, or sub-agent
+integration; skip for a single-purpose agent whose capabilities never vary by deployment.
+
+## 1. A swappable capability is three parts — seam, provider, model-facing tool
+
+- When a capability must vary by deployment (local vs sandboxed filesystem, real vs replay model
+  transport, in-process vs external sub-agent), decompose it into three separately-packaged roles:
+  the **seam** (the service contract: abstract interface + vocabulary types), one or more
+  **providers** (implementations of the seam), and the **model-facing tool** (a *consumer* of the
+  seam that renders it into the model's tool surface). Consumers — tools, policies, other
+  capabilities — depend only on the seam; a provider is selected at assembly time. The tool is not
+  the implementation and never reaches around the seam into one.
+- Verify the decomposition by the swap test: a new provider (remote store, different vendor,
+  fault-injection fake) must drop in without touching the seam's consumers or the tool. If adding a
+  provider forces edits in consumers, the contract leaked implementation detail.
+- Design the seam's contract for **all current consumers**, not the loudest one: a method shaped for
+  a single consumer's UI/transport/private need does not belong on the shared contract. A public
+  seam method with exactly one internal caller is API surface without a second user — prefer a
+  capability closure injected at construction into the one consumer that needs it.
+- Keep role vocabulary honest in reviews: "the tool does X" is a smell when X is storage, policy, or
+  enforcement — those belong to a provider or a policy plugin, and the tool only surfaces them.
+  (Worked instances of the split: the spill store vs spill policy split in `agent-tool-dispatch.md`
+  §Result shaping; the sandbox policy-resolution vs enforcement-backend split in
+  `agent-command-sandbox.md` §2.)
+
+## 2. Registration is reversible; teardown is scope disposal, not per-plugin cleanup
+
+- Every registration-like effect a capability performs at install time (registering a tool, an
+  event listener, a provider, a background worker) must carry its inverse, and the runtime — not
+  each plugin author — owns applying inverses on unload. Model installation as effects recorded
+  into an **ownership scope**; teardown = dispose the scope, which replays the inverses in reverse
+  order. Correct unload is then guaranteed by one abstraction instead of N hand-written uninstall
+  paths, and a plugin author cannot forget it.
+- Hot-swap/reload is dispose-old-then-install-new under the same rule — never patch-in-place, which
+  accumulates the old registration's residue. The failure half needs a contract too: preflight the
+  new provider in an isolated scope *before* disposing the old one where the capability tolerates
+  brief coexistence. Where it does not, know what rollback can and cannot promise: registration
+  inverses reverse *local* effects only — disposal may have released a lease, port, credential, or
+  other external resource that reinstallation cannot reacquire — so a non-coexistent cutover either
+  uses an atomic/preflightable swap mechanism, or retains the old install descriptor and
+  rollback-critical resources until the new install commits, and when the install fails *and*
+  rollback also fails, the seam enters a **typed, surfaced unavailable state** (fail closed), never
+  a silent half-registered one. Verify with an install → dispose → re-install cycle asserting no
+  duplicate handlers, no leaked listeners, and no orphaned background work — plus failure injection
+  through BOTH layers: new provider's install throws (capability ends served by old or new where
+  the swap mechanism can guarantee it), and restoration fails too (capability ends in the typed
+  unavailable state, observably, rather than asserting never-neither for a path that cannot
+  guarantee it).
+- Disposal order matters: dispose in reverse registration order so dependents release before their
+  dependencies, and make disposal idempotent so a crash-then-cleanup path cannot double-free.
+- This composes with (does not replace) the trust and generation rules in
+  `agent-runtime-bootstrap.md`: a reversible registration that loads untrusted code is still gated
+  by trust state, and a reload still invalidates the caches keyed to the old generation.
+
+## 3. Policy plugins decide; providers enforce; absence has a declared default
+
+- When a rule about *when/whether* to act is separable from the mechanics of acting (when to spill
+  an oversized result, whether an edit target is stale, when to compact), package the rule as a
+  swappable **policy plugin** over the capability seam rather than hard-coding it into the
+  provider. The provider keeps the atomic enforcement check at the moment of action (freshness,
+  no-clobber, bounds) because a policy's observation can be stale by the time the action runs.
+- Declare what happens when the policy plugin is absent, and the declared default must fail toward
+  the safe direction for that capability's risk class — for a destructive-capable capability
+  (file overwrite, deletion, spend), absence means deny or require explicit approval, never a
+  silent degrade to the unguarded behavior. The cautionary shape: a runtime whose read-before-edit
+  observation policy is merely a removable plugin, with nothing beneath it, silently degrades to
+  unconditional overwrite when the plugin is missing — which is why the enforcement-layer
+  freshness/no-clobber check (`agent-command-sandbox.md` §Filesystem write authorization) stays
+  mandatory regardless of which policy plugins are installed, and a deployment-level opt-out of a
+  safety default must be explicit, never implied by absence.
+- Do not let advisory policy observations become authority: a policy that watches tool traffic to
+  derive guard state (which files were read, which calls repeated) produces *hints and gates*, and
+  the enforcement layer re-validates at execution time.
+
+## 4. Sub-agent integration is a provider seam, not a hardcoded runner
+
+- Expose sub-agent execution through the same seam/provider decomposition (§1), with one shape
+  difference: sub-agent providers are **named and co-resident** — a registry of concurrently
+  available providers selected per spawn (in-process fork, spawned worker, an external vendor
+  agent CLI) — unlike a single-selected executor seam. External vendor agent CLIs integrate as
+  first-class providers behind the seam, so consumers do not care whether a child is in-process or
+  a different vendor's product.
+- Split the contract by lifecycle: a **one-shot** run (spawn → result) and a **continuable**
+  session (spawn → handle → further turns → teardown) are different APIs; do not overload one call
+  shape with both. For continuable children, the child-side provider emits only a **creation
+  spec**; the parent-side runtime owns handle allocation, turn delivery, and teardown — a provider
+  that never sees handles cannot leak or forge them.
+- Make **fulfillment the single publish/ownership-transfer boundary**: a spawned child becomes
+  visible to consumers only when the provider fulfills the creation, and ownership (who tears it
+  down, whose scope disposes it) transfers exactly there — before fulfillment the provider owns
+  cleanup on failure; after, the runtime's scope does (§2). Two owners or zero owners at any point
+  is a leak or a double-free.
+- This reference owns the seam shape only. Spawn-depth/live-count caps, capability intersection,
+  and cascade-cancel live in `retrieval-agent-safety.md` §Agent SDK Building Blocks; task-state
+  finality and recovery live in `agent-task-orchestration.md`; both apply in full to every
+  provider, including external-CLI children.
+
+## Non-negotiables
+
+- A model-facing tool never depends on a concrete provider; consumers import the seam only.
+- Every registration carries its inverse; unload correctness is owned once by scope disposal, and
+  hot-swap is dispose-then-reinstall, never patch-in-place.
+- A policy plugin's absence has a declared, deliberate default; policy observations are advisory
+  and the provider re-checks atomically at action time.
+- One-shot and continuable sub-agent APIs stay separate; fulfillment is the only ownership-transfer
+  point, and continuable child providers emit creation specs, never handles.
+- These are composition patterns from one industry form — apply the swap/dispose/ownership tests
+  above as design gates, but do not cargo-cult the package layout onto a runtime whose capabilities
+  genuinely never vary.
+
+## Routing
+
+- Tool registry/dispatch mechanics, result shaping, and output spill policy → `agent-tool-dispatch.md`.
+- Startup trust, config generations, and cache invalidation on reload → `agent-runtime-bootstrap.md`.
+- Sandbox policy resolution vs enforcement backends → `agent-command-sandbox.md`.
+- Sub-agent spawn bounds and capability scoping → `retrieval-agent-safety.md`; task control plane → `agent-task-orchestration.md`.
+- Session/scope persistence of what was installed when (for replay) → `agent-session-persistence.md`.

package/dist/assets/marketplace/plugins/ccl-skills/skills/llm-inference-integration/references/agent-command-sandbox.md

@@ -59,6 +59,41 @@ Express the filesystem/network posture as a closed enum of named profiles. A min
 Default network to **off** in every write-capable profile. Network is a separate grant from
 filesystem write (§4).
 
+**One resolution owner; many enforcement backends.** Resolve "which profile + which writable
+root(s) apply to this call" in exactly one place — a single policy owner that combines the
+deployment default, the session's durable mode override, and any explicitly approved per-call mode
+(explicit approval outranks session override outranks default — but only among profiles the
+deployment/managed policy permits, and only after the §5/§6 authorization decision: a managed hard
+deny or a mandatory sandbox ceiling is non-overridable by per-call approval, per §6's layered
+precedence), and canonicalizes the session's
+working root with filesystem semantics before it becomes the writable root. Every enforcing
+backend — file tools, one-shot shell, persistent interactive sessions (§10) — consumes that one
+resolved mode-and-root result per call, keeping only its platform dialect (§4) local. If each
+backend re-resolves its own mode + root, they drift into a split world where the file layer and
+the shell layer disagree about what is confined — a gap a command that touches both walks straight
+through. One caveat is load-bearing: handing a backend the newly-resolved policy cannot *revoke*
+a kernel sandbox an already-running persistent session (§10) was launched under — those sessions
+bind the resolved policy and roots at creation, and whenever the creation-time grant is not a
+subset of the current grant, or the policy/root generation has changed incompatibly (a swapped
+writable root is not "narrower", yet the old root's access is revoked), the §10
+generation-binding rule applies: tear down and recreate under the new sandbox, or reject the
+command — never dispatch into the stale sandbox. (This is the policy/enforcement split of `agent-capability-composition.md` §3 applied to
+the sandbox.)
+
+**Present the resolved policy to the model as a replay-safe snapshot, not a capability inventory.**
+Before each request, the model should see the currently-resolved policy as part of a cache-safe
+runtime-context snapshot that is recorded into model-visible history — so replay can reconstruct
+exactly what the model was told without rewriting the stable system prompt (prompt-cache churn;
+see `llm-client-gateway.md`). Every generation persists for replay, but context construction
+exposes only the *current* snapshot to the model and supersedes prior ones for subsequent
+requests — after a broad-to-narrow policy change, stale snapshots left in the live envelope keep
+advertising permissions and roots the enforcement layer no longer grants (denied attempts,
+needless escalation, stale-path disclosure). Write that policy text as *what the policy means for operations*,
+never as an enumerated capability/tool inventory (the maybe-absent-tool steering anti-pattern in
+`agent-tool-dispatch.md`), and include the instruction that the model should not refuse an action
+merely because policy *might* deny it — attempt the tool and follow the denial/escalation guidance
+(§7) — otherwise the model self-censors more broadly than the policy actually restricts.
+
 **Reads need a confidentiality boundary too, not just writes.** A profile that confines *writes* but
 allows reading the whole host is still an exfil hole: an auto-approved "safe" read (`cat`, `rg`,
 `sed`, `find`) can slurp `~/.ssh`, `~/.aws`/cloud-credential files, browser profiles, keychains,