voidmachine 0.0.0 → 4.0.0

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

@@ -0,0 +1,312 @@
+---
+name: void-functional
+description: Pure-by-default, errors as values (Result<T, E>), discriminated unions for state, immutability defaults, functional core / imperative shell. Side effects at adapters. Use for data flow or state.
+---
+
+# functional — voidcorp craftsman edition
+
+The domain decides in pure code. The world translates in adapters. Expected failures are values, not exceptions. Choices are types, not flags. Immutability is the default; mutation earns its place.
+
+This is `void-hexagonal-architecture`'s boundary viewed through a different lens — Bernhardt's functional core / imperative shell. Inside the hexagon: pure. At the adapters: effects.
+
+**Attribution**: see `.source` in this directory. Foundation: Wlaschin "Domain Modeling Made Functional," Mark Seemann "Code That Fits in Your Head," Bernhardt "Functional Core, Imperative Shell," Khorikov.
+
+---
+
+## Pure by default
+
+A function is **pure** if (a) same input → same output, (b) no observable side effects.
+
+Most domain logic should be pure. Side effects (DB writes, network calls, logging, time, randomness) live at adapter boundaries — outside the pure core.
+
+### Pure-in-effect
+
+An async function that only `await`s injected ports is pure-in-effect: deterministic given the same ports. This is the practical equivalent of pure code in an async TS context.
+
+### Red Flag — side effect inside a "pure" function
+
+```typescript
+function calculateInvoice(order: Order): Invoice {
+  const id = randomUUID();              // RED FLAG — impure
+  const at = Date.now();                // RED FLAG — impure
+  fetch('https://analytics/...');       // RED FLAG — side effect
+  return { id, at, ... };
+}
+```
+
+Fix: inject the ports.
+
+```typescript
+function calculateInvoice(
+  deps: { ids: IdPort; clock: ClockPort },
+  order: Order,
+): Invoice {
+  return { id: deps.ids.newInvoiceId(), at: deps.clock.now(), ... };
+}
+```
+
+Now `calculateInvoice` is pure-in-effect: deterministic given the same `deps`.
+
+---
+
+## Functional Core / Imperative Shell (Bernhardt)
+
+All decisions happen in pure code (the "core"). All side effects happen in the "shell" (adapters).
+
+```
+shell (adapters) → core (pure decisions) → shell (effects)
+```
+
+The shell:
+- Reads from outside (HTTP request, DB row, queue message)
+- Calls the core with the relevant input
+- Writes the result back outside (HTTP response, DB write, queue publish)
+
+The core:
+- Takes typed input
+- Returns typed output (often `Result<T, E>`)
+- No I/O, no side effects, no time / randomness without an injected port
+
+This boundary IS the `void-hexagonal-architecture` boundary. Same line, different framing.
+
+---
+
+## Errors as values — `Result<T, E>`
+
+Expected failures (validation error, business rule violation, expected external failure) are values.
+
+The standardized shape, published in `@voidcorp/core/result`:
+
+```typescript
+type Result<T, E> =
+  | { ok: true; value: T }
+  | { ok: false; error: E };
+
+export const ok = <T>(value: T): Result<T, never> => ({ ok: true, value });
+export const err = <E>(error: E): Result<never, E> => ({ ok: false, error });
+
+export function map<T, U, E>(r: Result<T, E>, fn: (t: T) => U): Result<U, E> {
+  return r.ok ? ok(fn(r.value)) : r;
+}
+
+export function flatMap<T, U, E>(
+  r: Result<T, E>,
+  fn: (t: T) => Result<U, E>,
+): Result<U, E> {
+  return r.ok ? fn(r.value) : r;
+}
+```
+
+### Usage
+
+```typescript
+async function checkout(
+  deps: CheckoutDeps,
+  input: { cartId: CartId },
+): Promise<Result<OrderConfirmation, CheckoutError>> {
+  const cart = await deps.orders.findCartById(input.cartId);
+  if (!cart.ok) return cart;
+
+  const payment = await deps.payment.charge(cart.value.total);
+  if (!payment.ok) return err({ kind: 'payment_failed', cause: payment.error });
+
+  return ok({ orderId: cart.value.id, confirmedAt: deps.clock.now() });
+}
+```
+
+The signature tells the caller everything: the input is what it claims, the output is either the typed success or the typed failure, no exception hidden in the implementation.
+
+### Exceptions for the unexpected
+
+Exceptions remain for truly unexpected bugs (DB down, network timeout, invariant violation that should be impossible). Sentry catches them. Domain code does not litter `try/catch` for these.
+
+```typescript
+// expected business failure → Result
+function withdraw(account: Account, amount: Money): Result<Account, InsufficientFundsError>;
+
+// unexpected technical failure → throw, let it bubble
+async function chargeWithRetry(stripe: StripeClient, ...): Promise<Charge> {
+  // network errors, retries, etc. — exceptions are fine here
+}
+```
+
+---
+
+## Algebraic Data Types (sum types)
+
+A choice with N variants is a discriminated union. Not a flag bag.
+
+```typescript
+type Order =
+  | { kind: 'draft'; id: OrderId; items: LineItem[] }
+  | { kind: 'submitted'; id: OrderId; items: LineItem[]; submittedAt: IsoDate }
+  | { kind: 'confirmed'; id: OrderId; items: LineItem[]; confirmedAt: IsoDate; tableNumber: number }
+  | { kind: 'cancelled'; id: OrderId; reason: string; cancelledAt: IsoDate };
+
+// transitions are functions on specific variants
+function confirm(
+  o: Order & { kind: 'submitted' },
+  tableNumber: number,
+  now: IsoDate,
+): Order & { kind: 'confirmed' } {
+  return { kind: 'confirmed', id: o.id, items: o.items, confirmedAt: now, tableNumber };
+}
+```
+
+The compiler refuses `confirm(draftOrder, ...)`. State transitions are mechanical, exhaustive switches cover every case. Composes with `void-typescript-strict` exhaustive-switch enforcement and `void-domain-driven-design` aggregate state machines.
+
+---
+
+## Immutability defaults
+
+```typescript
+// preferred
+type User = { readonly id: UserId; readonly email: Email; readonly createdAt: IsoDate };
+const users: readonly User[] = [...];
+
+// updates produce new values
+const updated = { ...user, email: newEmail };
+const usersPlusOne = [...users, newUser];
+```
+
+Mutation in place is an exception:
+
+- Performance hot paths (large array transforms, with tests proving the win)
+- Builder-style construction inside a private scope (then `return` an immutable result)
+
+The companion `void-code-review` flags mutation in domain code without justification.
+
+---
+
+## No `null`
+
+`null` duplicates the optionality concept and creates `null | undefined` ambiguity. Banned.
+
+Use `T | undefined` with `exactOptionalPropertyTypes` semantics:
+
+```typescript
+type User = { id: UserId; email: Email; nickname?: string };
+//   nickname property may be absent OR present (with a value), never explicitly undefined or null
+```
+
+Or `Option<T>` (also in `@voidcorp/core`):
+
+```typescript
+type Option<T> = { kind: 'some'; value: T } | { kind: 'none' };
+```
+
+When to choose:
+
+- `T | undefined` for "may not be set yet" / optional configuration / props
+- `Option<T>` for domain optionality where you want to discriminate explicitly (and prevent forgetting to handle the `none` case via exhaustive switch)
+
+The companion hook `no-null-grep` warns on `null` literals in domain code.
+
+---
+
+## Composition over inheritance
+
+Build behavior by composing functions.
+
+```typescript
+// composition
+const sendWelcomeEmail = pipe(
+  buildEmailPayload,
+  withWelcomeTemplate,
+  withSignature,
+  send,
+);
+```
+
+A `pipe` helper is in `@voidcorp/core`:
+
+```typescript
+export function pipe<A>(value: A): A;
+export function pipe<A, B>(value: A, f1: (a: A) => B): B;
+export function pipe<A, B, C>(value: A, f1: (a: A) => B, f2: (b: B) => C): C;
+// ... up to ~10 stages, fully typed
+```
+
+Class hierarchies are an exception with a documented reason (framework integration, React error boundary).
+
+---
+
+## Banned (by default)
+
+### Effect-TS / fp-ts as runtime dependency
+
+Rejected as default. Available as opt-in via a future pack when a project needs structured concurrency, layered effects, or rich combinators.
+
+### Haskell-style point-free / monad transformers / `traverse` / `applicative`
+
+Reject as default vocabulary. Use plain TS function parameters and the minimal `Result` / `Option` / `pipe` helpers. Consumers reaching for richer combinators adopt fp-ts or Effect-TS as a pack.
+
+### `null`
+
+Banned in domain code.
+
+### Throwing for expected domain failures
+
+Use `Result<T, E>`. Throw only for the unexpected.
+
+### Currying as default
+
+Curry when partial application is actually used at multiple call sites. Otherwise plain multi-arg.
+
+### Side effects inside "pure" functions
+
+Inject ports.
+
+---
+
+## Companion hooks
+
+- **`no-null-grep`** (pre-commit) — warn on `null` literal in domain code (`config.paths.business`). Tag `// allow-null: <reason>` to suppress.
+
+(Most functional rules surface via `void-typescript-strict` enforcement and `void-code-review` flags.)
+
+---
+
+## Composition with other skills
+
+- **`void-typescript-strict`**: provides the type machinery (discriminated unions, exhaustive switches, branded types, `satisfies`). This skill says when to use them.
+- **`void-hexagonal-architecture`**: the boundary is the same. Functional core = pure domain inside hex. Imperative shell = adapters at the edge.
+- **`void-domain-driven-design`**: value objects as branded types + smart constructors returning `Result`. Aggregates as discriminated unions for stateful workflows. Always-valid domain.
+- **`void-tdd`**: pure functions are trivially testable. RED writes a property-style or example-based test; GREEN implements pure.
+- **`void-testing`**: pure functions need no mocks. Sociable tests by default.
+- **`void-refactor`**: common moves — Replace Loop with Pipeline, Replace Conditional with Polymorphism (via discriminated-union dispatch), Replace Throw with Result, Extract Pure Function.
+- **`void-security-guidance`**: pure validation at trust boundaries returning `Result<Validated, ValidationError>`.
+
+---
+
+## Anti-rules
+
+- MUST NOT impose Effect-TS / fp-ts / monad transformers / point-free style as defaults.
+- MUST NOT decide where the functional / imperative split sits — that is `void-hexagonal-architecture`'s call.
+- MUST NOT decide what an aggregate is — that is `void-domain-driven-design`'s call.
+- MUST NOT decide test ergonomics — that is `void-testing`'s call.
+- MUST NOT silently allow side effects in supposedly-pure functions.
+
+---
+
+## When you are stuck
+
+| Problem | Solution |
+|---|---|
+| Should I throw or return Result? | Expected failure (validation, business rule) = Result. Unexpected (DB down) = throw, Sentry catches. |
+| Need time / randomness in pure code | Inject a ClockPort / RandomPort. Configure with a fake in tests. |
+| Discriminated union with 10 variants | Either: smaller domain (the cases are unrelated, separate types), or genuinely a 10-state machine — keep it, but document. |
+| Pipeline becomes 12 stages | Probably mixing concerns. Split into two pipelines, name the intermediate type. |
+| Need point-free for clarity | Try named partial application first. Adopt Effect-TS / fp-ts pack only if multiple use-cases benefit. |
+| Cannot avoid mutation | Confine it to a private scope. Return immutable result. Add a test proving the perf win if performance-driven. |
+
+---
+
+## Final rule
+
+```
+Pure by default. Errors as values. Choices as types. Effects at the boundary.
+Otherwise → it is not voidcorp functional.
+```
+
+The discipline is small. The payoff is exhaustively testable domain code and a typesystem that reflects what is actually true.

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

@@ -0,0 +1,15 @@
+# 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
+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-graph/.source

@@ -0,0 +1,15 @@
+Sources for `void-graph` (see `docs/plans/skill-audits/void-graph.md` for the full audit).
+
+Original to void-machine. It wraps this repository's own CLI, so there is no upstream skill to
+distil: the subject did not exist anywhere else.
+
+Provenance rather than inspiration: it was a slash command under `packages/core/commands/`,
+shipped there on 2026-06-04 because the plugin carried no in-session ergonomics at the time and a
+skill was not invocable from the keyboard. Claude Code has since merged commands into skills, and
+neither Codex nor Kimi ever had the command format, so the command was Claude-only for a reason
+that had expired. Converted on 2026-08-19, keeping its name and its `allowed-tools`, gaining
+`disable-model-invocation: true` — the gesture is typed by a human, never guessed by the model.
+
+Rejected while converting: letting the model invoke it on its own. A health check, an audit or a
+graph report that fires unprompted arrives when nobody asked and nobody acts on it, and it spends
+a screen doing so.

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

@@ -0,0 +1,80 @@
+---
+name: void-graph
+description: Read the installed harness as a graph and report what is dead, underused or expensive. No argument opens the local live studio; audit, cost and behavior print a terminal report.
+allowed-tools: Bash(void-machine:*) Bash(npx:*)
+---
+
+# void-graph
+
+The harness is a graph: skills, agents, hooks, and the edges between them. This reads that graph
+against what actually ran here.
+
+**Attribution**: see `.source`.
+
+---
+
+## When it fires
+
+Only when a human asks. It answers a question about the harness itself, not about the work in
+progress, and it costs a terminal for as long as someone reads it.
+
+---
+
+## Run it
+
+Everything goes through the CLI, which every install has:
+
+```
+void-machine graph audit      # dead, dead-hook, underused, low-yield components
+void-machine graph cost       # token weight per component
+void-machine graph behavior   # what actually fired, against what was declared
+void-machine graph live       # local studio, served on localhost, offline
+```
+
+`npx voidmachine graph <sub>` when the binary is not on PATH.
+
+For `live`, run it in the background so the session is not blocked, read the
+`serving on http://localhost:<port>` line, and give the human that URL.
+
+Everything is local. No npm, no network, no account. The analyzer reads the installed model and
+correlates it with this project's own events under `.void/machine/runs/*/events.jsonl`.
+
+> Do not reach for a path inside a plugin directory. The bundled analyzer used to be invoked
+> through the plugin-root variable, which a runtime substitutes for plugin assets only: on a local
+> install it stayed literal and pointed at nothing. The CLI is the one entry point that resolves
+> on every channel and every runtime.
+
+---
+
+## Read it
+
+Say what the report flags, and say what the reading can support:
+
+- **dead / dead-hook** — declared and never observed. Which is a statement about the observation
+  window, not about the component's worth. Give the window.
+- **underused / low-yield** — observed rarely, or observed often for little effect.
+- **expensive** — carries token weight out of proportion to what it returns.
+
+Every finding is **advisory**. It is a candidate for trimming or tuning, never an instruction,
+and nothing is applied from here.
+
+If the report says the data is insufficient, that is the answer: the activation meter needs
+enough sessions before absence means anything. `--min-sessions 1 --min-events 1` previews on a
+single session and should be labelled as a preview when you show it.
+
+---
+
+## Red flags
+
+| Rationalization | Reality |
+|---|---|
+| "It is dead, remove it" | It was not observed in this window. Removal is a human decision, taken with the reason it exists. |
+| "Insufficient data, the command failed" | It reported an absence of evidence, which is a real answer and often the useful one. |
+| "I'll run the bundled .mjs directly, it is faster" | That path only exists under a plugin install. The CLI resolves everywhere. |
+
+---
+
+## Composition
+
+Adjacent: `void-audit` proposes what to do about staleness; this shows the shape it sits in.
+Downstream: an accepted trim is filed through `void-learn`.

package/core-assets/skills/void-graph/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-hexagonal-architecture/.source

@@ -0,0 +1,12 @@
+Sources for `void-hexagonal-architecture` skill (see `docs/plans/skill-audits/void-hexagonal-architecture.md` for full audit):
+
+- Alistair Cockburn "Hexagonal Architecture" 2005 — https://alistair.cockburn.us/hexagonal-architecture/ — original ports + adapters definition
+- Bruno Boucard & Thomas Pierrain workshops/talks — testing strategy at the boundary
+- Herberto Graca "Explicit Architecture" — https://herbertograca.com/2017/11/16/explicit-architecture-01-ddd-hexagonal-onion-clean-cqrs-how-i-put-it-all-together/ — layered hex with use-cases
+- Gary Bernhardt "Functional Core, Imperative Shell" — DCDC 2012 talk — mental model twin of hex
+- Vladimir Khorikov "Enterprise Craftsmanship" — functional / architecture framing
+- citypaul/.dotfiles hex notes — cross-package import enforcement via tsconfig paths
+
+Strategy: distill. Reject DI containers, CQRS, mediator, event sourcing as defaults (per docs/PHILOSOPHY.md Wing Chun). Function-parameter injection only.
+
+Companion hook: boundary-direction-check (greps domain → infrastructure imports).