voidmachine 0.0.0 → 4.0.0

package/core-assets/profiles/typescript.yaml

@@ -0,0 +1,39 @@
+schemaVersion: 1
+id: core:typescript
+version: 2
+name: typescript
+technologies:
+  - id: typescript
+    versionIndependent: true
+detectors:
+  always: false
+  technologies: [typescript]
+  files:
+    extensions: [.ts, .tsx, .mts, .cts]
+    names: [tsconfig.json]
+    pathSegments: []
+sources:
+  - title: TypeScript documentation
+    url: https://www.typescriptlang.org/docs/
+reviewedAt: 2026-07-27
+expiresAfterDays: 180
+invariants:
+  - Keep strict type checking enabled and validate untrusted runtime input.
+  - Prefer narrow types and pure helpers over assertions and ambient mutation.
+patterns:
+  - id: typed-source
+    appliesWhen:
+      technologies: [typescript]
+      files:
+        extensions: [.ts, .tsx, .mts, .cts]
+        names: []
+        pathSegments: []
+    guidance: Model domain states explicitly and keep unsafe narrowing at named boundaries.
+  - id: compiler-config
+    appliesWhen:
+      technologies: [typescript]
+      files:
+        extensions: []
+        names: [tsconfig.json]
+        pathSegments: []
+    guidance: Preserve strictness and verify the effective compiler configuration.

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

@@ -0,0 +1,15 @@
+Sources for `void-accessibility` skill (see `docs/plans/skill-audits/void-accessibility.md` for full audit):
+
+- WCAG 2.2 AA — https://www.w3.org/WAI/WCAG22/quickref/ — target level
+- Radix UI primitives — https://www.radix-ui.com — no hand-rolled a11y
+- Apple HIG touch targets — https://developer.apple.com/design/human-interface-guidelines — ≥ 44×44 minimum
+- WAI-ARIA Authoring Practices — https://www.w3.org/WAI/ARIA/apg/ — reference for custom widgets
+- axe-core — https://www.deque.com/axe/ — static analysis baseline
+- Folpe mobile-first dual-quality — PHILOSOPHY.md (this repo)
+- citypaul/.dotfiles a11y notes
+
+Strategy: distill. Compose with frontend-design (separate skill, vendored from Vercel plugin).
+
+Companion hooks: axe-precommit, viewport-screenshot-gate (shared with frontend-design).
+
+Stack-specific Tappable helper + Radix-wrapped @repo/ui + axe-core integration in pack-nextjs-pwa.

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

@@ -0,0 +1,275 @@
+---
+name: void-accessibility
+description: WCAG 2.2 AA floor. Radix primitives only, touch >=44x44, keyboard parity, semantic HTML, form labels, aria-live errors, mobile-first dual-quality. Use when building or modifying UI.
+---
+
+# accessibility — voidcorp craftsman edition
+
+A11y is not a launch-time audit. It is the default at every interactive surface. Radix handles the hard parts; we honor the rules. Mobile-first dual-quality means both viewports ship at first-class quality.
+
+**Attribution**: see `.source`. Foundation: WCAG 2.2 AA + Radix UI + Apple HIG + WAI-ARIA APG + Folpe mobile-first dual-quality.
+
+---
+
+## The floor
+
+WCAG 2.2 AA is the minimum. Not the goal — the floor. Specific projects (regulated, public-sector) may target AAA via `voidcorp.config.json` `wcag_level: 'AAA'`.
+
+---
+
+## Interactive primitives — wrap Radix
+
+```tsx
+// banned
+<div onClick={handleClick} role="button" tabIndex={0}>
+  Submit
+</div>
+
+// allowed (Radix base)
+<button onClick={handleClick}>Submit</button>
+
+// preferred (shadcn-style via @repo/ui, wraps Radix)
+import { Button } from '@repo/ui';
+<Button onClick={handleClick}>Submit</Button>
+```
+
+Radix provides focus management, keyboard nav, ARIA wiring. Hand-rolling these is the #1 source of subtle a11y bugs.
+
+For composite widgets (dropdown, dialog, popover, tooltip, tabs, accordion, slider, switch, toggle group, navigation menu) — use the Radix primitive. Period.
+
+The companion `void-code-review` flag catches raw `<div onClick>` / `<span onClick>` on interactive surfaces.
+
+---
+
+## Semantic HTML over ARIA
+
+```tsx
+// banned
+<div role="navigation">...</div>
+<div role="heading" aria-level={2}>Title</div>
+
+// allowed
+<nav>...</nav>
+<h2>Title</h2>
+```
+
+ARIA is the escape hatch for cases semantic HTML cannot express. The rule of least power: use HTML if it fits; reach for ARIA only when nothing else works.
+
+---
+
+## Contrast — AA minimum
+
+| Type | Minimum ratio |
+|---|---|
+| Normal text | 4.5:1 |
+| Large text (18pt+ or 14pt+ bold) | 3:1 |
+| UI components / graphical objects | 3:1 |
+
+The design system palette (in `pack-nextjs`) documents contrast ratios for every token combination. Tokens that fail AA are marked and not used for text.
+
+The companion hook `axe-precommit` runs axe-core on staged UI changes and flags AA violations.
+
+---
+
+## Touch targets — Apple HIG floor
+
+Every interactive element ≥ **44×44px**, regardless of viewport. Small icons are wrapped in a padded tap area.
+
+```tsx
+// banned
+<button className="p-1"><Icon size={16} /></button>
+
+// allowed (via @repo/ui Tappable)
+<Tappable onClick={...}><Icon size={16} /></Tappable>
+// Tappable enforces min-h-11 min-w-11 (44px) regardless of icon size
+```
+
+The `Tappable` helper (provided by `pack-nextjs`) enforces minimum dimensions via Tailwind classes.
+
+---
+
+## Keyboard navigation — parity with touch
+
+For every UI interaction reachable by touch, there is a keyboard equivalent:
+
+| Key | Action |
+|---|---|
+| Tab | Move focus forward |
+| Shift+Tab | Move focus backward |
+| Enter | Activate primary action |
+| Space | Toggle / activate (per native semantics) |
+| Escape | Close modal, popover, menu |
+| Arrow keys | Navigate inside composite widgets (Radix handles this for Tabs, Menu, Slider, etc.) |
+
+### Focus visible
+
+Every focusable element shows a focus ring. Tailwind: `focus-visible:ring-2 focus-visible:ring-primary` (or design-system token).
+
+### Banned
+
+```css
+/* banned */
+outline: none;
+```
+
+without an alternative focus indicator (`focus-visible:ring-*` or equivalent).
+
+---
+
+## Skip-to-content
+
+Every page with > 3 nav items has a skip-to-content link at the top:
+
+```tsx
+<a href="#main" className="sr-only focus:not-sr-only focus:fixed focus:top-2 focus:left-2 ...">
+  Skip to content
+</a>
+<main id="main">...</main>
+```
+
+The companion `@repo/ui` `Layout` component provides this by default.
+
+---
+
+## Forms
+
+### Labels associated
+
+```tsx
+// banned (placeholder as label)
+<input type="email" placeholder="Email address" />
+
+// allowed
+<label htmlFor="email">Email address</label>
+<input id="email" type="email" />
+
+// or, when label is visually hidden
+<label htmlFor="search" className="sr-only">Search</label>
+<input id="search" type="search" placeholder="Search..." />
+```
+
+Placeholder is NOT a label — it disappears on input, often fails AA contrast, and is handled inconsistently by screen readers.
+
+### Errors announced
+
+```tsx
+<label htmlFor="email">Email address</label>
+<input id="email" aria-describedby="email-error" />
+{error && (
+  <p id="email-error" role="alert" aria-live="polite">
+    {error.message}
+  </p>
+)}
+```
+
+Screen readers receive the update. Visual users see it too.
+
+---
+
+## Color is not the only signal
+
+Success / error / warning indicators combine COLOR + ICON + TEXT:
+
+```tsx
+// banned (color only)
+<span className="text-red-500">Failed</span>
+
+// allowed
+<span className="text-red-500 flex items-center gap-1">
+  <XCircleIcon className="h-4 w-4" aria-hidden="true" />
+  Failed
+</span>
+```
+
+Colorblind users get parity. The aria-hidden on the icon prevents it from being announced redundantly.
+
+---
+
+## Mobile-first dual-quality
+
+Every UI is designed mobile-first AND must reach first-class quality on both viewports simultaneously. (Folpe rule, documented in `.void/installed/PHILOSOPHY.md`.)
+
+### Concrete invariants
+
+- Layout starts at **360–390px** (iPhone 12 mini → iPhone 15 Pro), progressively enhanced wider.
+- Touch targets ≥ 44×44 on every interactive element regardless of viewport.
+- Keyboard navigation parity with touch.
+- Performance budget: LCP < 2.5s on slow 4G mobile AND on desktop fiber (measure with the project's perf tooling — Lighthouse CI, WebPageTest, bundlesize).
+- No mobile-only nor desktop-only features without an explicit decision recorded through the `void-decide` skill.
+- Both viewports screenshot-reviewed before merge.
+
+The companion `viewport-screenshot-gate` hook (shared with `void-frontend-design`) fails PRs lacking both screenshots.
+
+---
+
+## Reduced motion
+
+```css
+@media (prefers-reduced-motion: reduce) {
+  * { animation-duration: 0.01ms !important; transition-duration: 0.01ms !important; }
+}
+```
+
+The design system handles this by default in `pack-nextjs`. Specific animations may override with a reduced-motion variant.
+
+---
+
+## Banned
+
+- `<div onClick>` / `<span onClick>` on interactive elements
+- `outline: none` without a focus alternative
+- Placeholder text as label
+- Color as only indicator
+- Custom dropdown / modal / tooltip implementations (use Radix)
+- Auto-playing media with sound
+- `tabIndex="-1"` to remove from tab order without a reason (rare legitimate cases: programmatically focused after user action)
+
+---
+
+## Companion hooks
+
+- `axe-precommit` (pre-commit on UI changes) — axe-core static analysis, blocks on AA violations. ≤ 80 LOC.
+- `viewport-screenshot-gate` (pre-PR on UI changes, shared with `void-frontend-design`) — fails PRs lacking both mobile and desktop screenshots. ≤ 60 LOC.
+
+---
+
+## Composition with other skills
+
+- **With `void-frontend-design`**: shared mobile-first dual-quality invariant. `void-frontend-design` decides density / hierarchy / motion; this skill enforces a11y across them.
+- **With `void-code-review`**: dimension `correctness` includes a11y at the UI surface.
+- **With `pack-nextjs`**: provides `@repo/ui` (Radix-wrapped) + `Tappable` + axe-core integration + design system palette tokens.
+- **With `void-ui-review`**: its technical-audit pass includes the a11y dimension (contrast, keyboard, focus, 44px) — composes with this skill. Live-URL visual a11y audit is deferred to Vague 4.
+- **With `DESIGN.md`**: the design-system contract incorporates a11y constraints (produced by `impeccable document`/`init` or by hand).
+
+---
+
+## Anti-rules
+
+- MUST NOT decide visual design (color, typography, motion language).
+- MUST NOT silently allow `<div onClick>` on interactive surfaces.
+- MUST NOT permit `outline: none` without alternative.
+- MUST NOT skip dual-viewport verification.
+- MUST NOT permit color-only indicators.
+
+---
+
+## When you are stuck
+
+| Problem | Solution |
+|---|---|
+| Need a custom widget Radix does not have | Check WAI-ARIA APG patterns. Implement carefully. Add to design-system docs. |
+| Contrast token fails AA | Adjust the palette OR use a token marked for non-text usage only. |
+| Cannot tab into composite widget | Verify Radix primitive is used. Hand-rolled focus management is the #1 bug source. |
+| Touch target too small | Wrap in `Tappable`. |
+| Reduced-motion conflicts with critical animation | Document the exception + provide a non-motion alternative. |
+
+---
+
+## Final rule
+
+```
+Every UI → Radix primitive, AA contrast, ≥ 44px touch, keyboard parity, semantic HTML, form labels, dual-viewport verified.
+Otherwise → it is not voidcorp accessibility.
+```
+
+A11y is not a tax. It is the floor. Build on it; do not negotiate with it.

package/core-assets/skills/void-accessibility/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:
+  extensions: ["tsx"]
+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-api-and-interface-design/.source

@@ -0,0 +1,13 @@
+Sources for `void-api-and-interface-design` skill (see `docs/plans/skill-audits/void-api-and-interface-design.md` for full audit):
+
+- David Parnas "On the Criteria To Be Used in Decomposing Systems into Modules" (1972) — https://www.cs.umd.edu/class/spring2003/cmsc838p/Design/criteria.pdf — information hiding: a module exposes an interface and hides its design decisions; the contract is the stable surface, the implementation is replaceable.
+- Joshua Bloch "How to Design a Good API and Why It Matters" — https://www.infoq.com/presentations/effective-api-design/ (slides: https://static.googleusercontent.com/media/research.google.com/en//pubs/archive/32713.pdf) — "when in doubt, leave it out"; minimal public surface; make it hard to misuse; public APIs are forever.
+- Contract-first / API-first design with OpenAPI — https://swagger.io/resources/articles/adopting-an-api-first-approach/ — write the contract (spec) before the implementation; the spec is reviewable and consumable on its own.
+- Semantic Versioning 2.0.0 — https://semver.org/ — MAJOR breaks, MINOR adds, PATCH fixes; encodes the backward-compatibility promise and the deprecation discipline.
+- void-machine `void-hexagonal-architecture` skill — ports are interfaces the domain owns; this skill shapes those ports as seen from outside (it does not decide where the boundary sits).
+
+Strategy: distill. Parnas (information hiding) + Bloch (minimal, misuse-resistant surface) + contract-first (spec before code) + SemVer (versioning + deprecation cycle), rewritten for void-machine and composed with hexagonal-architecture, domain-driven-design, typescript-strict, functional, security-guidance, async-safety.
+
+Boundary: narrower than hexagonal-architecture (no layering / dependency direction) and DDD (no domain vocabulary). Owns only the design of a public contract: shape, misuse-resistance, boundary types, error contract, versioning.
+
+Companion hooks: none in v1 (versioning/compat discipline is guidance + code-review surface; a future contract-diff hook is an open question).

package/core-assets/skills/void-api-and-interface-design/SKILL.md

@@ -0,0 +1,231 @@
+---
+name: void-api-and-interface-design
+description: Contract-first design of any public interface — package exports, HTTP/REST, RPC/tRPC, SDK, module boundary. Minimal surface, stable boundary types, versioning. Use when shaping a public API.
+---
+
+# api-and-interface-design — voidcorp craftsman edition
+
+A public interface is a promise. The contract is the promise; the implementation is replaceable. Once a consumer depends on a signature, that signature costs you forever — every shape you expose is a shape you must keep working or deprecate on a schedule. This skill governs how you draw the contract of anything other code consumes: what it accepts, what it returns, how it fails, how it changes.
+
+Design the contract before the implementation. The implementation is private and free to churn; the contract is public and expensive to change.
+
+**Attribution**: see `.source` in this directory. Foundation: Parnas "information hiding," Bloch "How to Design a Good API," contract-first / OpenAPI, SemVer.
+
+---
+
+## Boundary with neighboring skills
+
+This skill is narrow. It does NOT cover layered architecture or domain vocabulary.
+
+| Concern | Owner |
+|---|---|
+| Where the boundary sits physically, dependency direction, ports vs adapters | `void-hexagonal-architecture` |
+| What the domain IS — bounded contexts, aggregates, ubiquitous language | `void-domain-driven-design` |
+| **The shape, stability, and versioning of a public contract — viewed from the outside** | **this skill** |
+
+A port (hex) is an interface the domain owns. This skill says how to draw that port well *as seen by its consumer*: minimal, hard to misuse, stable, versioned. Hex decides the port exists and which side owns it; DDD supplies the words inside it; this skill shapes the contract.
+
+---
+
+## Contract-first — the order of operations
+
+Before writing the implementation, write the contract down:
+
+1. **Signature** — the operations, their names (ubiquitous-language words, per `void-domain-driven-design`).
+2. **Input type** — exactly what is accepted, validated at the boundary.
+3. **Output type** — a dedicated boundary type, never an internal/DB row.
+4. **Error set** — the failures a consumer must handle, as values.
+5. **Invariants** — what the contract guarantees (idempotency, ordering, pagination).
+
+The contract is reviewable on its own, before a single line of logic. For HTTP/RPC this is the OpenAPI / schema spec; for a package it is the exported `.d.ts`; for a module it is the interface. Implementation-first design (writing logic, then "extracting" an API from whatever leaked out) is the anti-pattern this skill exists to prevent.
+
+---
+
+## Minimal surface — when in doubt, leave it out
+
+Everything public is a liability. You cannot un-ship a method without breaking someone.
+
+- Expose the smallest set of operations that satisfies the use case. Internal helpers stay un-exported.
+- A capability you are unsure about: keep it private. Adding later is non-breaking; removing later is breaking.
+- One way to do a thing, not three. Redundant entry points multiply the contract you must keep stable.
+
+Bloch's rule: *when in doubt, leave it out.* You can always add; you can rarely remove.
+
+---
+
+## Make it hard to misuse
+
+The best contract makes the invalid call fail to compile, not fail at runtime. Composes with `void-typescript-strict`.
+
+### Illegal states unrepresentable
+
+```typescript
+// BAD — caller can pass a window that ends before it starts
+function schedule(input: { startsAt: IsoDate; endsAt: IsoDate }): Result<Booking, ScheduleError>;
+
+// BETTER — a validated value object can only exist if valid
+function schedule(input: { window: TimeWindow }): Result<Booking, ScheduleError>;
+// TimeWindow's smart constructor (per domain-driven-design) refuses end < start
+```
+
+### No positional booleans, no bare primitives
+
+```typescript
+// BAD — call site reads createUser('a@b.co', true, false); nobody knows what true/false mean
+function createUser(email: string, isAdmin: boolean, sendWelcome: boolean): User;
+
+// GOOD — named options object + branded input types
+function createUser(input: {
+  email: Email;                       // branded, validated (domain-driven-design)
+  role: 'admin' | 'member';           // discriminated, not a boolean
+  welcome?: { send: boolean };
+}): Result<User, CreateUserError>;
+```
+
+Named parameters survive reordering and additions; positional booleans rot the moment a third flag appears.
+
+---
+
+## Stable boundary types — never leak the inside
+
+The types crossing a public boundary are part of the contract. Internal and DB types are not.
+
+- **No leaking ORM rows / DB models / framework request objects** across a public boundary. A schema change must not silently break a consumer.
+- **Dedicated boundary types (DTOs / branded types)**. They are mapped to/from internal types in the adapter (per `void-hexagonal-architecture`), exactly where translation already lives.
+- **Validate input at the boundary**. External input is untrusted; parse it into the boundary type with a schema (Zod) before anything else touches it. Composes with `void-security-guidance`.
+
+```typescript
+// boundary input parsed before it reaches the use-case
+const parsed = createUserRequestSchema.safeParse(req.body);
+if (!parsed.success) return badRequest(parsed.error);   // 400, no internal detail leaked
+const result = await createUser(deps, toCreateUserInput(parsed.data));
+```
+
+The boundary type is a wall: internal churn stays internal, external input stays validated.
+
+---
+
+## Errors are part of the contract
+
+What can go wrong is as much a promise as what goes right. Consumers branch on failures; surprise failures are bugs you shipped.
+
+- **Typed results at the boundary** — return `Result<T, E>` where `E` is a closed, named set of failures. Composes with `void-functional`.
+- **Stable error identity** — a stable `code` (and a stable HTTP status for network APIs). Consumers match on the code, not on the message string.
+- **Non-sensitive messages** — never leak stack traces, internal IDs, SQL, or PII across the boundary. Messages are for humans; codes are for machines.
+
+```typescript
+type CreateUserError =
+  | { code: 'email_taken'; status: 409 }
+  | { code: 'invalid_email'; status: 400 }
+  | { code: 'rate_limited'; status: 429; retryAfterSec: number };
+```
+
+Adding a new error variant is additive only if consumers already have a default branch; otherwise it is a breaking change (see versioning).
+
+---
+
+## Versioning and backward compatibility
+
+A breaking change to a published contract is a broken promise to every consumer. SemVer encodes the promise: MAJOR breaks, MINOR adds, PATCH fixes.
+
+**Additive-first.** New optional field, new operation, new error variant behind a default branch — non-breaking, ship as MINOR.
+
+**Breaking requires a new version or a deprecation cycle.** Removing a field, renaming an operation, narrowing an input, tightening an output, changing an error code — all breaking. Either ship a new version (`/v2`, major bump) or run a deprecation cycle: **deprecate before you remove.**
+
+Deprecation cycle:
+
+1. Mark the old surface deprecated (`@deprecated` JSDoc / `Deprecation` header / changelog), point to the replacement.
+2. Ship the replacement alongside. Both work.
+3. Give consumers a window (a release count or a date).
+4. Remove in the next MAJOR only.
+
+Never shorten the cycle silently. A consumer that wakes up to a 410 they were never warned about is the failure mode this rule prevents.
+
+---
+
+## Network APIs — idempotency and pagination
+
+For interfaces crossing the wire, two contract terms earn their place when relevant. Composes with `void-async-safety`.
+
+- **Idempotency** — any non-`GET` a client may retry (a payment, a create) accepts an idempotency key, and the server guarantees one effect per key. Retries are inevitable on a network; the contract must make them safe.
+- **Pagination** — any collection that can grow is paginated from day one, with a stable cursor contract. Returning an unbounded list is a promise you cannot keep at scale, and adding pagination later is breaking.
+
+Both are decided at contract time. Retrofitting either breaks consumers.
+
+---
+
+## Rationalizations
+
+| Rationalization | Reality |
+|---|---|
+| "I'll design the API once the implementation works." | The implementation will leak its shape into the contract. Design the contract first; it is reviewable alone. |
+| "Expose it now, someone might need it." | Public surface is forever. Add when a real consumer appears; removing is the breaking change you cannot take back. |
+| "Returning the DB row is faster." | The row is your schema. A migration now silently breaks every consumer. Map to a boundary type. |
+| "A boolean flag is simpler than an enum." | Until the third flag. `fn(x, true, false)` is unreadable and reorder-fragile. Named options + unions. |
+| "Throwing is fine, callers can catch." | Thrown errors are invisible in the type. Consumers forget the catch. Typed `Result` makes failure part of the signature. |
+| "It's a small rename, no big deal." | A rename is a breaking change. Deprecate the old name, add the new, remove next major. |
+| "We'll add pagination when the list gets big." | By then consumers depend on the array shape. Adding pagination is breaking. Paginate from day one. |
+| "Internal API, compatibility doesn't matter." | If another module imports it, it has consumers. The promise still holds across the module boundary. |
+
+---
+
+## Verification
+
+Before a public interface is considered designed:
+
+- [ ] The contract (signatures, input types, output types, error set, invariants) was written and reviewed **before** the implementation.
+- [ ] Public surface is minimal — every exported symbol has a current consumer; helpers are un-exported.
+- [ ] No internal / ORM / framework type crosses the boundary; boundary uses dedicated DTOs or branded types.
+- [ ] All external input is validated at the boundary with a schema before use (composes with `void-security-guidance`).
+- [ ] Failures are a closed, typed `Result` set with stable codes (and stable HTTP statuses for network APIs); messages carry no sensitive detail.
+- [ ] No positional booleans; multi-arg calls use a named options object; primitives with semantics are branded.
+- [ ] The contract is versioned; any breaking change is gated behind a new version or a documented deprecation cycle (deprecate → coexist → remove next major).
+- [ ] For network APIs: retryable mutations accept an idempotency key; growable collections are paginated with a stable cursor.
+
+---
+
+## Composition with other skills
+
+- **`void-hexagonal-architecture`**: the domain owns ports (interfaces). Hex says the port exists and who owns it; this skill says how to draw that port well as seen from outside — minimal, misuse-resistant, versioned. Boundary types map to internal types in the adapter.
+- **`void-domain-driven-design`**: contract names come from the ubiquitous language. Input/output types reuse value objects (branded types) and aggregate identities. DDD names; this skill shapes the public face.
+- **`void-typescript-strict`**: branded types at the boundary, discriminated unions for inputs and error sets, `satisfies` for response shapes, exhaustive handling of the error union.
+- **`void-functional`**: `Result<T, E>` is the boundary return; the error set is a closed ADT.
+- **`void-security-guidance`**: external input parsed/validated at the boundary (Zod); errors carry no sensitive payload.
+- **`void-async-safety`**: idempotency keys and retry semantics for network mutations; pagination for growable reads.
+- **`void-devex-audit`**: this skill is the build-time floor (design a minimal, misuse-resistant, versioned contract); `void-devex-audit` is the audit-time ceiling that measures the shipped contract's developer experience (TTHW, error paths, docs, upgrade) after it deploys.
+
+---
+
+## Anti-rules
+
+- MUST NOT decide where the boundary sits physically or the dependency direction — `void-hexagonal-architecture`'s call.
+- MUST NOT define the domain model, bounded contexts, or aggregates — `void-domain-driven-design`'s call.
+- MUST NOT expose internal, ORM, or framework types across a public boundary.
+- MUST NOT break a published contract without a new version or a documented deprecation cycle.
+- MUST NOT design the API after the implementation (implementation-first).
+- MUST NOT decide the transport / framework / serialization library — pack concern.
+
+---
+
+## When you are stuck
+
+| Problem | Solution |
+|---|---|
+| Should this be public? | If no current consumer needs it, keep it private. Add later; never break later. |
+| Class, options object, or positional args? | More than one argument, or any boolean → named options object. |
+| How should failures surface? | Typed `Result` with a closed error set and stable codes. No throwing across the boundary. |
+| Is this change breaking? | Removing / renaming / narrowing input / widening required output / changing a code = breaking. Additive = safe. |
+| Need to remove a field consumers use? | Deprecate, coexist, remove next major. Never silent. |
+| DB type or boundary type? | Always a boundary type. The DB shape is private. |
+
+---
+
+## Final rule
+
+```
+Contract before implementation. Minimal surface. Stable boundary types.
+Errors typed. Breaking change → new version or deprecation cycle.
+Otherwise → it is not a voidcorp public interface.
+```
+
+The implementation is yours to change. The contract belongs to everyone who calls it. Treat it like a promise, because it is one.

package/core-assets/skills/void-api-and-interface-design/harness.yaml

@@ -0,0 +1,16 @@
+# 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
+triggers:
+  globs: ["**/src/index.ts", "**/openapi*.{yaml,yml,json}", "**/*.openapi.ts", "**/trpc/**/router.ts"]
+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-async-safety/.source

@@ -0,0 +1,13 @@
+Sources for `void-async-safety` skill (see `docs/plans/skill-audits/void-async-safety.md` for full audit):
+
+- Stripe "Designing robust webhook handlers" — https://stripe.com/blog/idempotency — foundation, idempotency keys, replay protection
+- Stripe webhook signing docs — https://docs.stripe.com/webhooks#verify-events — signature + timestamp window pattern
+- Outbox pattern (Microservices.io) — https://microservices.io/patterns/data/transactional-outbox.html — DB write + external notify in one transaction
+- Pat Helland "Life Beyond Distributed Transactions" — https://queue.acm.org/detail.cfm?id=3025012 — entity/activity/contracts framing
+- Bryan Cantrill talks on distributed-systems failure modes — mental model: assume re-delivery
+- GitHub webhook redelivery docs — https://docs.github.com/en/webhooks
+- n8n / BullMQ / Inngest docs — tactical references for queue / job patterns
+
+Strategy: distill. Principles from Stripe + Outbox + Pat Helland. Stack-specific implementations (BullMQ vs Inngest vs Trigger.dev) live in packs (pack-monorepo / pack-nextjs-pwa).
+
+Companion: pack wrappers (withWebhookSafety, withJobSafety, withCronSafety). domain_events outbox table schema in pack-monorepo. No new core hooks; code-review flags surface violations.