@ccoalm/ccl-skills 0.15.0 → 0.15.1

package/dist/assets/marketplace/plugins/ccl-skills/packages/opencode-plugin/ccl-skills.ts

@@ -6,6 +6,7 @@ import {
   mkdirSync,
   mkdtempSync,
   readFileSync,
+  readdirSync,
   realpathSync,
   rmSync,
   statSync,
@@ -337,6 +338,7 @@ export const CclSkills = async (context: {
   const hooksRoot = runtimeRoot()
   const parentSessions = new Map<string, string>()
   const idleInFlight = new Set<string>()
+  const pendingSkills = new Map<string, string>()
   let stateRoot: string | null = null
 
   function ensureStateRoot() {
@@ -390,9 +392,67 @@ export const CclSkills = async (context: {
     return typeof command === "string" && /\b(?:git\s+(?:push|merge)|gh\b[^\n;&|]*\bpr\s+merge|glab\b[^\n;&|]*\bmr\s+(?:merge|accept)|curl|wget)\b/i.test(command)
   }
 
-  function safeTranscriptInput(tool: string, args: Record<string, unknown>) {
-    if (tool === "skill") return typeof args.skill === "string" ? { skill: args.skill } : {}
-    return {}
+  function sameSkillDirectory(loaded: string, active: string) {
+    if (loaded === realpathSync(active)) return true
+    const pending = [[loaded, active]]
+    while (pending.length) {
+      const [copy, owner] = pending.pop()!
+      const copyStat = lstatSync(copy), ownerStat = lstatSync(owner)
+      if (copyStat.isSymbolicLink() || ownerStat.isSymbolicLink()) return false
+      if (copyStat.isDirectory() && ownerStat.isDirectory()) {
+        const copyNames = readdirSync(copy).sort(), ownerNames = readdirSync(owner).sort()
+        if (copyNames.length !== ownerNames.length || copyNames.some((name, index) => name !== ownerNames[index])) return false
+        for (const name of ownerNames) pending.push([join(copy, name), join(owner, name)])
+      } else if (!copyStat.isFile() || !ownerStat.isFile() || copyStat.size !== ownerStat.size || !readFileSync(copy).equals(readFileSync(owner))) return false
+    }
+    return true
+  }
+
+  function completedSkill(name: string | undefined, metadata: unknown) {
+    if (!name || !hooksRoot || !metadata || typeof metadata !== "object") return null
+    const result = metadata as { name?: unknown; dir?: unknown }
+    if (result.name !== name || typeof result.dir !== "string") return null
+    // The native tool reports the loaded source directory. A same-named skill
+    // elsewhere must never be promoted to a CCL owner by its caller's argument.
+    try {
+      const loaded = realpathSync(result.dir)
+      const entry = join(loaded, "SKILL.md")
+      if (!lstatSync(entry).isFile() || lstatSync(entry).isSymbolicLink()) return null
+      const content = readFileSync(entry, "utf8")
+      if (!content.startsWith(`---\nname: ${name}\n`)) return null
+      const activeRoot = existsSync(join(hooksRoot, "skills")) ? hooksRoot : resolve(hooksRoot, "../..")
+      // Bind the full skill to the running runtime: progressive disclosure loads
+      // references/scripts relative to this directory. Active source/project edits
+      // remain valid; inactive copies must match current files, without a stale cache.
+      const activeSkill = join(activeRoot, "skills", name)
+      const activeEntry = join(activeSkill, "SKILL.md")
+      if (!existsSync(activeEntry) || !lstatSync(activeEntry).isFile() || lstatSync(activeEntry).isSymbolicLink() || !sameSkillDirectory(loaded, activeSkill)) return null
+      const nativeRoots = [activeRoot, join(HOST_HOME, ".config/opencode"), join(directory, ".opencode"), join(context.worktree ?? directory, ".opencode")]
+      for (const root of nativeRoots) {
+        const expected = join(root, "skills", name)
+        if (existsSync(expected) && realpathSync(expected) === loaded && (root === activeRoot || existsSync(join(root, "ccl-skills/runtime/hooks/hooks.json")))) return `ccl-skills:${name}`
+      }
+      // Explicit skills.paths can select a CCL source checkout while a global
+      // adapter supplies the runtime. Require both its layout and the active bytes.
+      const sourceRoot = resolve(loaded, "../..")
+      const manifestPath = join(sourceRoot, ".claude-plugin/plugin.json")
+      if (loaded === join(sourceRoot, "skills", name) && existsSync(manifestPath)) {
+        const manifest = JSON.parse(readFileSync(manifestPath, "utf8"))
+        if (manifest?.name === "ccl-skills" && manifest?.skills === "./skills/") return `ccl-skills:${name}`
+      }
+      // The source installer also supports ~/.agents/skills. Require its existing
+      // receipt and the current native skill's bytes, not just a same-named file.
+      const compatibility = join(HOST_HOME, ".agents/skills", name)
+      const native = join(HOST_HOME, ".config/opencode/skills", name, "SKILL.md")
+      const receipt = join(HOST_HOME, ".config/opencode/ccl-skills/install-manifest.json")
+      if (existsSync(compatibility) && realpathSync(compatibility) === loaded && existsSync(receipt) && existsSync(native)) {
+        const manifest = JSON.parse(readFileSync(receipt, "utf8"))
+        if (manifest?.installer === "scripts/install-opencode.sh" && manifest?.install_mode === "global" && readFileSync(native, "utf8") === content) return `ccl-skills:${name}`
+      }
+      return null
+    } catch {
+      return null
+    }
   }
 
   async function resumeForStop(sessionID: string, reasons: string[]) {
@@ -446,6 +506,9 @@ export const CclSkills = async (context: {
       output.args = args
       const targets = editPaths(tool, args, directory)
       const toolName = claudeToolName(tool)
+      if (tool === "skill" && typeof args.name === "string" && /^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(args.name) && args.name.length <= 64) {
+        pendingSkills.set(`${sessionID}\0${callID}`, args.name)
+      }
       if (targets.length) {
         targets.forEach((filePath, index) => appendTranscript(sessionID, {
           type: "assistant",
@@ -454,7 +517,7 @@ export const CclSkills = async (context: {
       } else {
         appendTranscript(sessionID, {
           type: "assistant",
-          message: { content: [{ type: "tool_use", id: callID, name: toolName, input: safeTranscriptInput(tool, args) }] },
+          message: { content: [{ type: "tool_use", id: callID, name: toolName, input: {} }] },
         })
       }
 
@@ -507,6 +570,15 @@ export const CclSkills = async (context: {
       const tool = input.tool.toLowerCase()
       const sessionID = input.sessionID ?? `pid-${process.ppid}`
       const callID = input.callID ?? "unknown-call"
+      if (tool === "skill") {
+        const key = `${sessionID}\0${callID}`
+        const owner = completedSkill(pendingSkills.get(key), output.metadata)
+        pendingSkills.delete(key)
+        if (owner) appendTranscript(sessionID, {
+          type: "assistant",
+          message: { content: [{ type: "tool_use", id: callID, name: "Skill", input: { skill: owner } }] },
+        })
+      }
       appendTranscript(sessionID, {
         type: "user",
         message: { content: [{ type: "tool_result", tool_use_id: callID, content: "" }] },
@@ -536,6 +608,9 @@ export const CclSkills = async (context: {
           ? (properties.info as { id: string }).id
           : ""
       if (!sessionID) return
+      if (event.type === "session.deleted" || event.type === "session.idle" || (properties.status as { type?: string } | undefined)?.type === "idle") {
+        for (const key of pendingSkills.keys()) if (key.startsWith(`${sessionID}\0`)) pendingSkills.delete(key)
+      }
       if (event.type === "session.deleted") {
         const path = transcriptPath(sessionID)
         if (path) rmSync(path, { force: true })
@@ -562,6 +637,7 @@ export const CclSkills = async (context: {
     },
 
     dispose: async () => {
+      pendingSkills.clear()
       if (stateRoot) rmSync(stateRoot, { recursive: true, force: true })
       stateRoot = null
     },

package/dist/assets/marketplace/plugins/ccl-skills/packages/opencode-plugin/commands/ccl-install-skills.md

@@ -3,12 +3,24 @@ description: Install or refresh CCL skills for OpenCode
 argument-hint: "[--project]"
 ---
 
-Run the CCL OpenCode installer from the repository root.
+Install or reapply the CCL assets using the current installation mode. Check the existing CCL installation record and available entrypoint before running a command.
 
-Use `--project` when the user wants project-local `.opencode/skills`, `.opencode/commands`, and `.opencode/plugins` copied into this repository.
+For an npm installation, reapply the invoked package's OpenCode assets:
 
 ```bash
-bash scripts/install-opencode.sh $ARGUMENTS
+ccl-skills install --host opencode
 ```
 
-After installation, tell the user to restart OpenCode or open a new session.
+For a newer package version, follow `/ccl-update-skills`. The npm package does not include the source installer or support `--project`; do not forward that flag to the npm CLI.
+
+For a source checkout, locate the actual CCL repository and verify its installer exists. By default, from that checkout run:
+
+```bash
+bash scripts/install-opencode.sh --no-agent $ARGUMENTS
+```
+
+Use `--project` only for source mode when the user wants `.opencode/skills`, `.opencode/commands`, and `.opencode/plugins` copied into that checkout. Do not run a relative source-installer path in an unrelated project.
+
+For a global source installation, omit `--no-agent` when the user also needs `~/.agents/skills` for another tool. To sync only that compatibility path, run `bash scripts/install-opencode.sh --only-agent`; this mode does not install OpenCode assets and cannot be combined with `--project` or `--no-agent`.
+
+After OpenCode assets change, restart OpenCode or open a new session. After a compatibility-only sync, restart the tool that reads `~/.agents/skills`.

package/dist/assets/marketplace/plugins/ccl-skills/scripts/owner-dispatch/owner-dispatch.sh

@@ -1059,7 +1059,15 @@ def main(argv):
     head_enabled = enabled(head_cfg)
     base_enabled = enabled(base_cfg)
 
-    diff = run_git(["diff", "-z", "--name-only", base, "HEAD"], cwd=repo, text=False)
+    # --no-renames so a file moved OUT of a gated directory is still seen at its old
+    # (gated) path; rename detection would only report the exempt destination.
+    # --ignore-submodules=none so repository config (diff.ignoreSubmodules=all) cannot
+    # suppress a gitlink move out of the gated tree, which would leave only .gitmodules.
+    diff = run_git(
+        ["diff", "-z", "--name-only", "--no-renames", "--ignore-submodules=none", base, "HEAD"],
+        cwd=repo,
+        text=False,
+    )
     if diff.returncode != 0:
         return fail("owner-dispatch ci: diff failed — FAIL-CLOSED (2)")
     changed = [p.decode("utf-8", "surrogateescape") for p in diff.stdout.split(b"\0") if p]
@@ -1183,7 +1191,10 @@ cmd_ci() {
   # file (NUL can't survive a shell var) so paths with spaces/newlines classify exactly.
   local CHANGED=() difftmp rel
   difftmp=$(mktemp 2>/dev/null) || { echo "owner-dispatch ci: mktemp failed — FAIL-CLOSED (2)" >&2; return 2; }
-  git diff -z --name-only "$base" HEAD > "$difftmp" 2>/dev/null || { rm -f "$difftmp"; echo "owner-dispatch ci: diff failed — FAIL-CLOSED (2)" >&2; return 2; }
+  # -C "$repo" so diff.relative cannot truncate the set when ci runs from a subdirectory;
+  # --no-renames and --ignore-submodules=none: see the Python path above. Both paths must
+  # classify the same file set regardless of repository diff configuration or cwd.
+  git -C "$repo" diff -z --name-only --no-renames --ignore-submodules=none "$base" HEAD > "$difftmp" 2>/dev/null || { rm -f "$difftmp"; echo "owner-dispatch ci: diff failed — FAIL-CLOSED (2)" >&2; return 2; }
   while IFS= read -r -d '' rel; do CHANGED+=("$rel"); done < "$difftmp"
   rm -f "$difftmp"
 

package/dist/assets/marketplace/plugins/ccl-skills/scripts/owner-dispatch/test.sh

@@ -523,6 +523,59 @@ echo "// z" >> "$REPO/src/foo.go"; gc more
 # 10i. CI fails CLOSED when it cannot determine a base (no --base, no upstream).
 if ( cd "$REPO" && bash "$ENGINE" ci >/dev/null 2>&1 ); then bad "ci no-base should fail-closed"; else ok "ci: no base => fail-closed (non-zero)"; fi
 
+# 10j. a gated file moved OUT of the gated tree is still a gated change. Two ways the diff
+#      can hide it: rename detection resolves a pure move to the exempt destination only,
+#      and diff.ignoreSubmodules=all drops a moved gitlink entirely. Both ci paths (jq and
+#      the python fallback) must classify the same set, so each case runs on both.
+command -v jq >/dev/null 2>&1 || bad "ci rename-out: jq absent" "the jq lane would silently be a second python run"
+[ -z "$(PATH="$NOJQBIN" command -v jq || true)" ] || bad "ci rename-out: NOJQBIN still resolves jq" "the python lane would silently be a second jq run"
+printf '%s\n' "$EN" | rawcfg
+mkdir -p "$REPO/design" "$REPO/exempt"; echo "owners: x" > "$REPO/design/map.md"
+echo "package x" > "$REPO/src/moved.go"; gc renamebase
+rnbase=$(git -C "$REPO" rev-parse HEAD)
+git -C "$REPO" config diff.renames true   # else the base engine reports the source anyway
+git -C "$REPO" mv src/moved.go exempt/moved.go; gc renameout
+jq_rc=0; jq_out=$( cd "$REPO" && bash "$ENGINE" ci --base "$rnbase" 2>&1 ) || jq_rc=$?
+py_rc=0; py_out=$( cd "$REPO" && PATH="$NOJQBIN" bash "$ENGINE" ci --base "$rnbase" 2>&1 ) || py_rc=$?
+[ "$jq_rc" = 1 ] && [ "$py_rc" = 1 ] && ok "ci: gated file renamed out of scope, stale map => fail on both lanes" || bad "ci rename-out rc" "jq=$jq_rc py=$py_rc"
+case "$jq_out$py_out" in *src/moved.go*src/moved.go*) ok "ci rename-out: both lanes name the gated source path" ;; *) bad "ci rename-out diagnostic" "$jq_out | $py_out" ;; esac
+# cwd must not change the verdict: with diff.relative=true a diff run from a subdirectory
+# would drop paths outside it, and the two lanes would disagree.
+git -C "$REPO" config diff.relative true
+rel_jq=0; ( cd "$REPO/exempt" && bash "$ENGINE" ci --base "$rnbase" >/dev/null 2>&1 ) || rel_jq=$?
+rel_py=0; ( cd "$REPO/exempt" && PATH="$NOJQBIN" bash "$ENGINE" ci --base "$rnbase" >/dev/null 2>&1 ) || rel_py=$?
+[ "$rel_jq" = 1 ] && [ "$rel_py" = 1 ] && ok "ci: run from a subdirectory under diff.relative=true => still fail on both lanes" || bad "ci rename-out relative rc" "jq=$rel_jq py=$rel_py"
+git -C "$REPO" config --unset diff.relative
+echo "owners: y" >> "$REPO/design/map.md"; gc renameoutmap
+ok_jq=0; ( cd "$REPO" && bash "$ENGINE" ci --base "$rnbase" >/dev/null 2>&1 ) || ok_jq=$?
+ok_py=0; ( cd "$REPO" && PATH="$NOJQBIN" bash "$ENGINE" ci --base "$rnbase" >/dev/null 2>&1 ) || ok_py=$?
+[ "$ok_jq" = 0 ] && [ "$ok_py" = 0 ] && ok "ci: renamed-out gated file with updated map => ok on both lanes" || bad "ci rename-out with map" "jq=$ok_jq py=$ok_py"
+# an option-like base must be rejected before any diff runs, on both lanes
+for badbase in "--output=$WORK/pwned" "-z"; do
+  b_jq=0; ( cd "$REPO" && bash "$ENGINE" ci --base "$badbase" >/dev/null 2>&1 ) || b_jq=$?
+  b_py=0; ( cd "$REPO" && PATH="$NOJQBIN" bash "$ENGINE" ci --base "$badbase" >/dev/null 2>&1 ) || b_py=$?
+  [ "$b_jq" = 2 ] && [ "$b_py" = 2 ] && ok "ci: option-like base '$badbase' => fail-closed(2) on both lanes" || bad "ci option-base rc" "jq=$b_jq py=$b_py"
+done
+[ ! -e "$WORK/pwned" ] && ok "ci: option-like base created no file" || bad "ci option-base wrote a file"
+
+# 10j2. the same bypass through a submodule, which repository config can hide outright.
+SUBSRC="$WORK/subsrc"; mkdir -p "$SUBSRC"
+git -C "$SUBSRC" init -q; git -C "$SUBSRC" config user.email t@t; git -C "$SUBSRC" config user.name t
+echo hi > "$SUBSRC/f.txt"; git -C "$SUBSRC" add -A; git -C "$SUBSRC" commit -qm sub
+sub_err=$(git -C "$REPO" -c protocol.file.allow=always submodule add -q "$SUBSRC" src/vendor 2>&1) || true
+if [ -e "$REPO/src/vendor/f.txt" ]; then
+  gc subbase
+  sub_base=$(git -C "$REPO" rev-parse HEAD)
+  git -C "$REPO" config diff.ignoreSubmodules all
+  git -C "$REPO" mv src/vendor exempt/vendor; gc submove
+  sm_jq=0; sm_jq_out=$( cd "$REPO" && bash "$ENGINE" ci --base "$sub_base" 2>&1 ) || sm_jq=$?
+  sm_py=0; sm_py_out=$( cd "$REPO" && PATH="$NOJQBIN" bash "$ENGINE" ci --base "$sub_base" 2>&1 ) || sm_py=$?
+  [ "$sm_jq" = 1 ] && [ "$sm_py" = 1 ] && ok "ci: submodule moved out of scope under diff.ignoreSubmodules=all => fail on both lanes" || bad "ci submodule-move rc" "jq=$sm_jq py=$sm_py"
+  git -C "$REPO" config --unset diff.ignoreSubmodules
+else
+  bad "ci submodule-move: could not create the submodule fixture" "$sub_err"
+fi
+
 # ---- 11. SubagentStop: agent_id-scoped enforcement (the same engine handles Stop +
 #         SubagentStop; agent_id is present only for the latter and scopes markers/cap). ----
 rm -rf "$BDIR"

package/dist/assets/marketplace/plugins/ccl-skills/skills/code-review/scripts/review_gate.py

@@ -2736,6 +2736,7 @@ def freeze_review_profile(
     required_self_review_fields = {"concern", "conclusion", "evidence_refs"}
     self_review: list[dict[str, Any]] = []
     seen_concerns: set[str] = set()
+    seen_owner_concerns: set[tuple[str, str]] = set()
     for index, item in enumerate(self_review_raw):
         item_fields = set(item) if isinstance(item, dict) else set()
         if item_fields not in (
@@ -2761,7 +2762,6 @@ def freeze_review_profile(
             len(normalized_conclusion) < 20
             or placeholder_key in PLACEHOLDER_TEXT
             or concern not in known_concern_ids
-            or concern in seen_concerns
             or not isinstance(references, list)
             or not references
             or any(
@@ -2781,6 +2781,12 @@ def freeze_review_profile(
             )
         except GateError as exc:
             raise GateError(exc.reason, "self_review_incomplete") from exc
+        if (concern, skill) in seen_owner_concerns:
+            raise GateError(
+                "self_review repeats a concern for the same skill",
+                "self_review_incomplete",
+            )
+        seen_owner_concerns.add((concern, skill))
         seen_concerns.add(concern)
         self_review.append(
             {

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

@@ -1233,6 +1233,71 @@ out="$(run_gate --review-plan-file "$WORK/owner-review-plan.json" --allow-fallba
 check "owner-aware success without a wrapper binding receipt fails closed" \
   '[ "$rc" = 2 ] && json_fields "$out" reason_code=binding_mismatch next_action=stop_reviewer_lane && [ "$(printf "%s" "$out" | python3 -c "import json,sys; print(len(json.load(sys.stdin).get(\"reviewed_skills\", [])))")" = 0 ]'
 
+# Owner count is independent of concern count: a cross-skill candidate can have
+# more owners than the eight known concerns without changing the review scope.
+python3 - "$WORK" <<'PY'
+import copy
+import json
+from pathlib import Path
+import sys
+
+work = Path(sys.argv[1])
+owners = (
+    "requirement-scope", "product-rd-workflow", "platform-service-connectivity",
+    "platform-observability", "skill-extraction-workflow", "python-service-dev",
+    "web-react-dev", "testing-strategy", "terminal-cli-dev",
+)
+plan = json.loads((work / "review-plan.json").read_text())
+patches = []
+for owner in owners:
+    root = work / owner
+    root.mkdir(exist_ok=True)
+    entrypoint = root / "SKILL.md"
+    if not entrypoint.exists():
+        entrypoint.write_text(f"# Synthetic {owner} owner\n")
+    plan["self_review"].append({
+        "concern": "correctness", "skill": owner,
+        "conclusion": f"The {owner} boundary preserves its stated acceptance behavior.",
+        "evidence_refs": ["e1"],
+    })
+    path = f"skills/{owner}/SKILL.md"
+    patches.append(f"diff --git a/{path} b/{path}\n--- a/{path}\n+++ b/{path}\n@@ -1 +1 @@\n-old\n+new\n")
+(work / "many-owner-diff.patch").write_text("".join(patches))
+plans = {"many-owner": plan}
+missing_owner = copy.deepcopy(plan)
+missing_owner["self_review"].pop()
+plans["many-owner-missing-owner"] = missing_owner
+missing_concern = copy.deepcopy(plan)
+missing_concern["self_review"] = [row for row in missing_concern["self_review"] if row["concern"] != "safety"]
+plans["many-owner-missing-concern"] = missing_concern
+duplicate = copy.deepcopy(plan)
+duplicate["self_review"].append(copy.deepcopy(duplicate["self_review"][-1]))
+plans["many-owner-duplicate"] = duplicate
+default_duplicate = copy.deepcopy(plan)
+default_duplicate["self_review"].append({**default_duplicate["self_review"][0], "skill": "code-review"})
+plans["many-owner-default-duplicate"] = default_duplicate
+for name, value in plans.items():
+    (work / f"{name}-plan.json").write_text(json.dumps(value))
+PY
+
+reset_case passed unavailable unavailable
+out="$(run_gate --diff-file "$WORK/many-owner-diff.patch" --review-plan-file "$WORK/many-owner-plan.json")"; rc=$?
+check "nine derived owners can assess shared concerns in one explicit plan" \
+  '[ "$rc" = 0 ] && json_fields "$out" status=passed review_plan_source=implementer-supplied owner_selection_source=controller-derived+implementer-declared && [ "$(printf %s "$out" | python3 -c "import json,sys; p=json.load(sys.stdin); print(len(p[\"selected_skills\"]), len(p[\"reviewed_skills\"]))")" = "10 9" ]'
+printf '%s\n' "$out" >"$WORK/many-owner-review.json"
+
+reset_case passed unavailable unavailable
+out="$(run_completion_gate --diff-file "$WORK/many-owner-diff.patch" --review-plan-file "$WORK/many-owner-plan.json" --completion-review-result-file "$WORK/many-owner-review.json")"; rc=$?
+check "nine-owner explicit self-review closes the exact-candidate completion checkpoint" \
+  '[ "$rc" = 0 ] && [ ! -e "$WORK/state/client_sequence" ] && json_fields "$out" mode=complete status=passed completion_gated=false next_action=complete'
+
+for invalid_plan in missing-owner missing-concern duplicate default-duplicate; do
+  reset_case passed unavailable unavailable
+  out="$(run_gate --diff-file "$WORK/many-owner-diff.patch" --review-plan-file "$WORK/many-owner-$invalid_plan-plan.json")"; rc=$?
+  check "shared-concern owner plans reject $invalid_plan before provider execution" \
+    '[ "$rc" = 2 ] && [ ! -e "$WORK/state/client_sequence" ] && json_fields "$out" reason_code=self_review_incomplete next_action=deep_self_review'
+done
+
 printf 'diff --git a/skills/testing-strategy/SKILL.md b/skills/testing-strategy/SKILL.md\n--- a/skills/testing-strategy/SKILL.md\n+++ b/skills/testing-strategy/SKILL.md\n@@ -1 +1 @@\n-old\n+new\n' >"$WORK/diff.patch"
 reset_case passed unavailable unavailable
 out="$(run_gate --allow-fallback-egress)"; rc=$?

package/dist/assets/marketplace/plugins/ccl-skills/skills/platform-observability/SKILL.md

@@ -30,7 +30,7 @@ Observability is the chain that turns one user action into searchable, joinable,
 2. **Instrumentation** — every service emits structured logs, metrics, and spans through the **framework default**, not ad-hoc code. A service whose middleware chain does not include `ctx_inject + metrics + recovery + tracing` is unobservable by design.
 3. **Transport** — logs go stdout → file collector (DaemonSet) → log pipeline → search index; metrics + traces go SDK → OTLP collector → metric store + trace store. Both transports must survive collector restarts and back-pressure.
 4. **Storage + display** — logs in a searchable index keyed by log-id and trace-id; metrics in a long-term store separate from scraper; traces queryable by trace-id; one dashboard tool joins all three.
-5. **Evidence consumption** — SLIs are queries against (3) + (4); alerts evaluate SLIs and route to on-call; runbooks live in a wiki that on-call can reach in under one minute.
+5. **Evidence consumption** — SLIs query (3) + (4); actionable alerts route to on-call; runbooks live in a wiki that on-call can reach in under one minute.
 
 A new service must satisfy all five before it is allowed in production. A release must produce evidence at all five before it is promoted.
 
@@ -106,9 +106,9 @@ Add domain fields with a prefix (e.g. `app_*`, `biz_*`) to avoid colliding with
 
 **Retrofit / migration contract** (the rules above are otherwise greenfield-framed): when a schema is introduced over EXISTING services, field names, metric label names, and identity env-var names are a **migration contract** — a blind rename breaks every deployed dashboard, alert, and saved query that keys on the old name. Retrofitting MUST alias or dual-write old→new and migrate consumers before retiring the old name; never rename in place. The cheap time to fix a name is before services adopt it.
 
-### R7 — Alerts are SLI-driven and route to a human
+### R7 — Alerts are actionable and route to an owner
 
-- Alerts evaluate against SLIs (query the long-term metric store), not raw metrics.
+- Use SLIs for SLO paging; actionable capacity or impending-failure alerts may use internal measurements. See `references/alerting-and-on-call.md`.
 - Severity levels: P0 (page on-call now), P1 (notify channel, ack within work hours), P2 (digest).
 - Every alert MUST link to a runbook entry. If no runbook exists, the alert is not allowed to be P0.
 - An alert-backed metric is a coverage contract, and the trigger is mechanical, not prose: any new or changed alert rule, SLO, dashboard alert annotation, or metric referenced by an alert policy fires this check (a written "alert on any increase" note also counts, but its absence is not an exemption). Enumerate every site that should feed the metric and verify each is actually instrumented — derive the site list from a static registry or lint where possible; the easiest site to miss is often the riskiest (e.g. the panic counter in a stream reader parsing untrusted bytes). Ship the site checklist with the alert.
@@ -208,7 +208,7 @@ If any phase has missing evidence, the work is not done.
 - **"Sample everything vs head-sample 1%"** → head-sample low (1–10%) for cost; retaining errors/slow requests is **tail** sampling at the Collector and requires near-full SDK export to it (head-dropped spans never arrive) — pick one model per service, do not claim both. Sampling-by-route is acceptable for known noisy paths.
 - **"Metrics egress: scrape vs push"** → each platform picks ONE canonical egress and every process uses it. A Prometheus-native platform may default to **scrape** (pull, with `up`/target-health + service discovery); an OTel-first platform, or workers/jobs/runtimes that can't be scraped, may default to **OTLP push** to a collector. Neither is universally better — don't overturn a working pull setup just to push. One egress per process for a given metric; a migration window may dual-write only with isolated pipelines / distinct metric names / a dedup plan. Long-term store stays separate from the short-term scrape/collect layer (R5).
 - **"Add a new label to a metric"** → answer the cardinality question first. If max distinct values × series count > 1e6, refuse and use an exemplar trace instead.
-- **"Alert on this symptom or that cause"** → alert on user-visible symptom; cause-based alerts produce paging spam.
+- **"Alert on this symptom or that cause"** → prefer user-visible symptoms; capacity or impending-failure warnings follow R7.
 
 ## Sanitization and Provenance
 

package/dist/assets/marketplace/plugins/ccl-skills/skills/platform-observability/references/alerting-and-on-call.md

@@ -1,5 +1,13 @@
 # Alerting and On-Call
 
+## Choose an actionable signal
+
+- **User symptoms and SLOs:** use service-level signals for user-symptom paging and the corresponding SLIs for SLO burn-rate alerts. Query the declared metric store; diagnostic counters do not become availability or latency SLIs merely because an alert uses them.
+- **Capacity and impending failures:** white-box measurements may warn before user SLIs degrade, such as a credible forecast of disk exhaustion. Record the expected failure, the evidence for the threshold or forecast, the action, and the responsible owner. Choose urgency from impact and time left to act; a high internal metric alone is not a reason to page.
+- **Diagnostic signals:** keep measurements with no actionable condition in dashboards or queries. Do not alert on every possible cause.
+
+Verify new or changed alert rules against relevant failure, healthy, and recovery cases. Preserve the severity, ownership, runbook, and delivery requirements below for both symptom and impending-failure alerts. [Google SRE's Monitoring Distributed Systems](https://sre.google/sre-book/monitoring-distributed-systems/) describes both user symptoms and imminent saturation as alerting inputs.
+
 ## Two patterns
 
 ### Pattern A — Prometheus AlertManager

package/dist/assets/marketplace/plugins/ccl-skills/skills/platform-service-connectivity/SKILL.md

@@ -100,10 +100,11 @@ Confusing these is the source of most "why doesn't this work" connectivity bugs.
 
 ### R4 — Default retry/timeout/circuit-breaker live at mesh, app overrides for business reasons
 
-- Mesh DestinationRule provides default per-callee policy: retries (1-2 attempts on 5xx/connect-fail), connect timeout, request timeout ceiling, outlier detection (5xx-percent → eject).
-- Framework client SDK provides per-call override: business timeout (always ≤ mesh ceiling), retry policy for idempotent calls, hedging.
+- On Istio HTTP/gRPC paths, `VirtualService` HTTP routes own request `timeout` and `retries`; `DestinationRule` owns connection-pool settings and `outlierDetection`. Other transports use their platform-owned equivalents.
+- Before configuring retries or timers, read `references/retry-timeout-circuit-breaker.md` for field paths, single-owner retry selection, and idempotency checks. Both mesh and SDK follow them; a 5xx or missing response alone never proves replay safe.
+- Framework client SDK may provide method-specific retry/hedging; its total call budget must fit the caller's remaining duration and any platform cap. A longer mesh timeout is a backstop, not an extended caller deadline.
 - App code MAY override per-RPC. App code MUST NOT silently disable mesh-level outlier detection.
-- Budget rule: total upstream timeout = caller deadline minus a safety margin (e.g. 100ms). Cascading timeouts must shrink down the call chain.
+- Budget rule: downstream work, attempts, and backoff fit the remaining duration minus a safety margin (e.g. 100ms). Propagate deadline and cancellation; never reset the full budget at each hop.
 
 ### R5 — mTLS is mesh-default, app cannot disable
 
@@ -151,14 +152,13 @@ The client middleware fills this from ctx automatically; the server middleware e
 
 For non-protobuf or metadata-only transports, an equivalent header set is compliant only when it cites a resolvable platform owner record, such as a repo/path, document URL, registry id, gateway policy, or owner-suite id. The owner record must enumerate the concrete header names. In diff-only review without resolver tooling, the diff must cite a stable owner-record locator and list the concrete header names inline; with resolver tooling, the reviewer or owner-suite may resolve the locator to those names instead. The enumerated header names must then be checked against the actual propagated and exposed headers: caller-supplied identity headers are absent unless positive authenticated-caller evidence exists. An unresolvable, non-enumerating, uncited, service-local, or unchecked header set is an open gap, not a permitted alternative. For pure HTTP (no RPC base), the equivalent is a stable owner-recorded header set, also filled by middleware.
 
-### R8 — gRPC `:authority` and DNS-label hyphenation
+### R8 — gRPC `:authority` compatibility follows the actual request path
 
-If the platform allows service names with underscores (`<owner>.<class>.<env>` containing `_`), gRPC will reject them in the HTTP/2 `:authority` pseudo-header because it must be a valid DNS label (no `_`). Two acceptable fixes:
+HTTP/2 `:authority` carries URI authority, not a single DNS label. An underscore alone does not prove a gRPC protocol violation. DNS hostnames, certificate identity checks, SDK validation, and proxy routing can impose different constraints; preserve the constraints of the deployed path.
 
-1. **Disallow underscores in new service names**; enforce in registry registration and CI.
-2. **Mesh-level rewrite**: an EnvoyFilter Lua snippet replaces `_` with `-` in `:authority` for gRPC requests, before routing.
+Before renaming a service or adding a rewrite, capture the failing request's authority, the rejecting layer and version, and the relevant error or trace. A platform may require DNS-compatible service names and enforce that policy at registration and CI, but a registry name need not be the wire authority.
 
-Option 1 is cleaner long-term; option 2 is the live-system workaround. Document which the platform uses; new services should follow option 1.
+A proxy rewrite is an option only when the request reaches that filter before the rejecting layer. It cannot fix a client rejection before transmission or an inbound parser rejection before the filter runs. Scope any verified rewrite to the affected traffic and explicit authority mappings; retain route, TLS identity, and authorization checks. Diagnosis, migration, and verification: `references/grpc-authority-workaround.md`.
 
 ### R9 — Ingress and egress are explicit, not implicit
 
@@ -200,8 +200,8 @@ Option 1 is cleaner long-term; option 2 is the live-system workaround. Document
 ### Phase B — Mesh policy
 
 1. PeerAuthentication = STRICT (mTLS namespace-wide).
-2. DestinationRule per critical callee: retry policy, timeouts, outlier detection.
-3. VirtualService rules express lane-based routing: lane header match → lane subset.
+2. DestinationRule per critical callee: connection-pool limits, connect timeout, outlier detection.
+3. VirtualService HTTP routes: lane header match → lane subset, request timeout, and the R4 retry policy.
 4. AuthorizationPolicy expresses which services may call which (zero-trust at network level).
 
 ### Phase C — Service discovery
@@ -216,7 +216,7 @@ Option 1 is cleaner long-term; option 2 is the live-system workaround. Document
 
 1. Read the framework default client/server options module. Confirm middleware chain matches R6.
 2. Confirm dev cannot build a client/server without inheriting these.
-3. Test: kill a downstream pod → verify mesh outlier-detection ejects, framework retry kicks in for idempotent calls, error propagates up with stable error-code.
+3. Test: induce the configured outlier threshold on one callee → verify ejection and recovery, the configured retry layer retries only eligible calls within its budget, and exhausted calls propagate a stable error-code.
 
 ### Phase E — Failure modes
 
@@ -234,7 +234,7 @@ Before marking work done:
 
 ## Decision Points
 
-- **"Add a new retry policy for service X"** → start at mesh DestinationRule. Move to framework client only if the retry depends on business idempotency knowledge.
+- **"Add a new retry policy for service X"** → apply R4's replay-safety and single-owner checks. Use the matching VirtualService HTTP route for Istio retries; disable and verify route retries when the SDK owns them. DestinationRule limits concurrent retries, not per-request attempts.
 - **"Service A times out calling Service B"** → check three layers in order: app deadline (ctx timeout) → framework client timeout → mesh request timeout. Whichever is smaller wins; align them.
 - **"Switch service discovery mode"** → use `references/service-discovery-choice.md`; do not mandate registry unless the platform needs registry-specific capabilities such as per-instance drain, out-of-cluster lookup, or existing registry federation.
 - **"Need mTLS to a non-mesh external service"** → egress gateway with terminating TLS, not app-managed certs.
@@ -257,7 +257,7 @@ Reused industry patterns (PSM-style identity, `<owner>.<class>.<env>` shape, `tr
 - `references/framework-middleware.md` — Server and client middleware chain (HTTP + RPC); the canonical RPC base struct shape; verification commands.
 - `references/multi-env-routing.md` — Lane label end-to-end recipe; VirtualService patterns; queue-boundary propagation; stress/shadow tags.
 - `references/retry-timeout-circuit-breaker.md` — Mesh defaults vs SDK overrides; cascading timeout budgets; idempotency awareness; outlier detection tuning.
-- `references/grpc-authority-workaround.md` — The `_` → `-` rewrite quirk; when it's needed; the cleaner long-term fix.
+- `references/grpc-authority-workaround.md` — Locate authority rejection; distinguish naming policy from protocol syntax; verify scoped compatibility changes.
 - `references/dual-sidecar-and-traffic-config-center.md` — Pod-level dual sidecar (mesh + platform), per-protocol mesh injection policy, per-caller-callee traffic config via config center (separate from mesh routing).
 - `references/rpc-framework-recipe.md` — Concrete kitex/hertz default suite: shared RPC base field contract, RPC base.Request full schema (8 fields incl From/To), dual-channel ctx propagation (metainfo + grpc metadata), 9-code error enum + framework error mapping table, three resolver strategies (registry / FQDN fallback / proxy), platform latency histogram buckets, CORS defaults exposing log-id header, server boot sequence with graceful shutdown.
 - `references/service-discovery-choice.md` — Decision framework: registry-based vs k8s-native SD; both support lane routing + canary + multi-env; pick by per-instance drain need, laptop access pattern, federation preference, operational burden; mixed mode (k8s east-west + thin registry for laptop) is workable; migration paths in both directions.
@@ -269,7 +269,7 @@ Reused industry patterns (PSM-style identity, `<owner>.<class>.<env>` shape, `tr
 
 1. **Static**: framework default options module includes all R6 middleware; mesh PeerAuthentication is STRICT; DestinationRule and VirtualService exist for every callee that participates in lane routing.
 2. **Live, identity**: cross-service trace shows log-id + lane consistent across all hops; mesh access log lines include both.
-3. **Live, mesh policy**: kill a callee pod → outlier detection ejects within outlier-detection interval; metrics show client-side error count rise then fall.
+3. **Live, mesh policy**: trigger the configured outlier threshold with an eligible pool size; verify ejection and recovery against the effective policy and metrics. Consecutive-error checks are inline, not delayed until the periodic analysis interval.
 4. **Live, lane routing**: send request with non-default lane → confirm only matching-lane instances serve it.
 5. **Static, no leakage**: grep this skill's content — zero internal hostnames, repo names, or business terms.
 

package/dist/assets/marketplace/plugins/ccl-skills/skills/platform-service-connectivity/references/dual-sidecar-and-traffic-config-center.md

@@ -36,7 +36,7 @@ Mesh injection is not all-or-nothing. Real platforms apply per-protocol policy:
 | App protocol | Inject Istio sidecar? | Reason |
 |---|---|---|
 | HTTP (REST) | YES | Envoy handles HTTP/1.1, HTTP/2; full feature support |
-| gRPC | YES | HTTP/2 + per-call routing; needs `:authority` quirk handling |
+| gRPC | YES | HTTP/2 + per-call routing; verify `:authority` routing against the actual SDK/proxy path |
 | TCP (raw) | NO (often) | Envoy TCP proxy is feature-poor; routing/auth less useful at L4 |
 | Thrift (TTHeader) | NO (often) | Same — L4-ish; tooling limited |