ring:using-lib-systemplane

What this skill does

# ring:using-lib-systemplane

## When to use
Sweep mode:
- "Sweep the codebase for lib-systemplane opportunities"
- "Find where we hot-reload config DIY (SIGHUP, fsnotify, viper.WatchConfig)"
- "Audit this service for lib-systemplane adoption"
- "Find raw pgx LISTEN / Mongo change-stream watchers wired against config tables"
- "Detect v4 systemplane residue (Supervisor, BundleFactory, SYSTEMPLANE_* env vars)"

Reference mode:
- "What does lib-systemplane provide?"
- "How do I construct the client for Postgres / MongoDB?"
- "Show me Register vs RegisterTenantScoped"
- "Which read accessor should I use for a duration / int / bool?"
- "How do OnChange and OnTenantChange differ?"
- "How do I mount the admin HTTP surface safely?"
- "What does the test harness look like?"

## Skip when
- Working on non-Go services
- Working on frontend code
- Target codebase has zero hot-reloadable runtime knobs (everything is static env-var-at-startup config — DSNs, TLS material, listen addresses, secrets stay outside the plane)
- Task is documentation-only or non-code

## Related
**Migration partner:** `ring:migrating-to-lib-systemplane` — end-to-end 11-gate migration cycle. This skill is the **adoption/reference** counterpart; the migration skill is the **transformation pipeline**.
**Similar:** [[ring:using-lib-commons]], [[ring:using-lib-observability]], [[ring:using-runtime]], [[ring:using-assert]]

---

## Mode Selection

| Request Shape | Mode |
|---|---|
| "Sweep / audit / find DIY runtime config / migrate to lib-systemplane" | **Sweep** |
| "What does lib-systemplane provide for X?" | **Reference** |
| "How do I initialize / register / subscribe?" | **Reference** |
| "Replace our fsnotify + SIGHUP plumbing with lib-systemplane" | **Sweep** |
| "Wire admin routes onto our Fiber app" | **Reference** |

---

## Module Facts (lock-checked)

- **Module path:** `github.com/LerianStudio/lib-systemplane`
- **Go version:** 1.26.3+
- **Tenant context:** `github.com/LerianStudio/lib-commons/v5 v5.0.2` (via `tenant-manager/core`)
- **Observability:** `github.com/LerianStudio/lib-observability v1.0.0` (`log.Logger`, `tracing.Telemetry`, `runtime.RecoverAndLog`)
- **Dual backend:** Postgres 13+ (LISTEN/NOTIFY) **or** MongoDB 4.4+ (change streams; polling fallback for standalone deployments)
- **Provisioning:** migration-only via `systemplane.SchemaSQL()` + `systemplane.DefaultSeedSQL()` public artifacts. Runtime DDL hook (`runSchema`) was removed in v1.6.0. Consumers vendor the artifacts into their own SQL migration pipeline via the `make systemplane-ddl` generator pattern — see `ring:migrating-to-lib-systemplane` Gate 3.5 and `multi-tenant.md` §27 "Cold-tenant resolution"
- **License:** Elastic 2.0
- **Scope:** runtime-mutable knobs only — never bootstrap-only material (DSNs, TLS, listen addresses, secrets)

---

# SWEEP MODE

Orchestrate a 4-phase sweep. Each phase has a hard gate — do not proceed until the current phase produces its artifact.

```
Phase 1: Version Reconnaissance     → systemplane-version-report.json
Phase 2: CHANGELOG Delta Analysis   → systemplane-delta-report.json
Phase 3: Multi-Angle DIY Sweep      → 7 × systemplane-sweep-{N}-{angle}.json
Phase 4: Consolidated Report        → systemplane-sweep-report.md + tasks.json
```

## Phase 1: Version Reconnaissance

1. Read `go.mod` — search for `github.com/LerianStudio/lib-systemplane` and any v4-era `github.com/LerianStudio/lib-commons/v[34]/commons/systemplane` imports
2. WebFetch `https://api.github.com/repos/LerianStudio/lib-systemplane/releases/latest` — extract `tag_name`
3. Classify drift: `not-adopted` / `up-to-date` / `minor-drift` / `moderate-drift` / `major-upgrade` / `v4-residue`
4. If any `v4/commons/systemplane` or `Supervisor`/`BundleFactory` import survives → flag `v4-residue: true`
5. Emit `/tmp/systemplane-version-report.json`:
   `{adopted, pinned_version, latest_version, drift_classification, v4_residue, module_path}`

## Phase 2: CHANGELOG Delta Analysis

1. WebFetch `https://raw.githubusercontent.com/LerianStudio/lib-systemplane/main/CHANGELOG.md`
2. Extract entries between pinned_version (exclusive) and latest_version (inclusive). If not yet adopted, summarize the whole CHANGELOG.
3. Classify each entry: `new-api` / `breaking-change` / `tenant-feature` / `admin-feature` / `security-fix` / `performance` / `bugfix`
4. Cross-reference `MIGRATION_TENANT_SCOPED.md` for two-phase rolling-deploy implications when adopting tenant overrides
5. Emit `/tmp/systemplane-delta-report.json` with classified entries

## Phase 3: Multi-Angle DIY Sweep

### ⛔ STOP-CHECK BEFORE DISPATCH

Before emitting any Task call, count the explorers you intend to launch in this turn.
- Count MUST equal 7.
- If count < 7 → STOP. Do not partial-dispatch. Reconcile against the 7 angles below and try again.
- The 7 angles are the canonical sweep. No substitutions, no omissions.

### ⛔ MUST NOT trickle-dispatch

All 7 explorers leave in the SAME TURN, before reading any explorer output.

Forbidden sequences:
- Dispatch explorer 1 → read result → dispatch explorer 2
- Dispatch a subset → wait → dispatch the rest
- Dispatch follow-up explorers conditioned on partial output
- Loop sequentially over the angle list

If you find yourself about to dispatch an explorer in a turn AFTER any explorer has already returned a result → STOP. You violated parallel dispatch. Report the violation and mark the phase INCOMPLETE rather than completing the trickle.

### Self-verify after dispatch

After the dispatch turn, verify all 7 Task calls were emitted in that single turn. If fewer than 7 went out, the phase did NOT execute correctly. Mark INCOMPLETE and surface the dispatch failure — do NOT silently continue with a partial pool.

### Parallel dispatch — atomic batch

Emit all 7 Task calls in a SINGLE TURN, as one atomic batch.

**If your runtime exposes a `multi_tool_use.parallel` wrapper**, use it to dispatch the complete pool in one wrapped invocation. This is the canonical fan-out mechanism on OpenAI-style tool envelopes and on certain Anthropic SDK consumers — naming it explicitly activates parallel emission on runtimes where trickle-dispatch is the default behavior.

**If your runtime emits parallel tool_use blocks natively** (Claude Code with Claude models), `multi_tool_use.parallel` may not be needed — but naming it is harmless and serves as an enforcement anchor.

The STOP-CHECK, anti-trickle, and self-verify guards above remain binding regardless of which mechanism your runtime uses.

Dispatch all 7 explorer angles **in a single parallel batch**. Wait for all before Phase 4.

**Per-explorer dispatch** (`subagent_type: ring:codebase-explorer`):

```
## Target
<absolute path to target repo root>

## Your Angle
<angle number + name>

## Severity Calibration / DIY Patterns / Replacement / Migration Complexity / Version Context
<verbatim from the angle spec below>

## Output
Write findings to: /tmp/systemplane-sweep-{N}-{angle-slug}.json
Schema: { angle_number, angle_name, severity, migration_complexity,
  findings: [{file, line, diy_pattern, replacement, evidence_snippet, notes}],
  summary, requires_major_upgrade }
If no findings: write file with empty findings array and summary
"No DIY patterns detected for this angle".
```

### Angle 1 — SIGHUP / fsnotify .env reload (CRITICAL)

**DIY patterns to grep:**
- `signal.Notify(.*syscall.SIGHUP` paired with re-reading `.env`, YAML, or `os.Getenv` post-startup
- `fsnotify.NewWatcher()` watching config files
- Goroutines that `os.Open` a config file on a `time.Ticker`
- Any code path that re-loads env vars after `main()` has started

**Replacement:** `systemplane.NewPostgres` / `NewMongoDB` + `Register` + `Start` + `OnChange`. Per-key subscriptions replace the global reload pulse.

**Severity rationale:** SIGHUP/fsnotify reloads are racy by definition (no per-key fan-out, no validator, no audit trail). Hot-reload runtime config without observability is a class of silent misbehavior.

### An