@ccoalm/ccl-skills 0.1.0

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

@@ -0,0 +1,119 @@
+# Protobuf Contract Architecture
+
+Use this when designing protobuf IDL for HTTP APIs, internal RPC, events, generated clients, or gateway routes.
+
+## Contract Boundary
+
+- Treat `.proto` files as source contracts; generated files are outputs.
+- Separate public API contracts from internal RPC contracts when stability or security requirements differ.
+- Keep shared envelopes, annotation extensions, and common enums in small dedicated protos; keep resource messages in owning package protos.
+- Avoid monolithic service protos; split by capability, ownership, lifecycle, or client stability.
+- Design request/response pairs per method unless streaming, batch, or shared shapes are intentionally stable.
+- Put pagination, filtering, sorting, and idempotency fields in v1 for list and write APIs that need them.
+- Transport metadata such as trace id, auth subject, lane/environment, and service identity should travel via metadata or middleware unless it is part of the contract.
+
+## Package And Import Policy
+
+- Every proto needs `syntax`, `package`, and a language package option such as `go_package`.
+- Package names should be stable and independent of repo-local paths.
+- Imports should point to source protos, not generated Go packages.
+- Custom HTTP/gateway annotations belong in a dedicated annotation proto; normal contracts should import it rather than redefine options.
+- `proto2` is acceptable for descriptor extension files; product contracts should use `proto3` unless there is a specific compatibility reason.
+
+## Evolution
+
+- Never reuse field numbers or enum numbers.
+- Reserve deleted field numbers and names.
+- Prefer additive fields, new methods, and new enum values over semantic changes.
+- Do not change the meaning, type, cardinality, or units of an existing field.
+- Keep public API messages more stable than internal RPC messages.
+- Use explicit versioned messages or methods when compatibility cannot be preserved.
+- **Protobuf Edition 2024 (released in protoc 32.x, Q3 2025) is the current evolution baseline** — supersedes the "proto2 vs proto3" syntax dichotomy with the editions model (per `protobuf.dev/editions/overview/`). Key feature changes Edition 2024 introduced over Edition 2023: (a) `string_type` feature default changes from `STRING` to `VIEW` (more efficient string handling at the generated-code layer; verify generated Go output behavior on the migration); (b) `EXPORT_TOP_LEVEL` default ensures top-level symbols are exported and nested symbols are local by default, with explicit `export` / `local` keywords for annotation — this is a visibility model previously not available in proto syntax; (c) `import option` syntax imports only custom options from a `.proto` file without pulling in other symbols, reducing dependency graph noise. Migration strategy: do NOT mass-migrate existing proto2/proto3 files to Edition 2024 in one commit — convert per file as that file is touched for other reasons, run `buf breaking` against every conversion, and verify each generated language target (Go via protobuf-go, plus any other consumer language) re-renders identically. Buf supports Editions 2024 in current buf-cli (v1.x as of writing); BSR-managed plugins continue updating per the BSR release notes — pin specific plugin versions in `buf.gen.yaml` so a managed-plugin auto-bump doesn't silently change generated code. Edition 2024 does NOT change the wire format — old binaries can still parse messages from Edition 2024 sources; the changes are at the IDL syntax + generated-code-shape layer.
+
+## Message Modeling
+
+- Leave numeric gaps for expected growth.
+- Group field numbers by purpose only when it improves readability; do not depend on order semantically.
+- Use nested messages only for substructures that are scoped to a parent and unlikely to be reused.
+- Use `optional` when zero/empty and absent have different meanings.
+- Use `repeated` for collections; define ordering, max size, and dedupe rules in comments or validation.
+- Use `map` only for open-ended key/value metadata; use repeated typed entries when keys or values need validation or evolution.
+- Use `oneof` for mutually exclusive payloads and document unknown or empty behavior.
+
+## Enum And Status Policy
+
+- The zero enum value should be `UNKNOWN` or `UNSPECIFIED`.
+- Prefix enum values consistently to avoid generated-name collisions.
+- Status enums should include initial, in-progress, terminal success, terminal failure, and cancellation states only when the workflow needs them.
+- New enum values must be tolerated by old clients; clients should handle unknown values safely.
+- A protobuf enum is a transport contract, not automatically the domain source of truth. Architecture decides whether generated enum types may be used beyond transport/adapters; if storage, clients, analytics, or existing domain models use another representation, define explicit conversion helpers and a migration plan. Any transport-coupled exception must be traceable through an ADR or an inline usage-site comment formatted `architecture-approval: transport-coupled finite value <scope> <decision-ref> <reason>` where `<decision-ref>` is a full URL or numeric record id such as `ADR-123`; reviewers must confirm the referenced record exists and approves the specific value/scope before approval. A CI check, grep panel, or required review checklist item MUST exist and pass before any PR introducing `architecture-approval:` comments is merged; absence of that check is itself a blocking finding. The first PR that introduces `architecture-approval:` comments must include the enforcement check in the same PR or reference a prior merged check; "will add later" is not approval.
+- Shared enum placement is an architecture decision. Put cross-service finite values in the smallest shared IDL or domain/platform package that has real ownership; if none exists, approve a local fallback and track consolidation with `finite-value-debt: <task-ref> <owner> <deadline> <reason>`.
+
+## Error And Envelope Policy
+
+- Use one response envelope or canonical error contract consistently.
+- Common code/message fields should not replace typed resource data.
+- Shared error code ranges should be governed; local codes should not be added to global enums unless multiple clients depend on them.
+- Do not inherit a framework's reserved envelope/base field number as a contract convention. New products should choose an explicit envelope field and document it.
+- Keep request metadata minimal. Trace id, lane, caller identity, and auth context should normally be middleware metadata; put them in protobuf messages only when cross-language clients or async payload persistence require a typed contract.
+
+## Streaming And Surface-Shape Validation
+
+These tier/streaming/shape rules are cross-stack; the mirror lives in `python-service-architecture/references/api-contract-and-schema.md` (Contract Tiers, Streaming, And Shape Validation) — keep both in sync.
+
+- **A server-streaming RPC's streamed message is a separate shape decision — not automatically the unary response envelope.** A per-item business envelope (SSE / NDJSON / SDK-compatible styles do this) or a discriminated event stream both work; just don't force the unary request/response envelope by default. Define completion and error semantics explicitly, and decide whether termination/errors travel in-band or via transport status/trailers (gRPC). For a fatal terminal error on a transport that can still signal it (e.g. gRPC trailers), surface a non-success status so monitoring/retry/circuit-breaking aren't misled; where the status header is already committed (SSE / NDJSON after a 200), carry the error in-band and ensure observability classifies it as a failure rather than trusting the 200. A stream that already emitted client-visible data or dispatched side effects is not freely retryable, so don't assume the unary retry rule. Per-domain event payloads (e.g. token usage on an inference stream) are that service's contract, not a universal field set. Ensure any envelope-shape check exempts the streamed message rather than misfiring on a `*Response`-style name.
+- **Distinct contract tiers are distinct shapes — do not force one envelope across all.** Internal RPC (shared base + typed data), the public HTTP JSON business envelope (per the canonical HTTP-response-envelope contract), streaming events, and **externally-dictated standard protocols** (a provider-compatible API, a webhook spec, an industry wire format) each carry their own shape. An externally-dictated protocol follows that protocol's wire, mapped from the contract source — it is NOT the internal RPC or HTTP envelope. But a compatible wire is **not an exemption from internal controls**: authz, tenant isolation, quota, audit, and error-code governance still apply behind it — "we're just being standard-compatible" must not become a bypass. For a surface with no consumer yet, don't default it to another tier's envelope; define its own contract when a consumer or stability requirement appears.
+- **Make the conventions machine-checkable and multi-service, scaled to repo maturity.** The contract conventions (per-tier shapes, shared base, naming, base-field placement) belong in an agent-readable spec that a contract health check enforces. The check should iterate every service rather than hardcode one, validate each unary tier's envelope, and exempt streaming events and the shared-base definitions themselves. Scale enforcement to risk — a hard CI gate for production multi-consumer IDL, a lighter check plus recorded gaps for early/migration/prototype repos. A service it cannot yet validate is recorded as a gap with an owner and severity, not silently skipped; a single-service-hardcoded or unary-only check lets agents infer the shape from whatever materialized example they find, which drifts when that example itself diverged.
+
+## IDL Repo Organization
+
+- For portfolios with more than a handful of services, architecture decides whether IDL lives in dedicated repos (one per IDL family — proto, thrift, http-thrift) or inline with business code. Dedicated IDL repos make codegen, breaking-change checks, and multi-language publishing cheaper, but require explicit consumer/publisher contracts and a release cadence.
+- Inside one IDL set, organize sources by intent, not by team: a shared tier (`base`) for the canonical error/code enum and reusable structs, a gateway-facing tier (`api`) for contracts that cross the trust boundary, and per-domain tiers (`<domain>`) for internal RPC. The tiering is what makes Code range allocation, schema review, and downstream consumer rules tractable. Within one IDL set, the shared `base` is **defined once and imported** by every service, never redeclared per service within that set (a deliberate compatibility fork with owner, version, and deprecation plan is the documented exception — e.g. an open-source SDK or a cross-trust-domain boundary); a service that diverged unintentionally is recorded as a known divergence with an explicit migration target, not silently tolerated as a parallel convention.
+- Reserve numeric Code range explicitly (e.g., `[0, 11999]` in `base.proto`) and sub-allocate per tier so services cannot accidentally collide. Architecture owns the allocation table.
+- Multi-language codegen needs an explicit per-language script (Go, Python, TypeScript, etc.) driven by the IDL repo's CI. Architecture decides which languages are canonical (have integration tests) versus generated-only (clients without independent test coverage).
+- Breaking-change governance is required for any IDL surface that has more than one consumer team or external clients. `buf breaking`, `kitex check`, or equivalent runs in CI; intentional breaks route through an explicit approval path.
+
+## Runtime IDL Loading For Generic Call
+
+When a service needs to call another service whose IDL is not known at build time — typical use cases: gateways routing to many backends, admin/management consoles that proxy arbitrary service methods, debug/inspection tooling, dynamic test harnesses — the runtime fetches and parses IDL on demand and invokes the target via the framework's generic-call mechanism (Kitex `generic.Call`, gRPC reflection + descriptor pool, Thrift skeleton-less call).
+
+The pattern is real and useful but adds an authority + safety surface beyond static IDL:
+
+- **IDL source authority**: the runtime resolves an IDL fetch through an explicit registry — an IDL repo with a stable URL, a centralized descriptor service, or an internal package index. The IDL source identity is part of the call: a generic call against an IDL fetched from a user-supplied URL is unauthenticated code injection through schema. Reject IDL sources outside the allowlist.
+- **Recursive include / import resolution**: thrift `include` and proto `import` chains can pull in dozens of transitive files. The fetcher must (1) follow includes to a documented depth limit (typical 10) — refuse deeper, that is usually a misconfigured loop, (2) **deduplicate by canonical source identity + content digest, not by fully-qualified name alone** — FQN-only dedup hides alias / path loops, descriptor shadowing, and dependency-confusion cases where two sources claim the same FQN with different bodies; the fetcher rejects duplicate FQNs with non-matching digests at parse/link time, (3) record every fetched file's source identity in the call audit log, (4) bound total bytes fetched per resolution so a malicious or buggy IDL cannot exhaust memory.
+- **IDL parse cache with version pinning**: the parsed descriptor for `(idl_source, version)` is cached so repeated calls do not re-fetch / re-parse. Cache key includes version; cache invalidation triggers on registry signal, not on TTL alone (a TTL miss while the IDL is in transition picks up a half-published version).
+- **Call surface authorization**: generic call is broader than the caller's normal scope. The dispatcher checks (a) caller is allowed to use generic-call at all (most callers are not), (b) caller is allowed to invoke the target service + method, (c) the method is on the target service's published surface (not an internal/admin method exposed accidentally by reflection).
+- **Request shape validation on the fly**: since the request is not a compiled type, the dispatcher must validate the request body against the parsed descriptor before forwarding — required-field presence, oneof exclusivity, recursion depth on nested messages, total message size. Enum validation follows proto3 forward-compatibility: unknown enum numeric values are accepted (the backend may have added them in a newer rollout), not rejected; rejecting unknown enum values breaks rolling upgrades where descriptor and backend release independently.
+- **Audit per call**: generic call records caller identity, target service, target method, IDL source + version, request id, and outcome. The audit log is the only forensic surface when an attacker pivots through a generic-call gateway.
+- **Failure modes worth naming**:
+  - **IDL fetch failure for an uncached version** (registry down, network partition, requested version never been fetched): fail closed; never fall back to a stale, default, or sibling-version schema.
+  - **IDL fetch failure when a verified pinned descriptor is already cached**: serve from cache, but only while the cached descriptor's revocation-status lease is still valid. Cached descriptors carry a `last_known_not_revoked_at` timestamp refreshed by the registry on each successful poll; serving from cache during a registry outage is allowed up to a documented lease window (typical: minutes to a small number of hours, set by the security policy), after which the dispatcher fails closed even though the descriptor itself is still parsed in memory. A descriptor version whose revocation signal has been received (registry marked the version revoked / disabled, or the lease expired) MUST fail closed immediately and is purged from cache; never serve a known-revoked or lease-expired descriptor. The distinction is "no verified descriptor available for the requested version" (fail closed) vs "verified, not-revoked, lease-valid descriptor for this version is already cached" (serve).
+  - **Partial fetch** (some includes resolved, others timed out): reject the whole call; do not invoke with a partial descriptor.
+  - **Descriptor version drift between fetch and call**: re-fetch under single-flight; do not mix two descriptor versions in one call chain.
+
+## Runtime Frame Proxy (Generic Call Without Descriptors)
+
+Sibling pattern to Runtime IDL Loading: instead of fetching+parsing descriptors and reconstructing typed calls, the proxy intercepts the raw RPC frame at the unknown-service handler (Kitex `WithGRPCUnknownServiceHandler`, gRPC's `UnknownServiceHandler`, equivalent) and forwards opaque payload bytes to a routed target. The proxy never parses the message body. Use cases: mesh-style routing for arbitrary methods, cross-lane traffic mirroring, blue/green frame replay, debug capture. Distinct trade-offs from descriptor-based proxying:
+
+- **Caller identity comes from authenticated transport context, never from inbound metadata**: the proxy derives caller identity exclusively from the authenticated server context (mTLS client cert, signed session/JWT verified by middleware, SPIFFE id, k8s SA TokenReview) — not from inbound gRPC metadata headers, not from the payload. Any caller-identity-like metadata in the inbound frame (`x-caller-*`, `x-user-*`, claimed `from-service`) is stripped or overwritten with the authenticated value before any logic runs and before forwarding. Trusting metadata-claimed identity lets a caller impersonate an allowed principal and pivot through the proxy.
+- **Routing source is an explicit metadata header on the inbound frame**, not the message body: e.g. a `destination-service` header carrying the target PSM/identity. The proxy MUST NOT trust caller-claimed identity embedded inside the payload (it would require parsing the body, which defeats the frame-level design and opens authorization gaps).
+- **Routing header is canonicalized and validated BEFORE SD lookup**: reject non-canonical service ids, raw FQDN / IP / URL values (SD must be the only resolver), namespace or lane-escape syntax inside the header, duplicate or multi-value headers, and any value not in the authenticated caller's per-target allowlist. Without pre-SD validation, SD becomes a routing oracle and depending on the resolver implementation can become an internal-SSRF path. Authorization runs AFTER canonical target resolution and on the authenticated caller identity, not the claimed one.
+- **Target address resolution goes through the same service-discovery layer as typed clients**: DNS/FQDN construction for in-cluster, explicit timeout. The lane-routing default for a frame proxy is **fail-closed on lane miss**: a request bound for lane `canary` that does not resolve in `canary` is rejected (audit + structured error), NOT silently forwarded to base. Lane fallback is opt-in per route policy and applies only to routes where cross-lane delivery is explicitly safe; the default protects blue/green replay, mirror, debug-capture, and any tenant-scoped lane from silent wrong-recipient delivery. SD lookup empty must fail fast — never retry against a last-known address.
+- **Admission control is mandatory in addition to per-stream backpressure**: cap (a) max concurrent proxied streams globally and per route, (b) max inbound frame / message size, (c) per-caller and per-target-service concurrency. "Single goroutine pair, no full-stream buffer" prevents per-stream OOM but does not prevent many-streams OOM or oversized-frame OOM. Excess admission returns a structured `RESOURCE_EXHAUSTED` / 429 and is metered.
+- **Context propagation MUST cross all three surfaces** simultaneously: framework `appctx` value (for in-process middleware), outgoing gRPC `metadata` (for the wire), and persistent metainfo (`kitex_metainfo.WithPersistentValue` or equivalent, for in-cluster persistent values that survive through hops). Trace id, lane, tenant, and (authenticated) caller identity must each appear on all three; missing one breaks downstream observability or routing. Test this with end-to-end trace correlation, not by inspecting the proxy alone.
+- **Authorization is mandatory at the proxy boundary**: the proxy is broader than a typed client — any caller able to send a frame to the proxy can address any backend reachable from it. Apply (authenticated-caller) × target-service × method allowlist after the routing header is canonicalized, before forwarding. Same posture as Runtime IDL Loading's call-surface authorization. The proxy is a privilege boundary; treat its exposure surface like an API gateway, not like an internal RPC.
+- **Payload codec coercion via framework-internal reflection is fragile**: code that reaches into the framework's internal `RPCInfo` / `Stream` types via `reflect.FieldByName(...)` to coerce payload codec or extract the underlying server stream pins the proxy to a specific framework version and breaks on minor upgrades. Acceptable when no public API exists, but: (a) pin the framework version explicitly, (b) document the reflective access in a comment naming the version, (c) add a build-time or startup-time assertion that the expected fields exist, fail closed on absence.
+- **Server-stream forwarding preserves backpressure**: the proxy reads from the inbound stream and writes to the outbound stream in a single goroutine pair; do not buffer the entire stream in memory. Close propagation must work both directions (client cancel → upstream cancel; upstream error → client error frame).
+- **Observability**: log per-call records {authenticated_caller, target_psm, target_method, route_decision, lane, admission_decision, latency, error}. The proxy is often the only place where cross-service call patterns are visible at this granularity; this log is forensic evidence for routing or auth incidents.
+- **Failure modes worth naming**: routing header missing / non-canonical → reject with explicit error (do not silently forward); routing header valid but caller lacks authorization → reject and audit; lane miss without explicit fallback policy → reject and audit (do not fall back to base); SD lookup empty → reject (do not retry against last-known address); admission cap hit → structured exhaustion error, do not queue indefinitely; framework reflective access fails (post-upgrade) → fail closed and alert, do not fall back to typed default that may not exist.
+
+## Front-End Consumer Contract
+
+The HTTP/RPC contract that Go services publish is consumed by front-end clients (React Web, mobile web, mobile-native). The same envelope/header/timeout rules that the server owns appear on the consumer side; architecture documents both sides so they cannot drift independently.
+
+- **Envelope direction**: the response envelope shape the server emits is the same shape every front-end client parses. Mixing HTTP-200-always with HTTP-status-as-semantic across services in the same portfolio forces the front-end client to special-case per endpoint; the choice is a portfolio-level architecture decision recorded once. See the consumer-side rules in `web-react-dev/references/web-quality-release.md` (Cross-Stack Contract section) and the server-side decision in `error-contract-architecture.md`.
+- **Trace propagation**: the server reads `X-Request-ID` from inbound HTTP requests when present and otherwise generates one; it propagates the request id and the runtime trace id on the response so the front end can surface them in error UI. A server that drops the inbound `X-Request-ID` because middleware did not register the read is a finding — end-to-end correlation depends on this header surviving from client to log line.
+- **Auth header contract**: the server agrees with the front end on the auth header name (e.g. `Authorization` or a platform-specific token header), the app-identity header, and any tenant / lane / shadow-traffic headers that the front end injects. The server validates them through middleware once and exposes the result on the request context using a tiered context-keys convention.
+- **Timeout layering**: outer caller budget is always longer than inner callee budget. For the path `front-end client → gateway → downstream RPC`, the relationship is `client timeout > gateway timeout > downstream RPC timeout`. A gateway longer than the client lets the client time out before the gateway can return a structured error with the trace id; a gateway shorter than the downstream RPC budget the gateway itself initiates lets the gateway give up while the inner call is still running, leaving the work in an undefined state. Per-endpoint risk tunes the specific values; the ordering is invariant.
+- **Client-signed object-storage upload**: when the architecture supports direct front-end → object-storage upload, the server exposes a narrow `signed-token` / `STS` endpoint that returns a short-lived credential plus the upload target (bucket, key prefix, expiry). The credential is scoped, the expiry is short, and the server logs token issuance for audit. The main API path never carries the file body.
+- **SDK/codegen for the front end**: when the contract is exposed via OpenAPI / IDL annotation, the front-end TS client is generated from the same IDL the server compiles; architecture owns the generator command and the publishing cadence so the front-end client never lags the server contract by more than one release.

package/dist/assets/marketplace/plugins/ccl-skills/skills/go-microservice-architecture/references/redis-cache-coordination.md

@@ -0,0 +1,93 @@
+# Redis Cache Coordination
+
+Use this when designing Redis usage for a Go microservice product.
+
+## Redis Responsibility
+
+- Redis is appropriate for ephemeral coordination: cache, locks, counters, rate limits, idempotency windows, lightweight task queues, and short-lived workflow state.
+- Redis should not be the durable source of truth for domain state that must survive data loss or require auditability.
+- If Redis state changes domain outcomes, pair it with a relational record, idempotency table, event log, or reconciliation process.
+- Define failure behavior per use case: fail closed for risk controls, fail open for non-critical cache, retry for transient coordination failure.
+
+## Key Space Design
+
+- Keys should be built through typed functions, not inline string formatting across application code.
+- Key format should include stable dimensions in a consistent order:
+  - product or service namespace.
+  - data purpose.
+  - environment or lane when needed.
+  - authorization/resource/workflow id when needed.
+  - entity id or operation id.
+- Local development and tests should avoid colliding with shared environments through prefixes, isolated Redis DBs, or fakes.
+- Avoid raw user input in keys unless normalized and bounded.
+
+## TTL Policy
+
+- Every cache, lock, idempotency, rate-limit, and task-state key needs an explicit TTL unless intentionally durable.
+- TTL should be chosen from domain semantics:
+  - cache freshness window.
+  - retry/idempotency window.
+  - lock critical-section duration plus safety margin.
+  - rate-limit window plus cleanup margin.
+  - task recovery window.
+- No-unlock throttle locks are acceptable only when expiry is the intended release mechanism.
+- Durable or no-expiry Redis state needs an owner and cleanup strategy.
+
+## Cache Strategy
+
+- Use local memory cache for small, frequently read, eventually consistent reference data.
+- Use distributed cache when multiple instances need shared cache state or invalidation.
+- Cache miss, negative cache, and Redis failure must be distinguishable to callers.
+- Cache data should be versioned or invalidated when source schema changes.
+- Never cache secrets or raw authorization tokens unless encrypted and explicitly justified.
+
+## Locks And Coordination
+
+- Lock values must be unique per attempt and unlock must compare value before deleting.
+- Renewable locks need lease, renewal interval, max lease, cancellation behavior, and failure hook.
+- Long critical sections need compare-and-renew semantics, not blind expiry extension; renewal failure must stop or safely downgrade the work according to the workflow policy.
+- Lock scope should match the domain critical section, not the handler name.
+- Redis locks can reduce concurrency but should not replace database constraints for durable correctness.
+- Long-running jobs should expose skipped-lock, acquired-lock, renewal-failure, and duration metrics.
+
+## Rate Limits And Counters
+
+- Rate limits need a scope, window, threshold, retry/conflict behavior, and user-facing error contract.
+- Sliding-window limits should clean old entries and set expiry longer than the window.
+- Counters need explicit semantics:
+  - can go negative or cannot.
+  - initialize-on-missing or fail-on-missing.
+  - expiry reset on increment or fixed expiry.
+  - exact truth or approximate throttling signal.
+
+## Task Coordination
+
+- Redis sets, sorted sets, and lists can coordinate lightweight pending work, but durable jobs need a real queue or database-backed state.
+- Task entries should carry enough metadata to inspect, retry, or repair stuck work.
+- Pop operations should be atomic when losing work is unacceptable.
+- Scheduler locks and task queues should include recovery and max lease behavior.
+- Script-based coordination should define success, compare-failed, missing-key, and invalid-return semantics so callers can choose retry, skip, fail, or repair deliberately.
+- If Redis is used for idempotency, architecture must distinguish pending claim, completed marker, duplicate completed event, and retryable failure. Pending claims need a lease/TTL; completed markers need a dedupe window aligned with external retry behavior.
+- Redis Streams, Pub/Sub, lists, and sorted sets should be chosen by delivery semantics, not convenience: fire-and-forget notification, replayable stream, deduplicated pending work, delayed scheduling, or durable work backed by DB/MQ.
+- Broad key scans, pattern deletes, stream trimming, and TTL cleanup need an owner and bounded strategy before launch.
+- Redis failure policy must be explicit per responsibility: fail open for optional caches, fail closed for authorization or risk controls, return duplicate or pending states for idempotency, and expose retry or repair for workflow coordination.
+
+## Cache Stampede Architecture
+
+- For any cache fronting an expensive source of truth, architecture names the stampede defense: single-flight (one fetcher per key), negative caching with shorter TTL for misses, and randomized TTL jitter. Architecture also names the staleness budget so the team can pick the right combination.
+- Multi-tier caches (in-process in front of Redis in front of DB) need a coherent invalidation contract: Pub/Sub fan-out, topology-change events, or explicit delete-on-write. Architecture names the chosen mechanism per cache tier.
+
+## Cluster Topology Boundary
+
+- If Redis is deployed as Cluster, architecture declares the hash-tag convention and which keys must share a slot. Cross-slot Lua, `MULTI/EXEC`, and dependent pipelines are architectural decisions encoded in the key schema, not coincidence.
+- Cluster failover, slot migration, and topology refresh are owned at the platform layer; this skill names the client's expected behavior (refresh on `MOVED`/`ASK`, retry on topology change, idempotency on the retry path).
+
+## TLS And Managed-Auth Boundary
+
+- Production Redis traffic must be authenticated and encrypted. For self-hosted Redis this means TLS plus ACL users with least-privilege command grants; for cloud-managed Redis it may additionally mean IAM/AAD short-lived tokens via a per-connection auth callback. Architecture names the trust anchor and credential lifetime.
+- Application users get the minimum command set; cluster-wide admin commands (`FLUSHDB`, `CONFIG`, `DEBUG`) are not part of application grants.
+
+## Retry And Circuit Breaker Ownership
+
+- Retry policy and circuit breaker for Redis access live at the dependency-assembly layer, not scattered through call sites. Architecture names the transient-error catalog and the breaker scope.
+- Breaker-open behavior is a product contract: cache-miss path may return stale-OK, authz path must fail closed, idempotency path returns "duplicate uncertain". Architecture names the per-responsibility semantics rather than letting the resilience layer pick silently.

package/dist/assets/marketplace/plugins/ccl-skills/skills/go-microservice-architecture/references/release-runtime-readiness.md

@@ -0,0 +1,65 @@
+# Release Runtime Readiness
+
+Use this when designing launch, deployment, traffic, canary, or operating model for a Go microservice product.
+
+## Runtime Model
+
+- Treat runtime metadata as part of the architecture: service identifier, app name, owners, protocol, environment/lane, image, resource profile, replica count, ports, hosts, paths, storage needs, and whether special hardware is required.
+- Keep environment/lane separate from authorization/resource scope. Environment/lane routes traffic and controls deployment; resource scope controls data access and authorization.
+- Make local, test, staging, canary, and production behavior explicit. Avoid hidden defaults that make a request unexpectedly cross environments.
+- Service registration should include discoverable tags for environment/lane and should not require callers to know deployment internals.
+- Health and readiness must be defined before traffic is enabled. A simple process liveness endpoint is not enough when DB, Redis, MQ, or critical remote dependencies gate correctness.
+- **Go runtime version baseline (2025-2026)**: track at architecture level which Go version the service is built and deployed against, since 1.23/1.24/1.25 each shipped runtime-behavior changes that affect production. (a) **Go 1.25 (released Aug 2025) container-aware GOMAXPROCS**: on Linux the runtime reads the cgroup CPU **bandwidth limit** (not the request) and defaults `GOMAXPROCS` to `min(logical_cpus, cgroup_limit)`; for k8s pods this means `requests: 500m, limits: 4000m` → `GOMAXPROCS ≈ 4` (driven by the limit), so right-sizing CPU **limits** matters more than requests for goroutine scheduling. On all OSes the runtime periodically updates `GOMAXPROCS` if the limit changes — services that historically hardcoded `runtime.GOMAXPROCS(...)` at startup based on `runtime.NumCPU()` were silently over-scheduling under k8s CPU limits; on 1.25 the runtime fixes this BUT a service that still sets GOMAXPROCS manually defeats the auto-tuning. Upgrade discipline: **remove STALE GOMAXPROCS defaults** (hand-set values that were workarounds for the pre-1.25 behavior); **keep MEASURED overrides** when the team has profiled justification — I/O-heavy services that legitimately oversubscribe (set GOMAXPROCS above CPU limit to absorb async wait time), services that reserve a CPU slot for in-pod sidecars by undersubscribing, and services that intentionally pin GOMAXPROCS for predictable GC behavior all remain valid. Treat the upgrade as "audit each manual call → keep with rationale comment OR remove" rather than blanket removal. (b) **Go 1.25 experimental Green Tea GC** (`GOEXPERIMENT=greenteagc`): per Go release notes, reduces GC overhead by 10-40% on many applications — opt-in flag, NOT production-default yet; pilot on a representative non-critical service before flipping production. (c) **Go 1.25 experimental encoding/json/v2** (`GOEXPERIMENT=jsonv2`): faster, stricter, better errors — opt-in flag, track for likely Go 1.26+ stabilization. (d) **Go 1.24 (Feb 2025)** added FIPS-140 mode, crypto/mlkem post-quantum key exchange (auto-enabled in TLS when `Config.CurvePreferences == nil` via X25519MLKEM768) — services with regulatory FIPS requirements gain a stdlib path; services using non-default `CurvePreferences` need to opt into PQ. (e) Pin the build toolchain in `go.mod` `toolchain` directive so reviewers know which version's runtime behaviors apply. (f) **Verify RPC/HTTP framework support for the target Go version before bumping the toolchain** — a runtime baseline is not a mandate to upgrade: frameworks lag (e.g. Kitex's supported Go range per `go-microservice-dev/references/scaffold-and-codegen.md`), so a Go 1.25 service on a framework that only validates 1.19–1.24 must confirm framework compatibility first.
+
+## Deployment Resources
+
+- Generate deployment manifests from typed inputs rather than hand-edited YAML fragments.
+- Validate CPU, memory, replica count, image, protocol, ports, and storage before applying a deployment.
+- Use stable naming rules for namespace, workload, service, and routing resources so cleanup and rollback are deterministic.
+- Separate service-level resources from lane-level resources:
+  - Service-level: namespace, internal service, gateway/mesh route, destination/routing policy.
+  - Lane-level: deployment, replica count, resource profile, optional storage, image.
+- Delete in safe order: (1) shift traffic weight to zero and deregister from service discovery first, (2) wait for in-flight drain (documented grace window), (3) snapshot or verify retention policy on any storage marked durable, (4) delete lane workloads, (5) delete storage only if explicitly tagged ephemeral, (6) finally remove service-level routing and discovery metadata. Deleting workload storage before draining traffic destroys data while requests are still in flight; the destination order matters more than the source order.
+
+## Gateway And Mesh Routing
+
+- Keep domain, host, path, and TLS configuration in typed dynamic config or IaC, not scattered in handlers.
+- Expand wildcard domains through a controlled domain registry and reject hosts not owned by the current environment.
+- Model route matches explicitly: prefix, exact, regex, method, header, and rewrite behavior.
+- Mesh routing should make lane selection observable through a header, tag, or resolver metadata, and should include a clear default route.
+- Canary routing should define both caller-based and percentage-based options when the platform supports them.
+- Any traffic config update should be atomic for one caller/callee/method route and protected by a write lock or compare-and-swap.
+
+## Release Governance
+
+- Risky changes should have an approval task that records service, lane, run id, pipeline/workspace, reviewers, required approval count, status, expiry, and decision records.
+- Approval must be permissioned: only assigned reviewers or explicitly authorized roles can approve or reject.
+- Approval state updates need a concurrency guard and a transaction covering reviewer decision plus task status.
+- Rejection should win immediately for production-impacting changes; expired approval tasks should fail closed.
+- CI/CD callbacks should be idempotent by run id and stage. Missing out-of-order data should be retried for a bounded time, then surfaced as an operations warning.
+- Notifications should include service, lane, stage, task, run id, trigger user, reviewers, status, and direct run URL.
+
+## Canary Verification
+
+- A canary is not only a traffic weight. It needs an evaluation window, target pods/instances, baseline comparison, and pass/fail report.
+- Compare canary against production or previous stable lane for:
+  - new error locations.
+  - abnormal error-count growth.
+  - latency or saturation regressions.
+  - restart count and readiness failures.
+  - domain metric regression when available.
+- Canary reports should include sample logs, counts, reason, and whether human confirmation is required.
+- Store canary task window by service and run id so repeated checks share one time boundary.
+- Default canary duration should be short enough for delivery flow but configurable per risk level.
+
+## Rollback And Launch Checklist
+
+- Rollback must cover image, route weight, dynamic config, DB schema compatibility, async messages, and external callbacks.
+- Feature flags should default to off or low-scope exposure for behavior changes that cannot be instantly rolled back.
+- Backward compatibility requirements:
+  - New code can read old and new data shape.
+  - Old code can tolerate new optional fields.
+  - Consumers can ignore unknown event fields.
+  - Producers keep old required fields until all consumers migrate.
+- Launch readiness needs named owners, alert routes, dashboard links, runbook, error budget threshold, and escalation path.
+- Debug endpoints and profiling must be internal-only and disabled or gated in public-facing environments.

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

@@ -0,0 +1,26 @@
+# Replay Comparison Architecture
+
+Use this when designing replay, shadow execution, migration confidence checks, response diffing, or dual-run validation.
+
+## Execution Model
+
+- Separate capture, replay, comparison, storage, and reporting.
+- Replays need durable job state, concurrency limit, timeout, delay policy, rate limit, target environment or lane, and cancellation policy.
+- Captured input must be redacted and bounded by size before storage.
+- Replay requests should preserve only approved headers and metadata; never replay credentials blindly.
+- Shadow execution must not commit side effects unless the target is explicitly isolated.
+
+## Comparison Policy
+
+- Define comparator selection by method, content type, schema, or route.
+- Generic JSON comparison should support ignored fields, custom field comparators, numeric tolerance, null handling, array handling, and type mismatch reporting.
+- Diff output should include field path, original value summary, replay value summary, diff type, score, and ignored status.
+- Comparison thresholds should be config driven and versioned.
+- Positive, negative, and neutral diffs should be classified only when the product has a defensible definition.
+
+## Retention And Reporting
+
+- Store aggregate job counts and paginated diff details separately.
+- Define retention for captured requests, replay responses, and diff artifacts.
+- Expose summary metrics: total, processed, success, failed, diff count, similarity, p95 replay latency, and error categories.
+- Treat replay as a confidence signal, not an automatic release approval unless acceptance gates are explicit.

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

@@ -0,0 +1,94 @@
+# Runtime Observability
+
+Use this when defining runtime identity, service discovery, logging, metrics, tracing, or debug exposure for a Go microservice product.
+
+## Runtime Identity
+
+- Define one service identity used consistently by logs, metrics, traces, service discovery, deployment metadata, and ownership records.
+- Runtime identity should include service name, service type, port, environment, lane, cluster, region or data center, instance id, pod or host id, and node address when available.
+- Environment/lane is deployment routing metadata, not authorization or resource identity.
+- Service tags should be low-cardinality and safe for metric dimensions.
+- Local development defaults are useful, but production startup should validate required runtime identity fields.
+
+## Environment And Lane Model
+
+- Keep these concepts separate:
+  - environment: local, test, staging, production.
+  - lane: baseline, canary, preview, feature lane, or other traffic slice.
+  - authorization/resource scope: data access and permission scope.
+- Lane should propagate through inbound HTTP, RPC metadata, async messages, and outbound clients.
+- Default lane fallback must be explicit. Avoid silently routing production-impacting calls to an unintended baseline.
+- Public APIs should not trust client-provided lane headers unless the caller is authorized to route traffic.
+
+## Service Discovery
+
+- Register service instances with service identity and environment/lane tags.
+- Internal clients should resolve through a discovery abstraction rather than hard-coded host lists.
+- Resolution policy should define:
+  - same-lane preference.
+  - baseline fallback behavior.
+  - healthy-only instance selection.
+  - local development proxy or direct-FQDN behavior.
+  - failure behavior when no instance remains.
+- Discovery tags must avoid high-cardinality values such as request id or user id.
+
+## Logging Contract
+
+- Every log line from request, RPC, worker, and job code should be able to carry trace/log id.
+- Context-aware logging is the default; global logging is only for startup/shutdown and process-level events.
+- Request and response body logging must be gated by config/environment and disabled by default for sensitive or high-volume paths.
+- Logs should include safe domain identifiers only when useful for operations.
+- Error logs should retain internal cause, operation name, dependency identity, and canonical error code where available.
+- Do not log credentials, tokens, signatures, raw secrets, or full third-party payloads unless redacted and explicitly enabled.
+
+## Metrics Contract
+
+- Use low-cardinality attributes: service, method/API/job, caller, callee, environment, lane, cluster, canonical error code.
+- Avoid raw path parameters, subject ids, resource-scope ids, request ids, free-form error strings, and payload values as metric labels.
+- Minimum server metrics:
+  - request count.
+  - latency histogram.
+  - success count.
+  - error count by canonical code.
+  - panic count.
+- Minimum dependency metrics:
+  - outbound request count.
+  - dependency latency.
+  - dependency error count.
+  - timeout count.
+- Minimum async metrics:
+  - queue lag.
+  - consume count.
+  - retry count.
+  - dead-letter or skip count.
+  - job duration and skipped-lock count.
+
+## Tracing Contract
+
+- Initialize tracing at the server boundary and attach service name, environment/lane, instance id, and host/pod information as resource attributes.
+- Propagate trace context through HTTP, RPC, MQ, and detached jobs where the protocol supports it.
+- Add logs as span events only when useful and bounded.
+- Mark spans as errors when canonical error severity crosses the service-defined threshold.
+- Sampling policy should protect hot paths from excessive cost while preserving errors and slow requests.
+
+## Debug And Profiling
+
+- Liveness, readiness, introspection, profiling, and generated documentation endpoints must have separate exposure rules.
+- Liveness can be public to the platform; profiling and debug endpoints should be internal-only or auth-gated.
+- Public bypass paths must be prefix-safe and reviewed with auth middleware.
+- Debug endpoints should identify the current service and runtime context without exposing secrets.
+
+## Metric Naming Convention
+
+- Architecture standardizes a metric name shape across the portfolio so cross-service dashboards and alerts compose without renaming: `{category}_{operation}_{suffix}` snake_case, where category names the surface (`kitex_server`, `kitex_client`, `hertz_server`, `mq_consumer`, `db_dal`), operation names what is happening, suffix names what is measured (`qps`, `latency`, `err_qps`, `success_rate`).
+- Names live in a single per-service or per-platform file (e.g., `metrics_name.go`); architecture review treats inline metric name literals scattered through business code as a finding.
+- The base label set for RPC metrics is fixed at the platform layer: `caller`, `caller_cluster`, `caller_env`, `caller_method`, `callee`, `callee_cluster`, `callee_env`, `method`, `err_code`. New labels are added only with cardinality review.
+- High-cardinality identifiers (user id, tenant id, request id, trace id) are forbidden as metric labels regardless of the apparent business need; they belong in traces and logs.
+- Latency bucket boundaries (or summary quantiles) are picked at the platform layer once and reused across services. Per-service bucket choices defeat cross-service comparison and SLO inheritance.
+
+## Logger Adapter And Trace Linkage
+
+- Pick one structured logger family (zap is the common backend choice) and provide per-framework adapters (Kitex `klog.FullLogger`, Hertz logger, GORM logger, MQ logger). The adapter responsibility is to match the framework's interface while emitting the same JSON shape and field names; do not let each framework pick its own log format.
+- Every application-facing logger call takes `ctx` and automatically emits a fixed set of trace-identity fields (`_trace_id`, `_span_id`, `_trace_flags`, `_logid` or the project's chosen four). Callers do not pass these manually.
+- The logger pairs with the active OTel span: warn/error logs add a `span.AddEvent(...)` so trace backends correlate without manual join; span status flips to error only at logical error boundaries (handler entry/exit, dependency call failure), not on every warn.
+- Resource attributes (`service.name`, `service.namespace`, `service.version`, `lane`, `pod.ip`, `pod.name`) are set once at process start through the OTel provider; per-call attributes belong on individual spans, not on the provider.

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

@@ -0,0 +1,76 @@
+# Service Scaffold
+
+## Required Surfaces
+
+A new service should make these surfaces explicit from the first useful version:
+
+- `go.mod` and module ownership.
+- Entrypoints for API, RPC, worker, and scheduled jobs as applicable.
+- `proto/` or `idl/` source contracts.
+- Generated contract output directory.
+- `config/` with typed structs and environment overlays.
+- `handler/`, `service/` or `logic/`, `domain/`, and `infra/` boundaries.
+- `infra/dal`, `infra/cache`, `infra/rpc`, `infra/mq`, and external clients as needed.
+- DI setup for production and tests.
+- Makefile or scripts for code generation, tests, lint/format, and local run.
+
+## Runtime Lifecycle
+
+- Entrypoints should return or register a cleanup function for servers, tracer providers, metrics exporters, log writers, DB pools, Redis clients, MQ clients, and background workers.
+- Startup should install middleware in a deterministic order, with context/identity established before authorization and recovery/error mapping wrapping domain handlers.
+- Shutdown should stop accepting traffic before closing dependency clients and should flush logs/metrics after worker shutdown.
+- Graceful shutdown needs an in-flight draining deadline and a forced-close policy after that deadline.
+- Health endpoints should be available early, but readiness should only pass after required config, secrets, service discovery, and critical clients are initialized.
+- Debug, profiling, and generated-doc endpoints must be internal-only, auth-gated, or disabled in production-facing environments.
+- Avoid background loops that cannot be stopped; every ticker, watcher, scheduler, and worker pool needs an owner and close path.
+
+## Code Generation Contract
+
+- Treat IDL, DB DDL, route docs, and DI provider declarations as source inputs.
+- Treat generated stubs, route files, model helpers, query builders, and DI output as generated outputs.
+- Every generator should have one documented command.
+- Commands must use repo-relative paths or environment variables, not personal absolute paths.
+- Generated files should carry a clear generated-file convention and should not be hand-edited during feature work.
+- When a generator is unavailable, record the exception in the change and keep the manual patch minimal.
+
+## Dependency Injection
+
+Organize providers by concern:
+
+- base: config, logger, metrics, secret clients, object storage, generic clients.
+- dal: DB proxy and table-specific repositories.
+- cache: Redis client, key builders, locks, rate limiters.
+- rpc/http clients: internal service clients and external API clients.
+- service/application: use-case services and orchestrators.
+- task/worker: async task handlers, scheduled jobs, backfill jobs.
+- transport: HTTP handlers or RPC service implementation.
+- test: a test application graph with fakes or local adapters.
+
+Keep DI output reproducible. Do not construct hidden global dependencies inside domain logic when a provider can declare them.
+
+## Config Shape
+
+- Use typed config structs for service-specific settings.
+- Separate static defaults from dynamic config.
+- Include timeout, retry, worker count, lock lease, object storage, DB, Redis, MQ, and external client settings where relevant.
+- Validate required config at startup.
+- Never put credentials directly into config; resolve via a secret provider.
+
+## Test Architecture
+
+- Fast tests should not require live DB, Redis, MQ, service discovery, or cloud credentials.
+- Integration tests that require live dependencies should be opt-in with tags, environment variables, or separate make targets.
+- Provide fakes for external RPC/HTTP clients and repositories where domain behavior can be tested without infrastructure.
+- Include at least one smoke test for DI wiring when the graph is non-trivial.
+
+## Option Precedence And Protocol Selection
+
+- Server and client constructors should expose default-options helpers and accept caller overrides that win on conflict. Document the precedence (caller appended after defaults wins) so framework defaults can be tightened over time without surprise breakage in services that have already chosen a different setting.
+- Pick the meta handler (or equivalent transport-attached metadata propagator) by transport protocol exclusively — gRPC and Thrift do not share one handler, even when the framework allows registering both. Architecture chooses the protocol per service; the binary should not switch at request time.
+- Conditional registry registration is an architecture decision, not a default: register at startup only when running in an environment the platform layer is meant to discover (online / canary / lane environments). Local-dev, short-lived test, and migration binaries must not register, or the directory pollutes.
+
+## Layered Aggregates And DI Composition
+
+- For non-trivial services, model the layered surface as embedded aggregates: `AllInfra` (config + DAL + cache + RPC/HTTP clients + MQ + external SDKs), `AllService` (use-case services that depend only on `AllInfra`), `AllLogic` (orchestrators that depend on `AllService` + may reach `AllInfra` for low-level access), and a top-level `Application` (handlers + workers + consumers).
+- Wire-style DI maps cleanly: one `inject/infra` provider set, one `inject/service`, one `inject/logic`, and a top-level `inject` that composes them. Dependencies always point downward; never let `inject/infra` import from `inject/service`.
+- Embedded aggregates are a convenience for composition, not for hiding dependencies. A service that needs DAL access should still depend on the specific repository interface, not on `AllInfra` directly, except at the composition root.

package/dist/assets/marketplace/plugins/ccl-skills/skills/go-microservice-architecture/references/source-evidence-map.md

@@ -0,0 +1,55 @@
+# Go Architecture Source Evidence Map (Methodology Template)
+
+This file describes the **shape** of source-evidence tracking for Go architecture extraction. Project-specific provenance (real repo names, branch state, dates, module counts, extraction logs) lives in the maintainer's private alias file at `~/.<host>/.private-aliases/<project>.yaml`, never in this shared skill tree — see `skill-extraction-workflow` Core Rule "Extraction lifecycle handoff".
+
+## Scope boundary
+
+This shared template contains reusable methodology only. Do not add concrete repository names, branch state, module counts, package descriptors, or extraction logs.
+
+## Source coverage dimensions (architecture-level)
+
+When extracting Go architecture guidance from a new source set, organize evidence by these dimensions:
+
+| Dimension | What to collect | What to extract at architecture layer |
+| --- | --- | --- |
+| Service boundary inventory | How services are split (by domain / by traffic class / by data ownership); inter-service contract count | Boundary criteria, when to split vs merge, ownership rules |
+| API/RPC contract shape | IDL formats in use, public-vs-internal API split, contract evolution practice | Contract-first discipline, additive evolution rule, public/internal split when stability needs differ |
+| Data ownership | Per-service write model, cross-service read patterns, migration discipline | Each service owns its write model; cross-service reads through API/RPC; relational source-of-truth for durable state |
+| Runtime platform | Service discovery, framework, dynamic config, secret management, observability, mesh | Workload identity, registry-based vs DNS-based SD, mesh ownership boundary, dependency client contracts |
+| Error / context contract | Error code enum, error mapping table, ctx propagation through all sync/async paths | Stable enum, framework error mapping, ctx-as-source-of-truth for correlation |
+| Reliability surfaces | Admission control, rate limit, backpressure, circuit breaker, idempotency, durable status | Reliability is architecture, not bolt-on; idempotency strategy; durable acceptance |
+| Background workers | Long-running job model, lease scope, retry policy, idempotency key, failure visibility | Worker design as first-class architecture; not "happens to run async" |
+| Generated code ownership | Generators in use, generation commands, ownership boundary between generated and hand-edited | Generated code is output, not source; generation commands documented and portable |
+| High-risk operations | Tenant/user data isolation, money/billing, write atomicity, audit/outbox | Fail-closed default for high-risk paths; durable status + reconciliation; audit/outbox atomicity |
+| External integrations | Third-party callbacks, public APIs, authorization scope isolation | Boundary rules: idempotent receivers, signature verification, scope isolation |
+| Release runtime | Deployment unit, mesh routing, canary, approval, rollback | Architecture surface, not afterthought; per-service rollback boundary |
+
+## Sibling-generalization mini-map (template)
+
+For each Go architecture extraction, record decisions across sibling skills:
+
+- `go-microservice-dev` — does the architectural rule have an implementation pattern? note in dev reference.
+- `python-service-architecture` — cross-language counterpart? mirror at architecture level.
+- `python-service-dev` — implementation counterpart?
+- `testing-strategy` — what test layer proves the architectural property?
+- `platform-observability` / `platform-service-connectivity` / `platform-release-engineering` — does the rule belong at platform layer instead?
+
+Decisions go in the private alias map alongside the per-batch extraction log.
+
+## Coverage discipline rules
+
+- Architecture extractions describe **decision criteria, invariants, ownership boundaries, and acceptance checks**. Implementation patterns go to `go-microservice-dev`.
+- Mark each dimension `pending` / `read` / `deep-read` / `excluded` / `unavailable` / `routed` with the actual artifacts inspected, in the private alias map.
+- Re-read source artifacts when changing rules; use `wording cleanup` / `no new source read` labels honestly.
+- For full-coverage claims, the private source register must be closed (every dimension has a status) before any "complete" claim is made.
+
+## Where the live provenance lives
+
+For the maintainer's current Go extraction project, see:
+- Private alias map: `~/.<host>/.private-aliases/<project>.yaml`
+- Per-batch extraction logs: `~/.<host>/skills/.extraction-work/<batch>-completion.md`
+- These files are never pushed to the shared skill tree.
+
+## Audit gate
+
+Before committing a change to this skill, run the private alias map's `audit_cmd` against the changed shared-skill files. Any hit on real repo names, branch states, dates, file counts, or business-domain nouns is either fixed or recorded as `known_debt` in the alias map. Pre-existing leakage may be grandfathered; new or modified content must remain zero-hit.

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

@@ -0,0 +1,38 @@
+# Workflow State Architecture
+
+Use this when designing durable task, async workflow, import/export, backfill, or scheduled processing state.
+
+## State Contract
+
+- Define state enum, terminal states, allowed transitions, retry policy, and ownership before handlers are written.
+- Keep allowed transitions in one table, diagram, or policy function so handlers do not invent their own rules.
+- Separate state, progress, result pointer, error metadata, retry metadata, and audit metadata.
+- Persist the task record before starting expensive work, background execution, or external artifact generation so process failure leaves an inspectable and repairable state.
+- Define duplicate handling for every entrypoint: create, start, process, fail, succeed, cancel, and retry.
+- Transitions that affect durable truth need compare-and-update, transaction, or lock.
+- Completion events should be published after durable state update and should be idempotent.
+
+## Processing Semantics
+
+- Create should be idempotent when the caller supplies an idempotency key or natural unique key.
+- Start should claim ownership before expensive side effects.
+- Process should re-check state after ownership is acquired.
+- Success should persist result data before publishing completion.
+- Failure should record canonical error code, safe message, retryable flag, retry count, and trace or log id.
+- Cancellation should define whether in-flight work is interrupted, allowed to finish, or marked for later stop.
+
+## Retry And Recovery
+
+- Retry threshold and backoff belong in policy/config, not inline literals.
+- Terminal state recovery must be explicit; ordinary retries should not move successful or cancelled tasks.
+- Delayed events and queue messages must re-check current state before acting.
+- Process restart should leave enough durable state to resume, retry, or safely skip.
+- Background goroutines, workers, and scheduled cleaners need panic recovery and a bounded cursor/batch model; long-lived loops should use stoppable tickers or an explicit process-lifetime owner.
+
+## Acceptance Checks
+
+- Illegal transitions are rejected or no-op according to a documented policy.
+- Duplicate messages, delayed messages, and concurrent processors produce one durable outcome.
+- Every terminal state includes enough result or error context for support and reconciliation.
+- Expensive background work cannot start without an inspectable durable task record or an explicitly documented non-durable rationale.
+- Worker, goroutine, scheduler, and cleaner paths have panic recovery, bounded scan/batch behavior, and a visible recovery or repair result.