ring:migrating-to-lib-observability

What this skill does

# Migrate lib-commons Observability APIs to lib-observability

## When to use
- Application imports one or more lib-commons observability packages/symbols listed in the mapping table below
- Team decision to eliminate deprecation warnings from lib-commons shims
- lib-commons deprecation notices appear in IDE or go vet output
- Application no longer builds because lib-commons has removed observability APIs and source imports still reference them

## Skip when
- Application already imports lib-observability for all observability concerns
- Application has no imports of the lib-commons observability packages/symbols listed below
- Application is lib-commons itself

**Do NOT skip when:**
- "The app only imports log/ from lib-commons" → still migrate; log is an observability target
- "The app uses streaming/kafka" → streaming is out of scope; only observability packages and HTTP/gRPC observability middleware migrate
- "The app uses commons/opentelemetry for tracing bootstrap" → migrate when `lib-observability/tracing` exposes the target API (helper-only files first, bootstrap when type boundaries allow)
- "`go list` or `go build` fails because lib-commons removed the observability APIs" → still migrate; this skill performs static source rewrites against the known mapping table even when the source packages no longer exist

## Sequence
**Runs before:** (none)
**Runs after:** (none)

## Related
**Complementary:** ring:using-ring, ring:running-dev-cycle, ring:reviewing-code, ring:fixing-lint, ring:using-lib-commons

---

## Overview

This skill replaces imports/usages of lib-commons observability APIs
with their canonical lib-observability equivalents.

**Stable target baseline for this migration:**
- `github.com/LerianStudio/lib-commons/v5` >= `v5.2.0`
- `github.com/LerianStudio/lib-observability` >= `v1.0.0`
- `github.com/LerianStudio/lib-auth/v2` >= `v2.8.0` when present
- `github.com/LerianStudio/lib-license-go/v2` >= `v2.3.5` when present
- `github.com/LerianStudio/lib-streaming` >= `v1.3.1` when present
- `github.com/LerianStudio/lib-systemplane` >= `v1.0.0` when systemplane is used

`lib-commons/v5.2.0` is the first stable lib-commons release where the
deprecated observability shims are removed. `lib-observability/v1.0.0` is the
first stable lib-observability release. `lib-auth/v2.8.0` and
`lib-license-go/v2.3.5` are the first stable companion releases known to be
compatible with the removed lib-commons observability APIs. `lib-streaming/v1.3.1`
is the first stable streaming release in this validation set that no longer
imports removed lib-commons observability packages. `lib-systemplane/v1.0.0`
is the stable package destination for direct `commons/systemplane` imports
removed from lib-commons. Do not use beta tags for new migrations unless the
target application is intentionally pinned to a beta train.

**Known lib-commons observability removal refs:**
- Removal commit: `fe1db9e60ac9e959de4288208b6cf65f7bbfe439`
  (`refactor: remove deprecated commons observability shims`)
- First stable removal release: `v5.2.0`
- Pre-removal reference: `fe1db9e60ac9e959de4288208b6cf65f7bbfe439^`
  (currently `a33b160ac165cff8b4ddf5c69d8dbb80a10868f6`)

Use the pre-removal reference as the default source-evidence ref when the
effective lib-commons dependency has already removed the deprecated shims and
the user did not provide `lib_commons_pre_removal_ref`. That ref still contains
the `Deprecated:` notices while using lib-observability types internally.

**Targeting strategy:** migrate known observability APIs when the target API
exists in the effective lib-observability version. Source-side `Deprecated:`
notices are preferred evidence. Read them from the effective lib-commons version
when available; if a removal commit/ref is known, read them from the immediate
pre-removal lib-commons ref. If neither source is available because lib-commons
has already removed the package/symbol, the application may not compile, and the
skill must still migrate by static source analysis.

If a target API is missing from lib-observability, do not migrate that API.
Report the missing target and leave the lib-commons usage unchanged unless it is
already broken by removal; in that case report it as a manual migration blocker.

In removed-api mode, package-level imports such as `commons/log` can still
cross non-observability lib-commons boundaries (for example
`mongo.Config.Logger`, `postgres.Config.Logger`, `WithCORSLogger`,
`circuitbreaker.NewManager`, auth middleware, outbox/tenant-manager clients,
streaming builders, or any remaining lib-commons API typed as
`commons/log.Logger`). Do not invent adapters in the skill.
Migrate safe source files, run build validation, and if a file fails only
because a migrated value crosses a remaining lib-commons typed boundary, revert
that file/family to lib-commons and report it as a manual blocker.

Also check transitive dependencies after bumping lib-commons to a removal
release. If `go build` fails from `$GOMODCACHE` with errors such as
`no required module provides package github.com/LerianStudio/lib-commons/v5/commons/log`,
`commons/zap`, or `commons/opentelemetry`, the target repo was
migrated as far as local source allows, but one of its dependencies still
depends on removed lib-commons observability packages. First try the known
stable companion bumps when the modules are present:

```bash
GONOSUMDB="github.com/LerianStudio/*" \
GOPRIVATE="github.com/LerianStudio/*" \
  go get github.com/LerianStudio/lib-auth/[email protected] \
         github.com/LerianStudio/lib-license-go/[email protected] \
         github.com/LerianStudio/[email protected] \
         github.com/LerianStudio/[email protected]
go mod tidy
```

If the dependency is outside that stable set (for example `lib-auth/v3`,
`systemplane` packages removed from lib-commons, or a `lib-streaming` version
older than `v1.3.1`), first apply the known companion bumps and direct
systemplane import move. Then report only the remaining module/package as a
manual blocker; do not try to patch module cache files or vendor ad-hoc
replacements into the application.

Known repo-specific dependency drift:
- `matcher` may depend on `github.com/LerianStudio/lib-auth/v3` as a
  pseudo-version even though there is no stable lib-auth v3 release in this
  migration train. If that pseudo-version still imports removed lib-commons
  observability packages, do not rewrite it automatically. Report it as a
  dependency blocker and ask the executor whether they want to move matcher back
  to `github.com/LerianStudio/lib-auth/[email protected]` for this migration.

Packages that are NOT deprecated in lib-commons (e.g. non-observability
`commons/net/http` helpers, `commons/streaming`) are explicitly out of scope.

**What changes:** import paths and deprecated symbol qualifiers in `.go` files + `go.mod` dependency.
**What stays the same:** all non-deprecated lib-commons packages, including infrastructure
clients (`commons/postgres`, `commons/streaming`, etc.).

---

## CRITICAL: Role Clarification

| Who | Responsibility |
|-----|----------------|
| **This Skill** | Discover imports, plan replacements, validate, report |
| **Agent** | Apply file edits, run go mod, fix compilation errors |

---

## Import Mapping Reference

The lib-commons observability packages and their lib-observability replacements.
Match the source import with the module major already used by the repo
(`/v2`, `/v4`, `/v5`, etc.); do not require a lib-commons major-version bump
before migrating observability imports.

| lib-commons import | lib-observability replacement | Package name change? |
|---|---|---|
| `lib-commons[/vN]/commons/log` | `lib-observability/log` | No — qualifier stays `log` |
| `lib-commons[/vN]/commons/zap` | `lib-observability/zap` | No — qualifier stays `zap` |
| `lib-commons[/vN]/commons/runtime` | `lib-observability/runtime` | No — qualifier stays `runtime` |
| `lib-commons[/vN]/commons/assert` | `lib-observability/assert` | No — q