@ccoalm/ccl-skills 0.15.0 → 0.15.2

package/dist/assets/marketplace/plugins/ccl-skills/skills/defect-diagnosis/SKILL.md

@@ -5,7 +5,9 @@ description: bug / 报错 / test 挂了 / 线上问题 / 接口变慢·性能退
 
 # Defect Diagnosis
 
-Use this skill for the full defect discipline: diagnose the immediate failure, fix it with evidence, then decide whether root-cause prevention should update a product, architecture, development, testing, release, or tooling skill.
+Diagnose and fix from evidence; route prevention to product, architecture, development, testing, release or tooling.
+
+- Code/test changes require self-checks; invoke `code-review` automatically before completion.
 
 ## Non-Negotiable Rules
 

package/dist/assets/marketplace/plugins/ccl-skills/skills/go-microservice-dev/SKILL.md

@@ -5,7 +5,7 @@ description: Use when implementing, modifying, scaffolding, generating, or testi
 
 # Go Microservice Dev
 
-Use this for implementation of new backend products and services. It should adapt to the repo in front of you, but the workflow is independent of any prior codebase.
+Use this for implementation of new backend products and services. It should adapt to the repo in front of you, but the workflow is independent of any prior codebase. After code/test edits, self-check and invoke `code-review` automatically before completion.
 
 ## Skill Routing
 

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

@@ -7,6 +7,8 @@ description: Use when designing, implementing, reviewing, debugging, or operatin
 
 Use this for product backend work that calls, hosts, evaluates, or operates LLM and inference systems. Keep the skill generic: extract reusable mechanics only, not business-specific prompts, datasets, provider names, repository paths, or domain nouns.
 
+- Code/test changes require self-checks; invoke `code-review` automatically before completion.
+
 ## Skill Routing
 
 - Use this skill for LLM gateway/client design, model registry, prompt versioning, agent/tool orchestration, streaming APIs, fallback, token/cost accounting, evals, replay, shadow comparison, batch inference, and inference observability.

package/dist/assets/marketplace/plugins/ccl-skills/skills/miniapp-product-dev/SKILL.md

@@ -5,7 +5,7 @@ description: "小程序 / Taro / 微信小程序 / 支付宝小程序 / 抖音
 
 # Miniapp Product Dev
 
-Use this skill for mini-program client engineering and platform delivery. It covers product-facing miniapp work across WeChat, Alipay, Douyin/TikTok, Baidu, and similar host platforms. It does not own general product strategy, backend service architecture, or visual design rules.
+Mini-program client engineering and product-facing delivery across WeChat, Alipay, Douyin/TikTok, Baidu and similar hosts; excludes product strategy, backend architecture and visual design. After code/test edits, self-check and invoke `code-review` automatically before completion.
 
 ## Framework Scope
 

package/dist/assets/marketplace/plugins/ccl-skills/skills/multi-agent-delegation/SKILL.md

@@ -57,7 +57,7 @@ This skill is about **using AI agents / subagents to execute work** — delegati
   5. **Value**: the task is worth that premium.
   If independence, value, or breadth is unclear, start with one focused agent or sequential delegation; use parallel multi-agent dispatch when those checks are explicitly satisfied.
 - Model tier per dispatch is an explicit decision, not an inherited accident. On hosts that inherit the session model for unnamed dispatches (a common default — Claude-family harnesses behave this way; verify yours), an unnamed model is often the most capable and most expensive tier, so a high-volume fan-out silently puts every worker and reviewer on the top tier. The observable triggers are a fan-out — multiple dispatches (workers/reviewers) in one delivery — and any high-risk dispatch: there, name the tier per dispatch and choose by judgment complexity and risk, not token price alone — the cheapest tier routinely takes 2–3× the turns on multi-step work and costs more overall, so use a mid-tier floor for reviewers and for implementers working from prose descriptions; reserve the cheapest tier for transcription-plus-tests tasks (the plan text already contains the code to write) and single-file mechanical fixes; put architecture/design judgment, security/authority/tenant-isolation/data-loss review, and the final whole-scope review on the most capable tier — review tier scales with the diff's size, complexity, and risk, and a high-risk review never silently inherits a cheap session default even as a single dispatch (tier principle: `../skill-extraction-workflow/references/harness-patterns-and-eval.md`). Record the decision as a brief field alongside `required_skills`: `model_tier: <tier>` or `model_tier: host-default (<reason: single low-risk dispatch | no host model selection>)` — an absent field is an unmade decision, not a default, and the field is bookkeeping only until the dispatch call actually passes the matching model selector (verify the effective model where the host exposes it; a field/selector mismatch is a defect, not a recorded decision).
-- Stop and escalate when the plan is unclear, a dependency is missing, verification fails repeatedly (same error ~3 times — identical retries, not new findings from successive review rounds), or an agent returns unsupported claims. An escalation message must carry five fields, or it is just "stuck": the specific blocker, the attempts made and their results, the current state (diff / commits / workspace), the safest next action for the human to align on, and whether a lower-risk part can continue meanwhile.
+- Stop and escalate when unclear direction, unavailable dependencies, unknown completion state or missing authority remains after bounded remediation. Repeated identical verification failures (~3 times) require a status report and method/evidence checkpoint, not renewed task permission; stop identical retries and continue necessary work within existing scope, respecting explicit user limits. Escalation must name the blocker, attempts and results, current diff/commits/workspace, safest next action, and lower-risk work that can continue.
 
 ## Execution Flow
 

package/dist/assets/marketplace/plugins/ccl-skills/skills/nodejs-service-dev/SKILL.md

@@ -5,6 +5,8 @@ description: Use when implementing, modifying, scaffolding, or testing Node.js b
 
 # Node.js Service Development
 
+- Code/test changes require self-checks; invoke `code-review` automatically before completion.
+
 ## Skill Routing
 
 - Use this skill for Node.js service implementation: handlers, middleware, adapters, workers, jobs, clients, runtime/toolchain mechanics, and focused tests.

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

@@ -5,7 +5,9 @@ description: Use when designing, reviewing, debugging, or shipping observability
 
 # Platform Observability
 
-This skill owns the **evidence layer**: logs, metrics, traces, log/trace correlation, dashboards, alerts, on-call routing, SLI/SLO/error-budget design, and the framework-level wiring that guarantees a new service is observable on day one.
+Owns logs/metrics/traces, correlation, dashboards, alerts, on-call routing, SLI/SLO/error-budget design and framework wiring for new services.
+
+- Code/test changes require self-checks; invoke `code-review` automatically before completion.
 
 You do not own:
 - Traffic routing, retries, timeouts, mTLS, or service mesh policy — go to `platform-service-connectivity`.
@@ -30,7 +32,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 +108,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 +210,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-release-engineering/SKILL.md

@@ -5,7 +5,9 @@ description: 发布 / 灰度 / canary / rollback / rollout / 环境泳道 / prom
 
 # Platform Release Engineering
 
-This skill owns **how a change reaches users and how it gets recalled**: lane / environment topology, build-to-deploy pipeline, traffic-shifting strategies (canary, blue-green, mirror), promotion gates that consume observability evidence, secret + dynamic-config distribution, and the rollback contract.
+Owns lane/environment topology, build/deploy pipelines, traffic shifting (canary, blue-green, mirror), promotion gates using observability evidence, secret/dynamic-config distribution and rollback contracts.
+
+- Code/test changes require self-checks; invoke `code-review` automatically before completion.
 
 You do not own:
 - What signals exist to judge a release — see `platform-observability`.

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

@@ -5,6 +5,8 @@ description: 服务互通 / service mesh / service discovery / mTLS / retry / ti
 
 # Platform Service Connectivity
 
+- Code/test changes require self-checks; invoke `code-review` automatically before completion.
+
 This skill owns **how requests move between services**: the transport layer (mesh), service discovery, multi-environment routing, retry/timeout/circuit-breaker policy, and the framework middleware that propagates app-level context across hops.
 
 You do not own:
@@ -100,10 +102,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 +154,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 +202,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 +218,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 +236,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 +259,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 +271,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 |
 

package/dist/assets/marketplace/plugins/ccl-skills/skills/platform-service-connectivity/references/grpc-authority-workaround.md

@@ -1,90 +1,47 @@
-# gRPC `:authority` and DNS-Label Hyphenation
-
-## The quirk
-
-HTTP/2's `:authority` pseudo-header (which carries the host of a gRPC request) is parsed strictly. RFC 1035 says DNS labels can contain letters, digits, and hyphens — but NOT underscores.
-
-Many platforms use PSM-style service names like `<owner>.<class>.<env>`. When any segment contains underscores (e.g. an env segment named `prod_v2` or a feature-flagged variant `payments.ledger.prod_2024`), the SDK puts that name into `:authority`. Envoy / strict gRPC implementations reject the request:
-
-```
-RST_STREAM with INTERNAL_ERROR
-```
-
-You lose the connection on every call. Frustrating to debug because it looks like network failure.
-
-## Two fixes
-
-### Fix 1 (clean, long-term): forbid underscores in service names
-
-- Naming policy: service name = lowercase, dot-separated segments, hyphens within segments allowed, underscores forbidden.
-- Enforce at registry registration (reject the registration).
-- Enforce at CI / lint when defining new services.
-- Migrate existing names by renaming + parallel registration during a deprecation window.
-
-### Fix 2 (live-system workaround): mesh-level rewrite
-
-When you can't break existing names, an Envoy Lua filter rewrites `:authority` on the fly:
-
-```yaml
-apiVersion: networking.istio.io/v1alpha3
-kind: EnvoyFilter
-metadata:
-  name: modify-grpc-authority
-  namespace: istio-system
-spec:
-  configPatches:
-    - applyTo: HTTP_FILTER
-      match:
-        context: ANY
-        listener:
-          filterChain:
-            filter:
-              name: "envoy.filters.network.http_connection_manager"
-      patch:
-        operation: INSERT_BEFORE
-        value:
-          name: envoy.filters.http.lua
-          typed_config:
-            "@type": type.googleapis.com/envoy.extensions.filters.http.lua.v3.Lua
-            inlineCode: |
-              function envoy_on_request(request_handle)
-                local authority = request_handle:headers():get(":authority")
-                local content_type = request_handle:headers():get("content-type")
-                if authority and content_type and string.find(content_type, "application/grpc") then
-                  local modified_authority = string.gsub(authority, "_", "-")
-                  request_handle:headers():replace(":authority", modified_authority)
-                end
-              end
-```
-
-Effects:
-- Applies to gRPC traffic only (content-type check).
-- Rewrites `_` to `-` in `:authority`.
-- Callee's registry instance name must also use the `-` form so routing matches.
-
-## When to use which
-
-| Situation | Fix |
+# gRPC Authority Compatibility
+
+## Separate the names and constraints
+
+HTTP/2 `:authority` conveys the target URI's authority, as defined by [RFC 9113 §8.3.1](https://www.rfc-editor.org/rfc/rfc9113.html#section-8.3.1). [RFC 3986 §3.2.2](https://www.rfc-editor.org/rfc/rfc3986.html#section-3.2.2) permits a registered name containing unreserved characters, including `_`. This syntax does not guarantee DNS resolution, certificate identity matching, or acceptance by every SDK and proxy version.
+
+Keep these values distinct when diagnosing a request:
+
+- Service-registry identifier and resolved network endpoint.
+- HTTP/2 authority used for virtual-host routing.
+- TLS server name and the certificate identity expected on each TLS hop.
+- Platform naming, routing, and authorization policies.
+
+A platform can require DNS-compatible service names and enforce that choice at registration and CI. Existing identifiers do not require migration merely because they contain an underscore; first establish which constraint the actual path violates.
+
+## Locate the rejection before choosing a fix
+
+Record the runtime/SDK, proxy versions and relevant configuration, exact authority, and the failing run's error or trace. Use a synthetic payload and redact credentials from captured evidence.
+
+| Observed boundary | Next action |
 |---|---|
-| Greenfield platform | Fix 1 — naming policy from day one |
-| Mature platform, many existing names | Fix 2 — buy time, then schedule Fix 1 migration |
-| Mixed HTTP + gRPC for same service | Fix 2 — HTTP tolerates `_`, gRPC doesn't; rewrite only at gRPC layer |
-| Service-mesh-less (direct gRPC) | Fix 1 only — no Envoy to rewrite |
+| Authority syntax is malformed | Validate URI authority syntax, including brackets around an IPv6 literal, before changing service registration or routing. |
+| Client rejects before transmitting HTTP/2 headers | Check that client's authority validation and supported configuration. Fix the client-side mapping or naming contract; a downstream proxy cannot rewrite a request it never receives. |
+| DNS resolution fails | Check the resolved hostname and resolver's naming rules. Changing a later HTTP header does not repair failed resolution. |
+| TLS handshake or certificate identity check fails | Check that hop's endpoint, server name, trust chain, and certificate identities. Retain verification; changing authority is not evidence that TLS is fixed. |
+| Proxy/parser rejects before the HTTP filter runs | Fix the supported parser/input contract or an earlier owned mapping. A Lua filter after the rejection cannot intervene. |
+| Request reaches HTTP filters, then the intended virtual-host route does not match | Compare the received authority with the generated route configuration. A supported authority mapping may be appropriate after proving the mismatch. |
+| Existing path accepts the name and reaches the intended service | Preserve it unless a separate platform naming-policy migration is required. |
 
-## Verification
+`RST_STREAM` or `INTERNAL_ERROR` alone does not identify an underscore problem. Confirm the first rejecting layer rather than treating every transport failure as the same naming defect.
 
-Fix 1:
-- Registry rejects registration with `_` in name.
-- Linter / CI rejects PR adding such a name.
+## Choose a bounded compatibility change
 
-Fix 2:
-- Synthetic gRPC call to `<svc>_<env>` → inspect Envoy access log `:authority` field → expect `<svc>-<env>`.
-- Callee's access log `host` shows the rewritten form.
+**Naming policy or client mapping.** Where a DNS-compatible name is required, define the allowed form and the mapping from registry identity to endpoint/authority. Check uniqueness before migration: replacing `_` with `-` can collapse two distinct names. Migrate registrations, routes, and callers together with a compatibility window and rollback path. Use supported client options; do not bypass certificate or authorization checks to make a name work.
+
+**Proxy mapping.** Use only if the request reaches the chosen filter and the mapping addresses a reproduced failure. Prefer the platform's supported routing mechanism. If an EnvoyFilter is necessary, verify the installed Istio/Envoy API and generated configuration, and scope it to the affected workloads, listener/direction, route, and explicit old-to-new authority mapping. Do not install an all-workload, all-direction underscore replacement. The mapping must preserve the intended destination, tenant/lane routing, authorization, and TLS identity on each hop; rewriting a header does not itself update those contracts.
+
+## Verification
 
-## Common variants of the same bug
+Retain the original failing case and expected rejecting layer. After the change, verify:
 
-- HTTP/2 SETTINGS frame rejection on cert SAN mismatch (separate issue, but presents similarly — RST_STREAM with INTERNAL_ERROR).
-- gRPC `:scheme` set to `http` while upstream expects `https` (mTLS mismatch).
-- IPv6 literal in `:authority` not bracketed.
+1. The same request succeeds through the intended path and reaches the intended service; observe authority before/after any mapping and the selected route.
+2. Unrelated authorities and non-target traffic retain their behavior. Include potentially colliding names and unknown authorities as negative controls.
+3. Certificate identity and authorization failures still reject requests; the compatibility change has not disabled those checks.
+4. Registration/client/route changes can be rolled back together without sending traffic to another service.
 
-The Lua rewrite filter is the right tool for the underscore case; do not generalize it to all of the above. Each bug has its own fix.
+Static configuration validation proves only configuration properties. Claims about a deployed SDK/proxy path require execution evidence from that path.

package/dist/assets/marketplace/plugins/ccl-skills/skills/platform-service-connectivity/references/mesh-architecture.md

@@ -33,7 +33,7 @@ Reference topology and component rules. Istio is the recurring example; rules ge
 
 ## Istio Ambient Mode (GA Nov 2024, v1.24+)
 
-- **Istio Ambient Mode reached General Availability in Istio v1.24 (announced November 2024)** per `istio.io/latest/blog/2024/ambient-reaches-ga/` — `ztunnel` + `waypoint` architecture is the stable sidecar alternative for new production mesh deployments. **Two-layer split**: `ztunnel` (Rust-based DaemonSet, one per node, L4-only — mTLS + simple L4 authz + telemetry) handles every pod's transport-layer mesh participation without per-pod sidecar injection; `waypoint` proxies (Envoy-based, scaled independently from app workloads) handle L7 features when needed (rich authz, traffic routing, resilience). Per Istio's own reported numbers, the architecture can save 90%+ memory/CPU vs the sidecar model in dense-pod-per-node workloads (Istio's claim — re-measure on the team's actual workload before quoting savings). **Architecture choice for new mesh**: (a) **choose ambient** when memory/CPU per pod is the binding constraint, sidecar injection causes restart cycles the team wants to avoid, or a subset of namespaces don't need L7 features at all; (b) **stay on sidecar mode** when the team has deep sidecar-specific tooling (custom `EnvoyFilter`s injected per pod, sidecar-aware debugging recipes, app code that expects `localhost:15001` proxy conventions), or when ambient's narrower L7-feature coverage hits a gap the team relies on. **Mixed-mode in one cluster is officially supported** per the Istio docs: sidecar-mode namespaces and ambient-mode namespaces coexist; migration can be incremental namespace-by-namespace. **CRITICAL migration block: AuthorizationPolicy enforcement loss when flipping a namespace from sidecar to ambient without waypoint** — sidecar mode enforces full L7 `AuthorizationPolicy` rules (HTTP method, path, header, JWT claims) at the per-pod proxy. In ambient mode, ztunnel alone enforces only L4-level policy (workload identity, port); any L7-condition rule (`request.method`, `request.headers[...]`, `request.path`, `request.auth.claims[...]`) silently DOES NOT MATCH on ambient-mode pods until a waypoint proxy is deployed for the namespace/service and the policy is targeted at the waypoint. The failure shape: team flips `istio.io/dataplane-mode=ambient` label, sidecar comes down, ztunnel takes over L4, and every L7 authz policy stops gating traffic — without a visible error, because L4 policy still works. **Pre-flip gate**: inventory every `AuthorizationPolicy` targeting workloads in the namespace, identify the ones using L7 conditions, ensure a waypoint is deployed and the policy `targetRefs` is set to the waypoint (not the workload) BEFORE flipping the namespace label. Validate by re-running the authz integration tests against the ambient-mode namespace before completing the migration. **Observability shift**: ztunnel emits L4 metrics; waypoint emits L7 metrics; existing dashboards keyed on sidecar `istio_requests_total` need a ambient-mode equivalent for the L7-routed traffic — route this update through `platform-observability` rather than redesigning here.
+- **Istio Ambient Mode reached General Availability in Istio v1.24 (announced November 2024)** per `istio.io/latest/blog/2024/ambient-reaches-ga/` — `ztunnel` + `waypoint` architecture is the stable sidecar alternative for new production mesh deployments. **Two-layer split**: `ztunnel` (Rust-based DaemonSet, one per node, L4-only — mTLS + simple L4 authz + telemetry) handles every pod's transport-layer mesh participation without per-pod sidecar injection; `waypoint` proxies (Envoy-based, scaled independently from app workloads) handle L7 features when needed (rich authz, traffic routing, resilience). Per Istio's own reported numbers, the architecture can save 90%+ memory/CPU vs the sidecar model in dense-pod-per-node workloads (Istio's claim — re-measure on the team's actual workload before quoting savings). **Architecture choice for new mesh**: (a) **choose ambient** when memory/CPU per pod is the binding constraint, sidecar injection causes restart cycles the team wants to avoid, or a subset of namespaces don't need L7 features at all; (b) **stay on sidecar mode** when the team has deep sidecar-specific tooling (custom `EnvoyFilter`s injected per pod, sidecar-aware debugging recipes, app code that expects `localhost:15001` proxy conventions), or when ambient's narrower L7-feature coverage hits a gap the team relies on. **Mixed-mode in one cluster is officially supported** per the Istio docs: sidecar-mode namespaces and ambient-mode namespaces coexist; migration can be incremental namespace-by-namespace. **CRITICAL migration block: L7 policy enforcement changes when moving from sidecar to ambient.** Ztunnel enforces only L4 policy. A workload-selector policy containing L7 conditions that is picked up by ztunnel [fails safe as a DENY policy](https://istio.io/latest/docs/ambient/usage/l4-policy/#policies-with-layer-7-conditions), potentially blocking legitimate traffic. L7 enforcement requires a waypoint and `targetRefs` bound to the intended Service or waypoint Gateway; deploying a waypoint alone does not migrate selector-based policies. **Pre-flip gate**: inventory affected authorization policies, prepare the waypoint and correctly scoped bindings, and plan the old-policy/pod-restart transition using the deployed version's [migration guide](https://istio.io/latest/docs/ambient/migrate/migrate-policies/). Preserve mTLS and L4 authorization; do not remove a rejecting policy merely to restore connectivity. Verify allowed, denied, and waypoint-bypass paths before completing migration. If the transition cannot maintain required L7 protection, hold migration or use an approved maintenance window. **Observability shift**: ztunnel emits L4 metrics; waypoint emits L7 metrics; existing dashboards keyed on sidecar `istio_requests_total` need a ambient-mode equivalent for the L7-routed traffic — route this update through `platform-observability` rather than redesigning here.
 
 ## Sidecar injection rules
 
@@ -94,7 +94,7 @@ Egress gateway is OFF by default. Turn ON only when a workload needs controlled
 EnvoyFilter is the escape hatch. Use sparingly; each filter is hard to test and easy to break across Envoy upgrades.
 
 Acceptable uses:
-- Header rewrite for protocol quirks (e.g. gRPC `:authority` hyphenation — see `grpc-authority-workaround.md`).
+- Header mapping for a reproduced compatibility failure, scoped to the affected workloads and explicit names while preserving routing, TLS, and authorization (see `grpc-authority-workaround.md`).
 - Adding a Lua filter for one-off business handling that doesn't yet have a first-class WASM filter.
 - Custom rate-limit before the canonical RLS is rolled out.