voidmachine 0.0.0 → 4.0.0

package/core-assets/skills/void-merge/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: void-merge
+description: Vider la file des PR ouvertes sans casser le dépôt. Ordre par déblocage plutôt que par date, CI verte ET à jour, artefacts générés régénérés, conflits de contenu rendus à leur auteur. Use when merging pull requests.
+---
+
+# merge — voidcorp craftsman edition
+
+`void-implement` s'arrête à la PR ouverte. `void-autopilot` laisse à une personne les PR qu'il ne peut
+pas armer. Personne ne dit comment vider la file. Ce geste a l'air trivial jusqu'au moment où il ne l'est pas.
+
+**Attribution**: see `.source`.
+
+---
+
+## Ce que ce n'est pas
+
+Ce n'est pas une revue. Une PR entrant dans la file est supposée revue par un humain : cette skill
+décide de **mécanique**, jamais de qualité. Elle ne lit pas le diff pour juger le code.
+
+Elle ne force rien : pas de `--admin`, pas de force-push, pas de merge d'une PR rouge.
+
+---
+
+## Étape 1 — Lire la file, et savoir ce qui n'y entre pas
+
+Lister toutes les PR ouvertes vers la base visée, avec pour chacune : état de mergeabilité,
+conclusion de chaque check, base, brouillon ou non, auteur.
+
+Sortent de la file, sans discussion :
+
+- **La PR qui existe pour rester ouverte.** Une promotion permanente vers la branche de release
+  est verte et mergeable en continu ; la merger est la décision de contenu du cycle, et elle
+  appartient à un humain. La nommer dans le rapport, ne jamais la merger.
+- **Les brouillons.**
+- **Ce que l'utilisateur n'a pas visé** quand il a nommé un périmètre.
+
+Une file vide est un résultat, pas un échec : le dire et s'arrêter.
+
+## Étape 2 — Ordonner par déblocage, jamais par date
+
+L'ordre correct n'a aucun rapport avec le numéro ni l'ancienneté.
+
+1. **Une PR dont le contenu supprime la cause du conflit d'une autre passe avant elle.** Le cas
+   qui a motivé cette skill : la PR réparant le workflow de back-merge était en conflit
+   précisément parce que ce back-merge n'avait jamais tourné. Sans le back-merge d'abord, elle
+   restait bloquée pour toujours.
+2. À défaut de relation, **le moindre conflit d'abord** : ce qui se merge sans rien toucher, puis
+   ce qui demande une régénération.
+
+Chercher la relation explicitement : une PR en conflit avec la base, dont une autre PR ouverte (ou
+un geste manquant) explique le conflit, attend cette autre.
+
+## Étape 3 — Trois conditions pour merger, toutes nécessaires
+
+| Condition | Ce qu'elle écarte |
+|---|---|
+| Tous les checks **verts** | Un merge qui casse la base |
+| La branche **à jour** avec sa base | Des checks qui ont tourné sur une base disparue |
+| Le merge **propre** | Une résolution faite dans le noir |
+
+`BEHIND` n'est pas un feu vert. C'est le piège le plus courant : la CI est verte et la PR est
+mergeable, mais les checks portent sur un état qui n'existe plus. Remettre la branche à jour,
+**réattendre la CI**, puis merger.
+
+Ne jamais contourner un refus de la protection de branche : c'est le garde-fou, au bon endroit,
+et le seul qui connaisse l'état réel côté serveur.
+
+## Étape 4 — Résoudre le mécanique, rendre le contenu
+
+Deux natures de conflit, une seule automatisable.
+
+**Mécanique — un artefact généré.** Bundles, catalogues, index dérivés. On **régénère depuis les
+sources fusionnées**, jamais on ne choisit un côté. Un artefact choisi passe la CI et ment
+ensuite : il ne correspond plus à ses sources.
+
+**De contenu — deux intentions se croisent.** La boucle s'arrête sur cette PR et le dit. C'est un
+travail d'auteur.
+
+**Cas mixte** : un fichier généré qui porte aussi une décision, comme une version dans un
+manifeste. C'est du **contenu**. Le sens de la valeur décide, pas l'emplacement du fichier. Une
+version en particulier n'est jamais choisie à la main quand un outil de release la possède : la
+question devient « quelle branche fait autorité sur cette valeur », et elle se pose à l'humain.
+
+## Étape 5 — Boucler, puis rendre compte
+
+Merger une PR rend les suivantes `BEHIND` : la file bouge à chaque tour. Reprendre à l'étape 1
+tant qu'une PR **devient** mergeable.
+
+S'arrêter quand plus rien ne progresse, et rendre alors, pour chaque PR restante, la raison exacte
+du blocage — jamais « n'a pas pu être mergée ».
+
+Après le dernier merge, vérifier que la base est saine : la suite, les gates du dépôt, et l'état
+de la branche locale.
+
+---
+
+## Anti-rules
+
+- MUST NOT merger une PR dont un check n'est pas vert.
+- MUST NOT merger une PR `BEHIND` sans l'avoir remise à jour et avoir réattendu la CI.
+- MUST NOT merger la promotion vers la branche de release.
+- MUST NOT résoudre un conflit de contenu, ni choisir un côté d'un artefact généré.
+- MUST NOT utiliser `--admin`, ni force-pusher une branche protégée.
+- MUST NOT juger la qualité du code : la revue est un geste humain, déjà fait.
+
+## Composition
+
+- **Amont — `void-implement`** ouvre les PR que cette skill draine ; **`void-autopilot`** lui laisse celles qu'il
+  rend à une personne (chemin protégé, verdict non prouvé, branche qui déploie).
+- **Avec `void-verify`** : après le dernier merge, la base se prouve, elle ne se suppose pas.
+- **Avec `void-commit-discipline`** : un commit de merge dit pourquoi il a lieu, comme les autres.

package/core-assets/skills/void-merge/harness.yaml

@@ -0,0 +1,14 @@
+# Harness metadata for this skill. Not part of the Agent Skills
+# specification, and never copied into a consumer project: the SKILL.md
+# beside it stays portable and validates against the official six fields.
+# Read by this repository's graph, and by the installer for `runtimes`.
+kind: action
+owner: folpe
+runtimes: [claude, codex]
+enforcement:
+  floor: ci
+  inline:
+    claude: active
+    codex: active
+    hermes: ci-only
+eval_targets: [claude/anthropic/opus]

package/core-assets/skills/void-migrations/.source

@@ -0,0 +1,13 @@
+Sources for `void-migrations` skill (see `docs/plans/skill-audits/void-migrations.md` for full audit):
+
+- GoCardless "Zero-Downtime Postgres Migrations" — https://gocardless.com/blog/zero-downtime-postgres-migrations-the-hard-parts/ — foundation, locking analysis + two-phase patterns
+- Strong Migrations (Rails) — https://github.com/ankane/strong_migrations — rule catalog ported to TS/Drizzle
+- Drizzle migrations docs — https://orm.drizzle.team/docs/migrations — tactical syntax
+- Neon branching — https://neon.tech/docs/introduction/branching — test on dev branch first
+- Supabase migration patterns — https://supabase.com/docs/guides/cli/local-development
+- pgroll (Xata) — https://github.com/xataio/pgroll — multi-version online schema escape hatch
+- Postgres ALTER TABLE locking docs — https://www.postgresql.org/docs/current/sql-altertable.html
+
+Strategy: original. No single TS source covers this; combined the disciplined narrative (GoCardless) with the rule catalog (Strong Migrations) and the void-stack tactical layer (Drizzle + Neon).
+
+Companion hooks: migration-lint, migration-pr-template.

package/core-assets/skills/void-migrations/SKILL.md

@@ -0,0 +1,264 @@
+---
+name: void-migrations
+description: Zero-downtime Postgres migrations. Two-phase changes, batched backfills, locking analysis, banned DDL patterns, CONCURRENTLY indexes, dev branch test, immutable after merge. Use on DB schema changes.
+---
+
+# migrations — voidcorp craftsman edition
+
+A "simple" `ALTER TABLE ADD COLUMN NOT NULL DEFAULT 'x'` on a 10M-row Postgres table locks writes for minutes. A "harmless" `RENAME COLUMN` breaks active requests. This skill encodes the lessons so the first migration in a new project gets them too.
+
+**Attribution**: see `.source`. Foundation: GoCardless "Zero-Downtime Postgres Migrations" + Strong Migrations (Ruby) + Drizzle docs + Neon branching.
+
+---
+
+## The two-phase change pattern
+
+Risky DDL goes through TWO migrations + a deploy step in between:
+
+```
+1. Migration A — backwards-compatible schema change
+   (add nullable column / add new column / drop NOT NULL constraint)
+2. Deploy code that handles both shapes (old AND new)
+3. Backfill (batched, with progress logs)
+4. Migration B — tighten the constraint
+   (add NOT NULL / drop legacy column / rename / type swap)
+5. Deploy code that uses only the new shape
+```
+
+Doing it in one migration = lock contention + downtime.
+
+---
+
+## Migration PR body — mandatory template
+
+Every migration PR includes:
+
+```markdown
+## Migration safety
+
+- **Table affected**: <name>
+- **Approximate row count**: <number or "< 1k" / "10k–100k" / "100k–1M" / "1M+">
+- **Locking impact**: <AccessExclusiveLock / ShareLock / RowExclusiveLock>
+  - Estimated lock duration: <seconds / minutes — be conservative>
+  - Acceptable during business hours: <yes / no — if no, schedule>
+- **Backfill strategy**: <none / batched 10k per tx / online via pgroll>
+- **Rollback plan**: <how to back this out if it fails in prod>
+- **Tested on dev branch**: <Neon branch SHA / "pglite — table tiny" / N/A>
+```
+
+If any section is missing, the PR is incomplete. The companion hook `migration-pr-template` warns; `void-code-review` blocks.
+
+---
+
+## Banned DDL patterns
+
+### `NOT NULL` direct add — banned
+
+```sql
+-- banned
+ALTER TABLE orders ADD COLUMN status TEXT NOT NULL DEFAULT 'pending';
+```
+
+Two-phase:
+
+```sql
+-- migration A
+ALTER TABLE orders ADD COLUMN status TEXT;
+-- backfill (batched)
+UPDATE orders SET status = 'pending' WHERE status IS NULL AND id BETWEEN $1 AND $2;
+-- migration B
+ALTER TABLE orders ALTER COLUMN status SET NOT NULL;
+```
+
+### `RENAME COLUMN` direct — banned
+
+```sql
+-- banned
+ALTER TABLE users RENAME COLUMN email TO email_address;
+```
+
+Two-phase:
+
+```sql
+-- migration A
+ALTER TABLE users ADD COLUMN email_address TEXT;
+-- deploy code that dual-writes both columns
+-- backfill
+UPDATE users SET email_address = email WHERE email_address IS NULL AND id BETWEEN $1 AND $2;
+-- deploy code that reads from email_address
+-- migration B
+ALTER TABLE users DROP COLUMN email;
+```
+
+### Column type change on a large table — banned
+
+Forces a full table rewrite + AccessExclusiveLock. Two-phase via new column + backfill + swap + drop.
+
+### `DROP COLUMN` referenced by active code — banned
+
+Deploy code that ignores the column FIRST. Then DROP in a separate migration.
+
+### `CREATE INDEX` (blocking) on large table — banned
+
+```sql
+-- banned
+CREATE INDEX orders_status_idx ON orders (status);
+-- allowed
+CREATE INDEX CONCURRENTLY orders_status_idx ON orders (status);
+```
+
+`CONCURRENTLY` does not block reads/writes. Slower; safer.
+
+### Modifying a merged migration — banned
+
+Fix forward via a new migration. Existing environments have already applied the original; mutating it would diverge state.
+
+The companion hook `migration-lint` blocks edits to migration files whose SHA is in the merged history.
+
+---
+
+## Backfill discipline
+
+```typescript
+// pseudo-code — actual: in a Drizzle migration script
+async function backfillOrderStatus(db: Database) {
+  const batchSize = 10_000;
+  let lastId = 0;
+  while (true) {
+    const rows = await db.execute(sql`
+      UPDATE orders
+      SET status = 'pending'
+      WHERE status IS NULL AND id > ${lastId}
+      ORDER BY id ASC
+      LIMIT ${batchSize}
+      RETURNING id
+    `);
+    if (rows.length === 0) break;
+    lastId = rows[rows.length - 1].id;
+    logger.info({ lastId, batchCount: rows.length }, 'backfill_progress');
+  }
+}
+```
+
+- Each batch is its own transaction.
+- Batch size: 10k by default (tune per table).
+- Progress logged via structured logger (composes with `void-observability`).
+- Idempotent: rerunning resumes from `lastId`.
+
+---
+
+## Drizzle workflow
+
+```bash
+# generate from schema change
+drizzle-kit generate
+
+# HAND-REVIEW the produced SQL — drizzle-kit does not encode locking-aware patterns
+# adjust to two-phase where needed, add CONCURRENTLY for indexes, etc.
+
+# apply to dev branch
+bunx drizzle-kit migrate --config drizzle.dev.config.ts
+
+# integration test the migration (composes with void-tdd)
+bunx vitest run tests/migrations/
+
+# PR with the template
+```
+
+Auto-generated migrations are starting points, not deliverables.
+
+---
+
+## Testing migrations
+
+### Integration tests (composes with `void-tdd`)
+
+```typescript
+test('migration 0042 preserves existing order data', async () => {
+  const db = await createTestDb({ seed: 'pre-0042-snapshot.sql' });
+  await applyMigration('0042');
+  const order = await db.select().from(orders).where(eq(orders.id, knownId)).get();
+  expect(order.status).toBe('pending');
+  // ... assertions on preserved fields ...
+});
+```
+
+Tests run on pglite for small tables, on Neon dev branch for large ones.
+
+### Lock-impact dry run
+
+For migrations on tables > 100k rows, run on the dev branch with `pg_stat_activity` snapshot during the migration. Verify the actual lock acquired matches the predicted one.
+
+---
+
+## Rollback
+
+Forward-only is the default — but every migration PR states a rollback plan, even if it is "create a new migration that reverses the change."
+
+Some changes cannot be cleanly reversed (data loss on `DROP COLUMN`). Document that explicitly: "Rollback: only via point-in-time restore; this migration is one-way."
+
+---
+
+## When to escalate to online schema change tooling
+
+For tables > 100M rows or critical 24/7 surface, even two-phase may have a window of concern. Options:
+
+- **pgroll** (Xata) — multi-version schema, allows reading old shape while new shape exists
+- **pg_repack** — for table rewrites without lock
+- **pt-osc** — Percona, MySQL-flavor (we are Postgres, so less relevant)
+
+These are escape hatches. Default discipline (two-phase + batched backfill + CONCURRENTLY) covers > 95% of cases.
+
+---
+
+## Composition with other skills
+
+- **With `void-tdd`**: integration tests on pglite or Neon dev branch BEFORE merge.
+- **With `void-observability`**: structured logs at backfill progress; capture `pg_stat_activity` for long migrations.
+- **With `void-security-guidance`**: migration logs MUST NOT include PII.
+- **With `void-code-review`**: dimension `correctness` includes "lock analysis present, banned patterns absent, two-phase where required."
+- **With `void-commit-discipline`**: migration commits' "why" mentions the linked plan + the two-phase decomposition if applicable.
+- **With `void-plan`**: multi-migration schema changes flow through brainstorm + plans.
+- **With `void-domain-driven-design`**: schema changes are downstream of aggregate / value object decisions.
+
+---
+
+## Companion hooks
+
+- `migration-lint` (pre-commit on `<config.paths.migrations>`) — greps SQL for banned patterns; tags `// migration-allow: <reason>` for surgical exceptions. See `../../hooks/`.
+- `migration-pr-template` (pre-push when touching migrations) — warns if PR body lacks required sections.
+
+---
+
+## Anti-rules
+
+- MUST NOT auto-apply migrations on push to main (manual deploy approval).
+- MUST NOT amend a merged migration.
+- MUST NOT decide schema design (DDD's call).
+- MUST NOT skip the PR body template, even for "tiny" migrations.
+- MUST NOT silently allow banned DDL patterns.
+- MUST NOT skip the dev-branch test step.
+
+---
+
+## When you are stuck
+
+| Problem | Solution |
+|---|---|
+| Migration too risky for two-phase | Consider pgroll for multi-version schema. |
+| Backfill takes hours | Smaller batch size, run during off-peak, or pgroll. |
+| Cannot test on dev branch (no snapshot) | Use anonymized prod snapshot via Neon branching, or pglite for small tables. |
+| Need to fix a merged migration | Forward only — new migration that fixes. |
+| Locking analysis unclear | Run on dev branch with `pg_stat_activity` snapshot. |
+
+---
+
+## Final rule
+
+```
+Every migration → two-phase if risky, batched backfill, CONCURRENTLY for index, banned patterns absent,
+                  dev branch tested, PR template complete, immutable after merge.
+Otherwise → it is not voidcorp migrations.
+```
+
+The cheapest place to catch a downtime-inducing migration is before merge.

package/core-assets/skills/void-migrations/harness.yaml

@@ -0,0 +1,17 @@
+# Harness metadata for this skill. Not part of the Agent Skills
+# specification, and never copied into a consumer project: the SKILL.md
+# beside it stays portable and validates against the official six fields.
+# Read by this repository's graph, and by the installer for `runtimes`.
+kind: standard
+activation: always
+triggers:
+  globs: ["**/migrations/**", "**/*.sql"]
+owner: folpe
+runtimes: [claude, codex]
+enforcement:
+  floor: ci
+  inline:
+    claude: pretooluse
+    codex: pretooluse
+    hermes: ci-only
+eval_targets: [claude/anthropic/opus]

package/core-assets/skills/void-observability/.source

@@ -0,0 +1,12 @@
+Sources for `void-observability` skill (see `docs/plans/skill-audits/void-observability.md` for full audit):
+
+- pino — https://getpino.io — structured logger, fast, dev-pretty mode
+- OpenTelemetry semantic conventions — https://opentelemetry.io/docs/specs/semconv/ — attribute naming, trace/span model, W3C TraceContext
+- Charity Majors "Observability Engineering" — https://www.honeycomb.io/oreilly-observability-engineering — foundation: events over metrics, high-cardinality
+- Sentry best practices — https://docs.sentry.io — breadcrumbs, scopes, fingerprinting, beforeSend redaction
+- Cindy Sridharan "Distributed Systems Observability" — https://www.oreilly.com/library/view/distributed-systems-observability/9781492033431/ — three pillars composed not siloed
+- citypaul/.dotfiles observability notes — logger-only discipline, no console.log
+
+Strategy: distill. Stack-specific integration code in pack-nextjs-pwa (Sentry + pino + Vercel Analytics defaults). Skill mandates the discipline.
+
+Companion hook: no-console-log-grep.

package/core-assets/skills/void-observability/SKILL.md

@@ -0,0 +1,245 @@
+---
+name: void-observability
+description: Structured logs (no string interp), trace IDs end-to-end, error boundaries at async boundaries, anonymized user scope, no PII/secrets ever. Use @repo/core/logger not console.log. Use for prod code.
+---
+
+# observability — voidcorp craftsman edition
+
+Production debugging starts where observability ended. If you cannot see what happened, you cannot fix it; if you can only guess, you fix the symptom and the bug recurs. This skill codifies what to log, what to trace, what to measure — and just as critically, what NEVER to log (PII, secrets).
+
+**Attribution**: see `.source`. Foundation: pino + OpenTelemetry semantic conventions + Charity Majors "Observability Engineering" + Sentry best practices + Sridharan three pillars.
+
+---
+
+## Structured logs only
+
+```typescript
+// banned
+console.log('user ' + userId + ' did ' + action);
+logger.info(`user ${userId} did ${action}`);
+
+// allowed
+logger.info({ userId, action, durationMs }, 'user_action');
+```
+
+Structured logs are queryable. String-interpolated logs are searchable at best.
+
+The companion hook `no-console-log-grep` blocks `console.log` / `console.error` / `console.warn` in business code.
+
+### Use `@repo/core/logger` (pino)
+
+Provided by `pack-monorepo`. Business code imports `logger`, not pino directly — the adapter pattern lets us swap the backend later without business-code edits.
+
+```typescript
+import { logger } from '@repo/core/logger';
+
+logger.info({ userId, orderId }, 'checkout_started');
+logger.error({ err, orderId }, 'payment_failed');
+```
+
+### Levels (standard set, no custom levels)
+
+| Level | When |
+|---|---|
+| `fatal` | Unrecoverable — process must exit |
+| `error` | Operation failed; user impact |
+| `warn` | Unexpected but handled |
+| `info` | Significant business event |
+| `void-debug` | Developer-time signal |
+| `trace` | Very granular (rarely committed) |
+
+---
+
+## Trace IDs propagate end-to-end
+
+A user request crosses HTTP → service → DB → external API → response. The trace ID follows.
+
+```typescript
+// in pack-nextjs Server Action wrapper
+import { withTraceContext } from '@repo/observability';
+
+export const checkoutAction = withTraceContext(async (input: CheckoutInput) => {
+  const traceId = getTraceId();
+  logger.info({ traceId, cartId: input.cartId }, 'checkout_action');
+  // every downstream log inherits traceId via logger.child({ traceId })
+  return checkoutCart(deps, input);
+});
+```
+
+Composes with `void-async-safety` — the trace propagates across job / webhook / queue boundaries via the message envelope.
+
+### Default trace format
+
+W3C TraceContext (the OpenTelemetry default). Compatible with future vendor swaps (Sentry, Honeycomb, Datadog, OTel collector).
+
+---
+
+## Error boundaries at every async boundary
+
+### Client side (React)
+
+```tsx
+<ErrorBoundary
+  fallback={<ErrorView />}
+  onError={(err, info) => Sentry.captureException(err, { extra: info })}
+>
+  <Checkout />
+</ErrorBoundary>
+```
+
+### Server side
+
+```typescript
+async function callStripe(...): Promise<Result<Charge, StripeError>> {
+  try {
+    const charge = await stripe.charges.create(...);
+    return ok(translateCharge(charge));
+  } catch (err) {
+    logger.error({ err, customerId }, 'stripe_charge_failed');
+    return err({ kind: 'stripe_error', cause: serializeError(err) });
+  }
+}
+```
+
+The adapter (per `void-hexagonal-architecture`) is where the catch lives. The error is logged WITH context. Then re-rethrown as a typed `Result` error, OR (for truly unexpected) re-rethrown raw so Sentry catches it at the top.
+
+### Silent error swallowing — Red Flag
+
+```typescript
+// banned
+try { await doSomething(); } catch (e) { /* swallow */ }
+```
+
+Either log it, or rethrow, or both. `catch (e) {}` is rejected.
+
+---
+
+## High-cardinality attributes are valuable
+
+Majors' rule. Log:
+
+- User ID (anonymized — `userId: hash(realId)` for Sentry; raw in internal logs only if compliance allows)
+- Org / tenant ID
+- Feature flags active
+- Session ID
+- Browser / device / region
+- Business-meaningful tags (plan tier, signup source, conversion path)
+
+The cost is small. The benefit during investigation is "I can filter to the exact 12 users hit by this bug." Cardinality is not the enemy; pre-aggregation is.
+
+---
+
+## Metrics — what to emit
+
+| Metric | Why |
+|---|---|
+| Latency p50 / p95 / p99 per endpoint | User-perceived experience |
+| Error rate per endpoint | SLO tracking |
+| Business event counts (signup, checkout, conversion, churn) | Growth signal |
+| Queue depth / lag (jobs, webhooks) | Backlog detection |
+| Cost per business event (LLM tokens, third-party calls) | Composes with `void-llm-cost-discipline` |
+
+The skill mandates WHAT. The pack (`pack-nextjs`) provides HOW (Vercel Analytics + Sentry + custom emitters).
+
+---
+
+## Sentry integration (default)
+
+Provided by `pack-nextjs`. Defaults:
+
+- `Sentry.setUser({ id: hash(userId) })` — anonymized scope
+- `Sentry.addBreadcrumb` at every business event
+- `beforeSend` redacts known-secret keys + PII attributes
+- Fingerprinting by error class + message hash (deduplicates noise)
+- Performance monitoring at 10% sampling (head-based) in prod, 100% in dev
+
+Switch via `voidcorp.config.json` if a project chooses Highlight / OpenObserve / vendor X.
+
+---
+
+## No PII, no secrets, ever (composes with `void-security-guidance`)
+
+```typescript
+// banned
+logger.info(`user ${user.email} signed in with password ${password}`);
+
+// allowed
+logger.info({ userId: user.id, event: 'sign_in_success' });
+```
+
+### Logger config redacts at serialization
+
+`pack-monorepo` provides:
+
+```typescript
+const logger = pino({
+  redact: ['password', 'token', 'apiKey', 'secret', 'authorization', '*.email', '*.phone'],
+});
+```
+
+Defense in depth. The discipline says "don't log it." The config says "even if you slip, the serialized output drops it." Both layers must hold.
+
+---
+
+## What NOT to log
+
+- Full request bodies (PII / secrets / massive payloads). Log specific fields with explicit allowlist.
+- Passwords, tokens, API keys, session IDs, JWTs (composes with `void-security-guidance`)
+- Email addresses unredacted in production logs (consider hashing or partial redaction depending on compliance)
+- Full database rows (PII risk)
+- LLM full prompts / responses (PII + cost) — log token counts and structural metadata, not content
+- Stack traces with embedded secrets (some Node errors include the secret in the stack)
+
+---
+
+## Composition with other skills
+
+- **With `void-security-guidance`**: PII / secret redaction at log time. Logger config layer is defense in depth.
+- **With `void-debug`**: if visibility is the gap, FIX IT FIRST — add the missing logs / traces — then debug with real signal.
+- **With `void-async-safety`**: trace propagation across job / webhook / queue boundaries.
+- **With `void-hexagonal-architecture`**: error boundaries live at adapter boundaries; structured logging at use-case entry/exit.
+- **With `void-llm-cost-discipline`**: token counts logged at every LLM call site. Cache hit rate logged.
+- **With `void-code-review`**: flags missing observability (no log at use-case entry, no breadcrumb at business event, error swallowing).
+- **With `void-commit-discipline`**: `feat:` commits adding business logic mention the observability surface added.
+
+---
+
+## Companion hooks
+
+- `no-console-log-grep` (pre-commit) — fails if `console.log` / `console.error` / `console.warn` in staged business code. Allowed in `scripts/`, `**/*.test.{ts,tsx}` (with explicit allowlist marker). See `../../hooks/`.
+
+(Sentry / pino / OTel integration code lives in `pack-nextjs` because stack-specific.)
+
+---
+
+## Anti-rules
+
+- MUST NOT decide alerting policy (ops concern).
+- MUST NOT decide retention windows (compliance concern).
+- MUST NOT silently allow `console.log` in business code.
+- MUST NOT log PII or secrets.
+- MUST NOT swallow errors silently.
+- MUST NOT use custom log levels.
+
+---
+
+## When you are stuck
+
+| Problem | Solution |
+|---|---|
+| Cannot reproduce a bug in prod | Add observability first (logs / breadcrumbs / traces). Wait for next occurrence. |
+| Logger output is overwhelming | Add structured filters in the query, not at the source. The signal you do not log is the one you wish you had. |
+| Logging slows down a hot path | Async / batched log writes via the logger config. Pino is fast; the bottleneck is rarely the logger itself. |
+| Sentry too noisy | Fingerprint better, not "drop the breadcrumb." Noise is a tuning problem, not a discipline problem. |
+| LLM prompts too big to log | Log token counts + structural metadata (kind, length). Never the content. |
+
+---
+
+## Final rule
+
+```
+Production code → structured logs via @repo/core/logger, trace ID propagated, error boundaries present, no PII no secrets.
+Otherwise → it is not voidcorp observability.
+```
+
+Visibility is the precondition for everything. Earn it once; benefit forever.