@ccoalm/ccl-skills 0.1.0

package/dist/assets/marketplace/plugins/ccl-skills/skills/platform-release-engineering/references/secret-and-config-management.md

@@ -0,0 +1,231 @@
+# Secret and Config Management
+
+Three tiers, three lifecycles. Mixing them up is a recurring source of outages and leaks.
+
+## The three tiers
+
+### Static config
+
+What it is: values that change only when the application changes. Defaults, feature definitions, hardcoded behavior switches that no operator should flip without a code review.
+
+How it ships: bundled into the image, in a known path (`conf/<env>.yml` or `config/default.yml`). Per-env split is acceptable (`conf/prod.yml`, `conf/test.yml`) but only for values that legitimately differ per env (DB hostnames, queue cluster names).
+
+Updates: require a code change + deploy.
+
+Examples:
+- DB connection pool sizes.
+- Default timeouts.
+- Feature definitions ("there is a feature called X").
+
+### Dynamic config (config center)
+
+What it is: values an operator can flip at runtime without redeploy. Feature flags, rate limits, A/B test variants, kill switches.
+
+How it ships: through a config center (Apollo, etcd KV, Consul KV, internal dcc-style service). Application SDK subscribes, caches locally, receives push updates.
+
+Updates: configurable via API / UI; audit-logged like deploys.
+
+Examples:
+- `feature_X_enabled = true | false`.
+- `rate_limit_per_user = 100/s`.
+- `experiment_split = { control: 50, variant_a: 25, variant_b: 25 }`.
+- Kill switch for a degraded-mode path.
+
+### Secrets
+
+What it is: credentials, tokens, certs. Any value that, if leaked, causes a security incident.
+
+How it ships: via a secret store (cloud KMS, Vault, internal secret manager). Injected into pods at start (init container, sidecar, or projected volume). Never committed to git, never in a regular ConfigMap.
+
+Updates: rotation pipeline. Old value remains valid for a grace window during cutover.
+
+Examples:
+- DB password.
+- Third-party API key.
+- TLS cert + private key.
+- OAuth client secret.
+
+## Tier selection rules
+
+| Need to flip without redeploy? | yes → dynamic config |
+| Sensitive to leak? | yes → secret store |
+| Both? | secret-aware dynamic config (some platforms support encrypted KV with audit) |
+| Neither? | static config |
+
+If you find a feature flag in static YAML, move it to dynamic. If you find a password in dynamic config, move it to a secret store.
+
+## Static config patterns
+
+```
+service/
+  conf/
+    default.yml          ← shared defaults
+    prod.yml             ← prod overrides (no secrets)
+    pre.yml
+    test.yml
+    dev.yml
+```
+
+Load order: default → env-specific. Application reads `env.Lane()` or equivalent to pick the file.
+
+If two envs share most config, factor shared values into `default.yml` and let env files override only what differs.
+
+## Dynamic config (config center) shape
+
+Client SDK contract:
+
+```go
+val, ok := dcc.GetString("rate_limit.user_per_second")
+flag := dcc.GetBool("feature.checkout_v2.enabled")
+dcc.Watch("kill_switch.payment", func(newVal interface{}) {
+    // react to flip
+})
+```
+
+Server-side:
+- Pushed to clients via long-poll or websocket.
+- Updates are atomic per key.
+- Versioning: each update has a version number; clients track their last-applied version.
+- Rollout: a value can be staged (visible to canary lane only) before promotion.
+
+Operator-facing:
+- UI with audit log: who flipped what, when, why.
+- Diff and dry-run: preview which clients would receive a change.
+
+## Secret store patterns
+
+### Pattern A — Cloud-provider KMS / Secrets Manager
+
+AWS Secrets Manager, GCP Secret Manager, equivalent. Service reads via SDK with IAM role. No file on disk.
+
+```
+appCode → cloud SDK → KMS → secret value
+```
+
+Pros: managed, audited, integrated with cloud IAM.
+Cons: cloud-coupling; cross-cloud is painful.
+
+### Pattern B — Self-hosted Vault
+
+HashiCorp Vault deployed in-cluster. Apps authenticate via k8s ServiceAccount JWT and request secrets.
+
+Pros: cloud-neutral, fine-grained policy, dynamic secrets (e.g. short-lived DB credentials).
+Cons: you operate Vault.
+
+### Pattern C — Internal KMS
+
+A platform-team-written service that brokers between cloud KMS, k8s ServiceAccount, and pods. Hides cloud specifics; exposes a uniform API.
+
+Pros: customization, integration with internal RBAC.
+Cons: you own the implementation — and the bar for a production KMS is high. Most internal KMS implementations are dangerously incomplete on day one.
+
+**Required for an internal KMS to be production-grade** (not "an encrypted key-value store"):
+
+- **Envelope encryption with DEK / KEK separation**: data is encrypted by a per-object data encryption key (DEK); the DEK itself is encrypted by a long-lived key encryption key (KEK). The KEK never appears in plaintext outside the trust root (HSM, cloud-provider KMS, or a sealed enclave). DEKs are short-lived and per-object.
+- **AEAD ciphers only**: AES-GCM, ChaCha20-Poly1305, or equivalent. AES-CBC + PKCS#7 padding without an authentication tag is a finding — silently accepts tampered ciphertext.
+- **KEK is never in application memory as a literal**: not a base64 string in code, not in `.env`, not in a config-center value. Acceptable sources: HSM (PKCS#11 / cloud HSM), cloud-provider KMS root, sealed enclave. If the application process can dump its own memory and recover the KEK, the design is broken.
+- **Key versioning**: every encrypt records the KEK version used; decrypt reads the version and resolves the right KEK. Without versioning, rotation is impossible.
+- **Key rotation is operational, not aspirational**: scheduled (cadence per policy, typically 90 days for KEK, faster for DEK), automated, with a re-wrap pipeline for existing ciphertexts and a deprecation horizon for the old version. "We support rotation in principle but never run it" is the same as no rotation.
+- **Audit log per operation**: every encrypt / decrypt / rotate / disable records caller identity (workload identity, not just IP), key id, key version, operation, timestamp, request id. The audit log is append-only and stored separately from the KMS service itself. A KMS without an audit trail cannot meet any compliance bar.
+- **Per-key authorization (ACL)**: not every caller can use every key. The KMS enforces caller-x-key allowlist, not "anyone in the cluster can decrypt anything".
+- **Backing store is durable + encrypted at rest**: a real database or object store with per-row/per-object encryption, not a config center treated as a key-value cache. Storing ciphertext in a config center conflates "fast read" with "durable encrypted store" — wrong layer.
+- **DR for the KEK**: secure backup, multi-region replication, or sealed split-shares (Shamir or equivalent). Losing the KEK loses all data forever; "we'll add this later" is not acceptable.
+
+**Anti-pattern guardrails** (commonly observed in early-stage internal KMS):
+
+- KEK as base64 literal in source / env / committed config → equivalent to plaintext.
+- AES-CBC + PKCS#7 without HMAC / GCM → silently accepts tampered ciphertext.
+- "Encryption" implemented as `xxx_encrypt(value)` writing to a config center under a regular key name → there is no envelope, no DEK, no key version, no audit; it is a config rename.
+- K8s ServiceAccount TokenReview as the only authorization → any pod in the cluster (or any compromised pod) can decrypt anything; missing per-key ACL.
+- No rotation → first KEK in production is the KEK forever; if it ever leaks, every byte ever encrypted is exposed.
+- No audit log → no way to answer "who decrypted X on date Y" during an incident.
+- Ciphertext stored in a config center as an ordinary key/value → DR / encryption-at-rest / backup story collapses to the config center's story, which usually does not meet KMS bars.
+
+When the project is not ready to meet these bars, do not build "Internal KMS Pattern C" — use Pattern A (cloud-provider KMS) or Pattern B (self-hosted Vault) until the team has bandwidth to own a real KMS.
+
+### Pattern C-adjacent — Cloud Session Token Brokering
+
+Distinct from Pattern C (which encrypts data): a service that mints short-lived cloud-provider credentials (STS, OIDC, IAM session tokens) on behalf of pods and caches them. Common when the platform calls multiple cloud accounts or multiple roles per account.
+
+- **Caller authentication and authorization MUST gate every mint**: the broker is a privilege-escalation surface — it holds credentials more powerful than any individual pod and hands them out. Before minting, the broker verifies the caller's workload identity (mTLS service identity, k8s SA TokenReview, SPIFFE/SPIRE id, or platform-issued JWT) AND checks an explicit caller × target-account × target-role × scope allowlist. "Any pod in the cluster can ask for any role" is a finding; the allowlist is data-driven and reviewed.
+- **Cache key covers the full effective credential scope**, not just account+role: the cache key is `(caller_identity, account_id, role_arn, session_policy_hash, source_identity, external_id, session_tags_hash, transitive_tag_keys_hash, region, scope_hint, requested_duration)`. Every input that the cloud provider treats as credential-shaping — session policy, source identity, ABAC session tags (including which are marked transitive), external id, region — is included; omitting session-tag fields lets one caller receive credentials minted with another caller's ABAC tags, which collapses tenant / resource boundaries. A `(account_id, role_arn)`-only key leaks one caller's restricted session into another's broader request.
+- **Refresh-ahead-of-expiry**: short-lived credentials (typically 15-60 minutes) refresh at `expiry - safety_buffer`. The buffer is typically 1 minute, but clock skew between the broker and the cloud provider's STS endpoint can make the broker's view of "expiry" wrong. Validate clock skew (NTP-derived or via the cloud provider's response timestamp header) and treat any skew > buffer as cause to refresh immediately.
+- **Refresh is single-flight per cache key**: under load, all in-flight callers wait for one refresh, not N parallel refreshes against STS.
+- **Failure to refresh fails closed, not silently serves stale**: STS / AssumeRole errors do not produce empty tokens; cached-and-now-expired tokens do not silently extend.
+- **Audit token issuance**: every mint records caller (verified workload identity, not claimed), target account / role, requested scope / session policy, expiry granted, request id. Token leakage investigation requires the audit log.
+
+### Pattern D — Sealed / external secret operators
+
+For GitOps shops: `Sealed Secrets` (Bitnami) or `External Secrets Operator` reads from a secret store and creates k8s `Secret` objects.
+
+Pros: declarative; integrates with Argo CD.
+Cons: still need a real secret store behind it.
+
+## Injection paths
+
+Pod gets the secret via:
+
+1. **Init container**: pulls from secret store, writes to a shared volume, app reads at start. Simple, works for any language.
+2. **Sidecar**: continuously syncs secrets to the volume; supports rotation without restart.
+3. **CSI driver**: k8s native; mounts secrets as files.
+4. **Env vars from k8s Secret**: simplest but rotates only on pod restart and leaks via `/proc/<pid>/environ`.
+5. **SDK fetches at runtime**: most flexible; requires the secret store SDK in the app.
+
+Choose by rotation needs and language ecosystem.
+
+## Rotation
+
+Every secret has an expiry. Rotation pipeline:
+
+```
+1. Generate new secret at source (DB user new password; new API key).
+2. Push new secret to secret store as a new version, marked "pending".
+3. Trigger app reload (or wait for next rotation poll).
+4. Confirm apps read new secret (metric: secret_version_in_use).
+5. Mark new version "active"; mark old version "deprecated".
+6. After grace window, revoke old secret at source.
+```
+
+Grace window: 24h - 7d depending on app traffic patterns. Long enough that all replicas pick up the new value.
+
+### Webhook / HMAC verifier rotation
+
+A subset of "secrets" — the shared secrets used to verify inbound webhook / callback signatures (chat-platform approval cards, OAuth provider callbacks, partner webhooks, internal control-plane callbacks) — has rotation requirements that the generic secret-rotation pipeline above does not fully cover. Apply these rules in addition to the generic pipeline:
+
+- **Dual-verifier acceptance during cutover**: during the rotation grace window the verifier accepts both the active and the deprecated secret. Closing the grace window before all senders cut over is the most common rotation outage; the grace must be longer than the longest sender propagation path the platform commits to.
+- **Key id in the signed payload (when the protocol allows)**: senders include a `kid` / `key_version` header so the verifier picks the right secret directly rather than try-all. When the protocol does not allow a key id (some chat-platform card callbacks), the verifier tries active first, then deprecated; never beyond that.
+- **Constant-time comparison**: signature comparison is constant-time (`hmac.Equal`, `crypto.subtle.timingSafeEqual`). String `==` on the signature is a finding.
+- **Provider cutover order**: rotate the verifier (accept new + old) BEFORE the sender starts emitting under the new secret. Senders cutting before verifiers leaves a window where valid inbound callbacks fail signature, and operators reach for the override.
+- **Hard reject after revocation**: a secret moved to "revoked" (not just "deprecated") must fail verification immediately and loudly, including for already-signed-and-delayed payloads. Revoked-but-still-accepted is the bypass an attacker uses after leak.
+- **Audit per verification outcome** for the rotation window: which secret version succeeded, sender id, request id. Sustained verification against the deprecated secret after the planned cutover date is the early warning that a sender did not rotate.
+
+### Ephemeral bootstrap / pairing credentials on observable channels
+
+Some credentials must transit a channel you cannot redact or keep private: a value printed to a system/console log, a CI build log, a device-flow user code, a QR pairing code, a one-time provisioning URL, or any handoff where the producer and consumer are reached through an observable medium. For these, "do not log the secret" and the reactive "rotate immediately if discovered" below are not enough — the exposure is *by design*, so leak-driven rotation never fires. Make the value worthless to whoever captures the channel:
+
+- **Born single-use and short-lived, invalidated on first legitimate use.** The credential carries a risk-appropriate expiry — seconds for a machine-to-machine in-process bootstrap (a token printed to a launch log and redeemed by a local daemon), minute-scale where a human must read and enter it across devices (a device-flow user code or QR pairing code, where RFC 8628-style flows leave the exact lifetime deployment-specific but bounded) — and is consumed on first successful exchange, so the copy sitting in the log/screen/history is already dead. Design the bootstrap so the long-lived authority (session token, refreshable credential) is minted *in exchange for* the ephemeral one over a private channel, never logged.
+- **Exchange it for a private-channel credential immediately; never reuse the bootstrap value as the working credential.** The observable value's only job is to authenticate one handoff; after that the parties talk over a credential that never touched the observable channel. Rotating the bootstrap value "within seconds of boot" so anything scraping the launch log past that point sees a dead credential is the canonical shape.
+- **The observable value alone must not be sufficient to mint authority — redemption is not "first claimant wins".** A captured value can be redeemed by an attacker *before* the legitimate consumer (RFC 8628 §5.5 calls out this hijack: complete the flow faster than the initiating party); single-use + rate-limit + audit then only record the breach *after* a usable credential was issued to the wrong party. So redemption must require a second proof the attacker cannot obtain from the observable channel: a pre-established device/public key, mTLS/SPIFFE identity, local-IPC peer credential, or a session id that never appears on the observable channel — verified *before* minting, with an atomic single-use compare-and-swap so concurrent redemptions cannot both win. Foreign or unproven redemption must fail closed (mint nothing) and, for high-risk flows, revoke the value and alert. When no prior private proof exists (a QR or device-flow code a human scans), require user-visible device/possession confirmation; the observable code by itself never issues the working credential. Scope the value to a single generation so it cannot be replayed against a later incarnation (same single-use + generation-binding discipline as `llm-inference-integration`'s approval tokens; this is the secret-design counterpart).
+- **Rate-limit and audit the redemption endpoint.** The endpoint that exchanges the ephemeral value is a brute-force and replay target: bound redemption attempts per identity/window, and audit each redemption (who, when, outcome) so an anomalous replay after the legitimate exchange is visible.
+- **Treat "the channel is internal/loopback/short-lived" as defense-in-depth, not the boundary.** A log that is local today is shipped to a log aggregator tomorrow; a loopback-only console is captured by a crash report or a screen recording. The ephemerality of the value, not the assumed privacy of the channel, is what makes the exposure safe.
+
+## What MUST NOT be in git
+
+- Committed `.env` files.
+- Plaintext passwords in any YAML.
+- API keys in test fixtures (use fake values).
+- Private keys in any form.
+- OAuth client secrets.
+- Cookie / JWT signing keys.
+
+Run a secrets-in-git scanner (`gitleaks`, `trufflehog`, GitHub secret scanning, equivalent) on every PR. Reject merge if hit.
+
+A leaked secret in git history persists until force-push and even then is recoverable. Rotate immediately if discovered.
+
+## Verification
+
+- A new service can pull DB password from secret store on cold start; no password in image.
+- Flipping a feature flag in config center takes effect within seconds (subscription) or single refresh cycle (poll).
+- Static config changes require a code review + deploy; bypass attempts are audited.
+- Rotation pipeline runs without service outage; metric shows version transition.
+- Secrets scanner runs on every PR; new credential commit is rejected.

package/dist/assets/marketplace/plugins/ccl-skills/skills/platform-release-engineering/references/version-authority-and-deprecation.md

@@ -0,0 +1,21 @@
+# Version authority and deprecation timing
+
+The two cross-repo version decision-cliffs the `## Decision Points` one-liners
+route here. `product-rd-workflow`'s spec/repo-contract sync gate cross-refs this;
+this skill owns the layered version model and the rollout-timing decision.
+
+## "Where the version number lives across repos" (version-authority layering)
+
+Version management is layered, each layer one owner + one change-mode: contract version (tag — immutable, accumulate) → version combination (manifest — current-state, update-in-place) → consumer pin (dependency declaration — current-state) → repo-local **agent contract** (`AGENTS.md`: version-independent rules + a pointer to the authority; **must not copy the authoritative current pin**, which drifts on the next bump).
+
+Exception (narrow): **non-normative historical artifacts** (audit / release-note) and **generated artifacts with a checked generation source** MAY inline a version, labeled `generated/as-of <authority> @ <ref/date>` with owner + refresh/generation path; but if anything consumes the artifact for a **current** decision it must resolve the authority at use-time or pass a freshness gate (source ref + generation command + owner + max-age/refresh + CI check). The exception is not a license to copy the current pin into any doc and call it a snapshot. `product-rd-workflow`'s spec/repo-contract sync gate cross-refs this.
+
+**Current-state layers need a standing drift check, not same-batch discipline.** The `update-in-place` layers above (the combination manifest and consumer pins) and any agent/human status doc that restates them are the only layers that *drift* — immutable tags do not. "Update it in the same delivery batch" is a discipline rule that silently fails across sessions and teams: the manifest or status doc keeps asserting an old combination while components moved on (e.g. a status doc still naming an old contract version as "what mainline tracks" long after mainline advanced). Do not rely on an agent or person remembering to reconcile — for a manifest/status doc that is **decision-bearing across components, repos, lanes, or external consumers**, add a **standing mechanical drift check** (a CI/script fitness function, mechanics owned by `testing-strategy`); a tiny single-repo doc barely more than a local lockfile can use a lighter local script or defer the gate.
+  - **The gate is only decidable if the doc TYPES each value** — otherwise it cannot tell intentional lag from staleness and will flag legitimate `stable` lag. A *verified-combination pin* (e.g. `stable`) MAY lag head by design — **not drift**; a *"current / latest / tracks-head" claim* MUST equal reality — staleness there **is** drift. Each value declares its authority target (which component `VERSION` / conformance pin it must match). Prefer **deriving** the "current/tracks" claims over hand-writing them; a hand-maintained current value without a declared type/authority is itself a finding.
+  - **The check resolves each pin against its declared authority and emits explicit verdicts** — `match` / `drift` / `unresolvable` (deleted-or-moved ref, auth/network) / `non-immutable-pin` (a branch where a tag/SHA was required) / `circular-authority` (the "authority" is the same doc being checked). Only `drift` and `non-immutable-pin` block; `unresolvable` is a flake/triage signal, **not** auto-drift (transport failure must not block a good release); `circular-authority` **fails loudly**, never self-passes.
+
+  This is the firing mechanism for the layered model: "must not copy the pin" removes copies; the typed drift check catches the remaining current-state layer mechanically instead of by memory.
+
+## "When can the producer drop an old contract version?" (deprecation timing for consumers you don't control)
+
+A consumer whose upgrade you do **not** control synchronously — a store-reviewed mobile app, an externally distributed SDK, a customer-deployed service — does not upgrade on the producer's deploy schedule, so the backward-compatibility hold for its pinned version must key off a **real adoption/telemetry signal** (observed traffic on the old pin, store-adoption metric, consumer ack), not a date the producer picked for convenience. A `stale-after <date>` field is only a **placeholder** until that signal exists: it flags "revisit by here," it does not authorize dropping the old version. Sunsetting on the placeholder date alone — before adoption data shows the lagging consumers have moved — breaks live clients you cannot hotfix. Hold the old version, instrument old-pin usage, and let the signal (not the calendar) close the window. But lack of a signal is **not** a license for an unowned indefinite hold either: if no reliable adoption signal can be obtained, sunset still proceeds through an explicit EOL decision — documented consumer notice/outreach, a minimum support window, owner risk acceptance, a rollback/kill-switch plan, and the best available proxy evidence (store-release/adoption, SDK version telemetry, customer ack, or a contractual deprecation policy). testing-strategy's "approved compatibility window" owns the contract-test side, this owns the rollout-timing decision.

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

@@ -0,0 +1,276 @@
+---
+name: platform-service-connectivity
+description: 服务互通 / service mesh / service discovery / mTLS / retry / timeout / circuit breaker / lane routing → design or debug how one request safely reaches another service across environments, mesh, clients, HTTP/RPC, and queues.
+---
+
+# Platform Service Connectivity
+
+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:
+- Whether the right signals exist or how to alert on them — go to `platform-observability`.
+- Whether a change is safe to promote across environments — `platform-release-engineering` consumes connectivity policy as input.
+- HTTP handler shape, DB schema, or business contract design — language-specific service-architecture skills.
+- Agent/MCP tool exposure, dynamic tool catalog/cache behavior, model-visible schemas, or execution-time tool authorization — route those to `llm-inference-integration`. This skill owns the connector's network path, egress policy, mTLS/TLS boundary, service identity, and transport observability, not whether the agent may call a tool.
+
+## Skill Routing
+
+- Use this skill for: introducing or auditing service mesh, choosing service-discovery mechanism, setting retry/timeout/circuit-breaker defaults, designing lane-based or canary-based traffic shifts, debugging a "service A can't reach service B" failure, writing connectivity middleware, deciding where mTLS lives, propagating tenant/lane/log-id across hops.
+- Use `platform-observability` for: anything about whether you can *see* a connectivity failure (envoy access log, kitex/grpc trace, Prom mesh metrics).
+- Use `platform-release-engineering` for: shifting traffic during a deploy, promoting a canary, or rolling back via mesh VirtualService.
+- Use `llm-inference-integration` for: agent tool catalogs, MCP tool/resource/prompt semantics, prompt-cache or manifest stability, tool-call approval policy, execution-time authorization, and model-visible connector schemas. Return here only for the connector's network reachability, service identity, egress allowlist, TLS/mTLS, timeout/retry transport policy, or mesh/discovery path.
+- Use `defect-diagnosis` for: an active connectivity incident — come back here to land the recurring pattern.
+
+## Core Mental Model — Two Layers
+
+A request crossing two services traverses two cooperating layers:
+
+```
+Service A app code
+   │ writes ctx fields (log_id, lane, business ctx)
+   ▼
+Framework client middleware (kitex/hertz/equivalent)
+   │ packs ctx fields into request headers / RPC base struct
+   │ resolves callee via the chosen service-discovery mode
+   ▼
+A's mesh sidecar (Envoy)         ◄── owns: mTLS, retries, timeouts,
+   │ TLS, traffic policy, lane     traffic policy, lane routing,
+   │ routing, retry, timeout       circuit breaking, telemetry
+   ▼
+Network
+   ▼
+B's mesh sidecar (Envoy)
+   │ TLS terminate, authz
+   ▼
+Framework server middleware
+   │ extracts ctx fields from headers / base struct
+   │ injects into ctx for handler
+   ▼
+Service B app code
+```
+
+**Layer ownership is non-negotiable:**
+
+| Concern | Owner | Reason |
+|---|---|---|
+| mTLS | Mesh | Identity is platform-level; apps must not see keys. |
+| Connection-level retry | Mesh | Network failures are infrastructure noise. |
+| Idempotent retry of business call | App or framework client | App knows idempotency. |
+| Per-call timeout (transport) | Mesh + framework client | Mesh sets ceiling; client sets budget. |
+| Per-call timeout (business) | App | Mesh cannot know intent. |
+| Circuit breaker | Mesh primary, framework fallback | Outlier detection at network. |
+| Load balancing across replicas | Mesh | Topology-aware. |
+| Service discovery | Framework client + platform resolver | Resolver may use registry, k8s-native discovery, or a mixed mode; mesh consumes the resulting endpoints/subsets. |
+| Lane / env / canary routing | Mesh | Single source of traffic truth. |
+| Log-id propagation | Framework | Mesh sees but does not mutate. |
+| Business context propagation (tenant, user, lane awareness in code) | Framework | Mesh stays oblivious to business. |
+| Authz at request level | App (gateway or service) | Business rules. |
+| Authz at network level (which service may call which) | Mesh AuthorizationPolicy | Infrastructure rule. |
+
+Confusing these is the source of most "why doesn't this work" connectivity bugs. When in doubt: **mesh is transparent transport; framework is explicit context**.
+
+## Non-Negotiable Rules
+
+### R1 — Mesh is opt-out, not opt-in
+
+- Every service pod runs the mesh sidecar by default (`sidecar.istio.io/inject: "true"` or namespace label).
+- Specific workloads MAY opt out via explicit annotation. Documented exceptions:
+  - Telemetry collectors (would observe themselves).
+  - File-log shippers (DaemonSet with hostPath).
+  - Service discovery / registry pods (would bootstrap-cycle).
+  - Mesh control plane itself.
+- A new service that opts out of mesh without documented reason fails review.
+
+### R2 — Service discovery mode is explicit
+
+- Pick and document the platform's service-discovery mode: registry-based, k8s-native, or mixed. Use `references/service-discovery-choice.md` before mandating a registry.
+- App code MUST NOT bypass the chosen lane-routing mechanism with hard-coded cluster URLs or ad hoc hostnames.
+- Registry mode carries lane and weight in instance metadata; k8s-native mode carries lane through pod labels, Services, EndpointSlices, and mesh subsets. Both require health to be honored before routing.
+
+### R3 — Lane is the canonical multi-env primitive
+
+- "Lane" = a logical traffic isolation label: `prod`, `test`, `pre`, named per-developer lanes for staging, named per-test-run lanes for integration.
+- Lane flows through:
+  1. **Request header** (a platform-wide header name; treat the literal value as a constant) at the entry edge.
+  2. **`context.Context`** field via framework server middleware.
+  3. **Outbound RPC base struct / outbound HTTP header** via framework client middleware.
+  4. **Mesh `VirtualService` match rule** that routes lane-tagged traffic to lane-specific endpoints or subsets.
+  5. **Discovery metadata** (registry instance tag or k8s pod label) so callees are discoverable under the right lane.
+- A service that does not propagate lane through ctx is a multi-env hazard. Lane must traverse every hop, including queue boundaries.
+
+### 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.
+- 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.
+
+### R5 — mTLS is mesh-default, app cannot disable
+
+- Mesh PeerAuthentication enforces STRICT mTLS namespace-wide.
+- App code MUST NOT use plaintext HTTP/gRPC between services. Local dev can use plaintext (no mesh) but the build/staging path always tests with mesh on.
+
+### R6 — Framework client/server middleware chain is mandatory
+
+Every service uses the platform framework client and server suites; ad-hoc construction is reviewed. The default chain (RPC side) MUST include:
+
+| Middleware | Purpose |
+|---|---|
+| `ctx_inject` | extract log-id from inbound RPC headers/base; generate if missing on client side; write into `context.Context` |
+| `base_inject` / request-metadata inject (client side) | populate the outbound request-metadata carrier — the in-message `base` struct where that carrier is standardized, else the R7 owner-recorded metadata/header set (the default for ordinary gRPC) — with `log_id`, lane, idc, cluster, caller identity from ctx (uniform shape regardless of the calling language); the middleware is mandatory, the in-message `base` struct specifically is not (carrier is scenario-driven, see R7) |
+| `request_info_log` | log inbound/outbound RPC line with method, duration, error code (gated by env flag for noisy paths) |
+| `metrics` | count + histogram with baseline labels + caller/callee identity + method |
+| `error_handler` | map framework errors (timeout, panic, ACL, biz) to a stable error-code enum |
+| `tracing` (via OTel contrib) | span per RPC, parent-child link across services |
+
+If a developer can build a new client/server without these, the framework is broken.
+
+### R7 — Standard RPC base field contract
+
+For RPC platforms that support a structured request "base" (Kitex `base.Request`, Thrift `Base`, protobuf-backed gRPC request fields, or metadata-only fallbacks), the platform defines a canonical shape:
+
+```
+Base {
+  UnixTime  int64           // ms since epoch (caller's view)
+  LogId     string          // platform log-id
+  Caller    string          // PSM-style identity of caller
+  Tags      map[string]string {
+    "idc":     <region>,
+    "cluster": <k8s cluster>,
+    "lane":    <env/lane>,
+    // optional: "stress_tag", "shadow"
+  }
+}
+```
+
+Whether a platform carries this metadata in an **in-message `base` field at all**, versus the **transport metadata / context channel** (gRPC HTTP/2 metadata + interceptors — the industry-standard default for ordinary unary and streaming gRPC), is a scenario decision, not a universal mandate; the propagation obligation (R6) holds on either carrier, but the in-message field-number contract applies only where the in-message `base` carrier is used. See the Carrier decision in `references/rpc-framework-recipe.md`.
+
+For protobuf-backed internal RPC on a platform that has standardized the in-message `base` carrier, the protobuf base-field declarations are owned by `references/rpc-framework-recipe.md`. Field name, type, field number, request/response shape, exception handling, and generated-artifact provenance are fixed by that shared contract source; service repos and language-specific generated packages must consume them as generated, not rename, renumber, retype, or replace them locally.
+
+The client middleware fills this from ctx automatically; the server middleware extracts it back. **App code does not touch the base struct directly.**
+
+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
+
+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:
+
+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.
+
+Option 1 is cleaner long-term; option 2 is the live-system workaround. Document which the platform uses; new services should follow option 1.
+
+### R9 — Ingress and egress are explicit, not implicit
+
+- Ingress: traffic from outside the cluster enters via a documented Gateway (Istio Gateway / k8s Ingress). One default gateway per environment is fine; ad-hoc NodePort exposure is not.
+- Egress: traffic leaving the cluster goes through an egress gateway OR is explicitly allowed via mesh policy. "Service can reach the internet" is a configuration decision, not a default.
+- A service that needs to call an external third-party API declares it; the platform sets up the egress path with mTLS termination, retry, observability.
+
+### R10 — Envoy access log is part of the observability contract
+
+- Mesh access logs MUST include `log-id` and `lane` fields (read from request headers).
+- Access logs ship to the same log pipeline as app logs so on-call can join "what mesh saw" with "what app saw" by log-id.
+- `enablePrometheusMerge` (Istio) is enabled so Envoy stats appear in the same Prom scrape as the app — one less moving part.
+
+### R11 — Long-lived streaming control channels need transport contracts
+
+- WebSocket, SSE, long-poll, or split read/write transports need explicit connection state: idle, connected, reconnecting, closing, and closed. Permanent auth/not-found/protocol rejections stop retry; retryable network, 429, and 5xx failures use bounded exponential backoff with jitter and a total reconnect horizon.
+- Reconnect must refresh credentials, preserve or send a high-water mark that advances only after durable apply or write, replay only unconfirmed outbound messages whose original principal/workspace/session/policy/capability/auth-generation tuple still matches, deduplicate by stable event/request id, and fence callbacks from a previous transport incarnation.
+  - If that tuple changed, cancel or fail closed and surface unknown finality instead of replaying under fresh credentials.
+  - If multiple sessions run in one process, auth headers and tokens must be per transport instance, not process-global mutable state.
+- Liveness is not optional. Define heartbeat or keepalive cadence, liveness timeout, proxy idle-timeout mitigation, sleep/wake behavior, listener/timer cleanup on reconnect and close, and graceful shutdown drain windows. A closed transport must release blocked writers and must not leave orphan listeners, timers, pings, or callbacks.
+- Streaming writes need backpressure and queue bounds. Batches are serialized when the downstream store cannot safely handle concurrent writes; retry-after hints are clamped and jittered; permanent failures, max-failure drops, close-time drops, and best-effort flush semantics are surfaced as diagnostics rather than silently treated as delivered.
+
+### R12 — Local egress relays are credentialed transport, not environment sugar
+
+- A local proxy or relay that injects credentials, rewrites trust roots, or tunnels subprocess traffic must bind only to loopback, fail open only before credentials are accepted or injected when optional setup fails, and fail closed once it has accepted a credentialed tunnel but cannot safely continue. Delete or revoke bootstrap secrets only after the listener, trust bundle, and cleanup path are proven ready, and before launching credentialed children or accepting traffic when possible; keep the secret out of model context, child-visible arguments, logs, dumps, crash reports, and fixture files.
+- A local browser authorization callback listener is also credentialed transport.
+  - Bind only to loopback, prefer an OS-assigned port unless a caller explicitly owns the port, validate callback path and host/port, accept only the pending flow's state, and reject duplicate or late callbacks after manual fallback, cancellation, timeout, success, or failure.
+  - Pending HTTP responses must have exactly one terminal outcome, listeners must remove handlers and close on every exit path, and callback secrets or authorization codes must never be echoed into child process args, model-visible prompts, logs, telemetry, dumps, or fixture files.
+- Trust-root and proxy environment changes are scoped runtime state. Publish them only to the intended child process tree, include explicit bypass rules for loopback, metadata, private networks, first-party control channels, package registries, and other direct paths, and never route plain traffic through a credential-injecting tunnel unless the protocol explicitly supports it. Per-runtime proxy support differences need tests; inherited proxy variables must be passed through only when the parent relay is still the intended authority.
+- CONNECT-style or byte-tunnel relays need parser and stream contracts: cap header size, reject non-tunnel methods, preserve bytes that arrive before the upstream tunnel is open, chunk large payloads, validate tunnel frame encoding, implement keepalive inside proxy idle windows, handle partial writes and backpressure per runtime, avoid writing plaintext errors after encrypted payloads may have begun, and cleanup listeners, timers, sockets, and upstream sessions on every close path.
+
+## Workflow
+
+### Phase A — Identity and lane chain
+
+1. Confirm lane and log-id propagate through ctx for every hop type (HTTP, RPC, queue). Spot-check by reading framework client/server middleware, not user code.
+2. Confirm the RPC base struct (or HTTP header equivalent) carries `log_id` + tags `{idc, cluster, lane}`. A missing tag is a propagation bug.
+
+### 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.
+4. AuthorizationPolicy expresses which services may call which (zero-trust at network level).
+
+### Phase C — Service discovery
+
+1. Confirm the chosen mode is documented: registry-based, k8s-native, or mixed.
+2. Registry mode: registry is multi-replica, explicitly NOT in mesh; SDK resolver uses registry metadata.
+3. K8s-native mode: Service / EndpointSlice / pod labels are the discovery source; app code does not bypass mesh/lane routing with raw cluster URLs.
+4. Discovery metadata includes `lane` (registry tag or pod label) so VirtualService subsets can target correctly.
+5. Healthcheck contract exists: registry heartbeat or k8s readiness removes unhealthy endpoints within the documented window.
+
+### Phase D — Framework middleware
+
+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.
+
+### Phase E — Failure modes
+
+1. Mesh sidecar crash → app pod fails readiness. Configured behavior?
+2. Discovery backend unreachable → resolver uses cached endpoints for a bounded TTL, or fails closed by documented policy?
+3. Lane label drops mid-chain → service calls wrong env. Detected how?
+4. Cascading timeout → caller deadline exceeded but downstream still running. Hedge or cancel?
+
+### Phase F — Evidence
+
+Before marking work done:
+- One request traced end-to-end across ≥ 2 services; mesh access log + app log + trace all share the same log-id.
+- One synthetic outlier: pod 5xx → mesh ejects → recovers when pod healthy → metrics + access log show the pattern.
+- One lane-routing verification: request with lane=test header → arrives only at lane=test instances. Verified via access log `upstream_host`.
+
+## 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.
+- **"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.
+- **"Multiple registries (legacy + new)"** → run them side-by-side, dual-write during migration, single read source per lane.
+
+## Sanitization and Provenance
+
+This skill is product-agnostic. It must not contain:
+- Repository names, service names, internal hostnames, internal IPs, namespaces, cluster names.
+- Business-domain header values, tenant types, or vertical terms.
+- Specific image registry URLs, ingress hostnames, or cloud-provider artifact paths.
+- Concrete credentials or example certificates.
+
+Reused industry patterns (PSM-style identity, `<owner>.<class>.<env>` shape, `traceparent`, `:authority` semantics) are fair game.
+
+## References
+
+- `references/mesh-architecture.md` — Istio (or equivalent) topology, sidecar injection rules, gateway shape, EnvoyFilter use, what mesh owns vs framework owns.
+- `references/service-discovery-recipe.md` — Registry-based SD (Nacos as recurring example), instance metadata, lane tag, healthcheck contract, dev-vs-prod differences.
+- `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/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.
+- `references/service-discovery-migration-playbook.md` — Step-by-step playbook: 6-phase registry-retirement (inventory / add k8s resolver / dual-resolve burn-in / switch registration off / migrate off-cluster tools / decommission); per-phase risk + rollback path; total ~3 months active work for medium platform; reverse direction (add thin sync-only registry) for off-cluster lookup; 6 anti-patterns to avoid during migration.
+- `references/protobuf-http-contract-signals.md` — Cross-stack gate for classifying an HTTP surface as routine JSON/OpenAPI vs protobuf-backed: the in-scope/out-of-scope predicate, protobuf signal list, authoritative wire-format record, and owner-approval decision list. Shared by the Go/Python/web/mini-program/testing skills (each points here; do not redefine per stack).
+- `references/http-response-envelope-contract.md` — Cross-stack JSON business-response envelope (`code`/`message`/`data`): canonical shape, new-service vs new-route vs existing-surface adoption/migration, non-JSON surfaces that record their own contract, and the invent/duplicate/hide anti-patterns. The response-side companion to the request-side base struct; shared by the same stack skills (each adds only its define/implement/consume/assert verb).
+
+## Verification before marking work done
+
+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.
+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.
+
+If any check fails, the work is interim, not done.

package/dist/assets/marketplace/plugins/ccl-skills/skills/platform-service-connectivity/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Platform Service Connectivity"
+  short_description: "Design service-to-service connectivity"
+  default_prompt: "Use $platform-service-connectivity to design mesh, service discovery, mTLS, retries/timeouts, circuit breakers, and cross-service routing."