voidmachine 0.0.0 → 4.0.0

package/core-assets/skills/void-security-guidance/SKILL.md

@@ -0,0 +1,255 @@
+---
+name: void-security-guidance
+description: Default-secure at trust boundaries. Zod at every input, secrets via env, SQL parameterized, Better-Auth, LLM I/O untrusted. Escalate to security-audit for deep audits. Use on trust-boundary code.
+---
+
+# security-guidance — voidcorp craftsman edition
+
+Security is not "I will think about it later." It is the defaults applied at every trust boundary. This skill codifies the everyday discipline: validate at the boundary, never log secrets, never hand-roll auth, treat LLM I/O as untrusted. Full audit work is delegated to `void-security-audit`. This skill is the daily floor; `void-security-audit` is the periodic ceiling.
+
+**Attribution**: see `.source`. Distilled from citypaul + OWASP cheat sheets; the deep-audit ceiling lives in `void-security-audit`.
+
+---
+
+## Trust boundaries — the unit of discipline
+
+A trust boundary is a place where data crosses from untrusted to trusted (or vice versa). Examples:
+
+- HTTP request → Server Action (untrusted body → typed command)
+- Webhook → handler (untrusted signed payload → typed event)
+- Form input → service (untrusted form → typed input)
+- Third-party SDK response → adapter (untrusted external data → domain type)
+- LLM response → consumer (untrusted text → typed output)
+- File upload → storage (untrusted bytes → validated content)
+
+At every trust boundary, validate. With Zod. Without exception.
+
+---
+
+## Input validation — Zod at every boundary
+
+```typescript
+const CheckoutInputSchema = z.object({
+  cartId: CartIdSchema,
+  paymentMethod: z.enum(['card', 'bank_transfer']),
+});
+
+export async function checkoutAction(formData: FormData) {
+  const raw = Object.fromEntries(formData);
+  const parsed = CheckoutInputSchema.safeParse(raw);
+  if (!parsed.success) return err({ kind: 'invalid_input', issues: parsed.error.issues });
+  return checkoutCart(deps, parsed.data);
+}
+```
+
+### Banned
+
+- `JSON.parse(req.body)` without schema validation
+- `req.body as MyType` type assertions
+- "Validation happens later in the service" — by the time the service runs, the boundary was crossed
+
+### Composes with `void-typescript-strict`
+
+The validated output is a typed value (often a branded type). No `as` cast required after `safeParse`.
+
+---
+
+## Secrets — env vars only, validated, never logged
+
+### Allowed
+
+```typescript
+// in @repo/core/env (or pack-monorepo provided env module)
+const env = createEnv({
+  server: {
+    STRIPE_SECRET_KEY: z.string().min(1),
+    DATABASE_URL: z.string().url(),
+  },
+  // ...
+});
+```
+
+### Banned
+
+- `process.env.STRIPE_SECRET_KEY` directly in business code (use `env.STRIPE_SECRET_KEY` instead)
+- Hardcoded secrets, even in fixtures
+- Secrets in commit messages, in logs, in error messages, in Sentry breadcrumbs
+- Secrets in `.env.local` files committed to git
+
+### Exception — customer-provided credentials (BYO key)
+
+"Secrets via env" governs the application's OWN secrets (its Anthropic key, its master encryption key, its data-source keys). A credential supplied by a customer (a BYO API key, e.g. a per-tenant data-source key) is application **data**, not the app's infra secret. Env does not fit: it holds one value, not one-per-tenant, and a multi-tenant app cannot scale a customer key into env.
+
+Store a customer-provided credential as data:
+
+- **Encrypted at rest in the DB, scoped per tenant** (AES-256-GCM), never plaintext — a DB dump must not leak every customer's credential.
+- **The master encryption key stays in env** (validated `@repo/core/env`). The per-tenant ciphertext lives in the DB.
+- **Never returned to a client surface** — expose a masked last-four only, never the full value.
+
+This narrows the rule; it does not weaken it. The app's own secrets still go in env, never the DB.
+
+### Composes with
+
+- `void-observability` — secrets MUST NOT appear in logs. The logger config redacts known-secret keys.
+- `pack-monorepo` — provides the `env` module + `gitleaks` pre-commit hook.
+
+Companion hooks (in `pack-monorepo`):
+
+- `gitleaks-precommit` — already in void-starter
+- `no-process-env-grep` — fails if `process.env.` appears outside `env.mjs`
+
+---
+
+## SQL / DB — parameterized via Drizzle, no string concat
+
+```typescript
+// allowed
+const user = await db.select().from(users).where(eq(users.id, userId)).get();
+
+// banned
+const user = await db.execute(sql.raw(`SELECT * FROM users WHERE id = '${userId}'`));
+```
+
+Composes with `void-migrations` for schema changes.
+
+### Raw queries
+
+Allowed only with explicit boundary review (a `BLOCKER:` review comment must be addressed). When unavoidable, parameterize:
+
+```typescript
+const result = await db.execute(sql`SELECT * FROM users WHERE id = ${userId}`);  // sql template literal — parameterized
+```
+
+---
+
+## Auth — Better-Auth (or Clerk opt-in), never hand-rolled
+
+Better-Auth is the default in `void-starter`. Clerk is the alternative (opt-in). Both handle:
+
+- Password hashing (argon2 / bcrypt)
+- Session token generation
+- CSRF protection
+- Cookie security (`HttpOnly`, `Secure`, `SameSite`)
+- Account lockout / rate limiting
+
+### Banned
+
+- Hand-rolled password hashing
+- Custom session token generation
+- Custom CSRF handling
+- "I just need a quick login for the demo" — use the real auth even for demos
+
+If a feature requires auth-related behavior that Better-Auth does not provide, that is a `void-brainstorm` discussion + an ADR — not a workaround.
+
+---
+
+## Cookies — defaults from pack-nextjs
+
+`HttpOnly`, `Secure`, `SameSite=Lax` (or `Strict` for sensitive cookies). Never set a cookie directly without these defaults — the helper in `pack-nextjs` enforces.
+
+---
+
+## LLM input is untrusted. LLM output is untrusted.
+
+### Input — prompt injection
+
+User-controlled text inside an LLM prompt is an attack vector. Treat it as data, not instructions.
+
+- Separate the system prompt from user input clearly.
+- Sanitize where appropriate (markdown stripping, URL blocking).
+- Defense in depth: if the LLM has tools, every tool invocation re-validates inputs at its boundary (do NOT trust because "the LLM checked").
+
+### Output — LLM hallucination as untrusted
+
+LLM responses are untrusted output. Validate with Zod if you parse structured data. Never `eval()` LLM output. Never pass LLM output directly into `dangerouslySetInnerHTML`, `innerHTML`, SQL, shell commands.
+
+### Composes with
+
+- `void-llm-cost-discipline` — cost rules and security rules co-evolve at LLM call sites
+- `pack-nextjs` — Server Actions wrapping LLM responses validate before returning
+
+---
+
+## Banned constructs
+
+- `eval()`, `new Function(...)`, `setTimeout(string, ...)`, `setInterval(string, ...)`
+- `dangerouslySetInnerHTML` (with allowlist for sanitized markdown rendering — explicit review)
+- `child_process.exec` with user-controlled input (use `execFile` with arg array)
+- `fs.readFileSync(userPath)` without path validation
+- `fetch(userUrl)` from server-side without URL allowlist (SSRF)
+
+The companion hook `no-eval-fn-grep` blocks `eval(`, `new Function(` in staged code.
+
+---
+
+## Logs — no PII, no secrets, ever
+
+```typescript
+// banned
+logger.info(`user ${user.email} signed in with password ${password}`);
+
+// allowed
+logger.info({ userId: user.id, event: 'sign_in_success' });
+```
+
+Composes with `void-observability` (structured logs only, never string interpolation).
+
+Logger config (in `pack-monorepo`) redacts known-secret keys (`password`, `apiKey`, `secret`, `token`) at the serialization layer as defense in depth.
+
+---
+
+## When to escalate to `void-security-audit`
+
+This skill is the daily floor. Escalate to `void-security-audit` for:
+
+- Periodic deep audit (monthly): OWASP Top 10 walkthrough, dependency supply chain scan, threat model review, CI/CD pipeline security
+- High-stakes feature: payment surface, auth changes, PII handling
+- Pre-launch security gate
+- Incident response
+
+The `doctrine-critic` agent (in void-machine) flags trust-boundary code in a diff and routes the security pass to `void-security-audit`; `void-security-audit` runs the phase-driven deep audit.
+
+---
+
+## Composition with other skills
+
+- **With `void-hexagonal-architecture`**: trust boundary = adapter ingress. Zod validation happens at the adapter.
+- **With `void-typescript-strict`**: validated input is a typed value (branded type for primitives). No `as` cast.
+- **With `void-observability`**: structured logs, no PII / secrets, breadcrumbs scoped with anonymized user ID.
+- **With `void-async-safety`**: webhook signature verification, replay protection.
+- **With `void-llm-cost-discipline`**: cost rules and security rules co-evolve at LLM call sites.
+- **With `void-code-review`**: dimension `security` is delegated. `doctrine-critic` flags boundaries and `void-security-audit` does the deep pass.
+- **With `void-security-audit`**: full audit on demand. This skill is the daily floor; `void-security-audit` is the periodic ceiling.
+
+---
+
+## Companion hooks (in `pack-monorepo` per-stack)
+
+- `gitleaks-precommit` — secrets in staged diff
+- `no-process-env-grep` — `process.env.*` outside `env.mjs`
+- `no-eval-fn-grep` — `eval(`, `new Function(` in staged code
+
+(These live in `pack-monorepo` rather than `core/claude/hooks/` because they depend on the consumer having gitleaks installed and a specific `env.mjs` convention.)
+
+---
+
+## Anti-rules
+
+- MUST NOT replace `void-security-audit` full-audit mode (different scope).
+- MUST NOT decide threat model boundaries (escalates to `void-security-audit`).
+- MUST NOT pretend LLM input/output is trusted.
+- MUST NOT hand-roll auth, sessions, password hashing.
+- MUST NOT bypass Zod validation at trust boundaries "for performance."
+- MUST NOT log PII or secrets, ever.
+
+---
+
+## Final rule
+
+```
+Trust boundary → Zod validation. Secrets → env. SQL → parameterized. Auth → Better-Auth.
+LLM I/O → untrusted. Logs → no PII no secrets.
+Otherwise → it is not voidcorp security-guidance.
+```
+
+Security defaults are like seat belts: uncomfortable at first, unimaginable to drive without.

package/core-assets/skills/void-security-guidance/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-source-driven-development/.source

@@ -0,0 +1,12 @@
+Sources for `void-source-driven-development` skill (see `docs/plans/skill-audits/void-source-driven-development.md` for full audit):
+
+- void-machine CLAUDE.md / AGENTS.md hard rule — "Read the official documentation of any third-party tool BEFORE writing its config." This skill encodes that rule and makes it enforceable.
+- Anthropic Claude Code best practices — guidance to give the model current, authoritative context (point it at official docs / fetch real references) rather than relying on training recall, which drifts across versions. https://www.anthropic.com/engineering/claude-code-best-practices
+- "Ground decisions in the official, versioned docs" principle observed from the Claude Code team's own working style — verify the installed version, read its docs, distrust dated third-party tutorials. (practice / methodology, no single canonical URL)
+- gstack /defuddle — composed for clean-markdown reads of official documentation (strips nav/ads to load-bearing prose), preferred over raw WebFetch for doc pages. (gstack skill)
+
+Strategy: distill. The repo already states the rule in one line; this skill distills the load-bearing principles (version-match the docs, docs beat memory, official beats third party, cite the reference) and adds the harness-standard Rationalizations + Verification gate. No verbatim vendoring.
+
+Composition: upstream of plan (stack decisions grounded in current docs); with commit-discipline (the "why" carries the source citation); with decide (alternatives cite official docs). Contrast with memory-driven config.
+
+Companion hooks: none in v1 (citation is prose-level discipline; a future post-commit grep for an unsourced config diff is an open question in the audit note).

package/core-assets/skills/void-source-driven-development/SKILL.md

@@ -0,0 +1,158 @@
+---
+name: void-source-driven-development
+description: Ground every third-party config or API usage in the official docs for the installed version, not training memory. Verify the version; cite the reference when it helps. Use before writing any tool config.
+---
+
+# source-driven-development
+
+Training memory drifts. It blends three minor versions of a framework into one plausible-looking config that compiles, runs, and is subtly wrong: a renamed option, a removed flag, a default that flipped between majors. This skill makes the official documentation of the **installed version** the source of truth for any third-party tool. The read is mandatory; the citation is not. Where a choice is not obvious, a brief reference in the commit lets the "why" outlive the session.
+
+This encodes the repo hard rule: *read the official documentation of any third-party tool before writing its config.*
+
+**Attribution**: see `.source` in this directory.
+
+---
+
+## The rule
+
+When you configure or call a third-party tool (framework, library, CLI, API, build tool):
+
+1. **Find the installed version.** Read the lockfile (`pnpm-lock.yaml`, `package-lock.json`, `Cargo.lock`) or the resolved entry, not just the `^x` range in `package.json`. Options change between majors; the range lies about what is actually resolved.
+2. **Read the docs for that version.** Pin the docs to the resolved major/minor. Latest-docs for an older installed version is a silent mismatch.
+3. **Prefer a clean read.** Use the `defuddle` skill (or WebFetch) on the official docs. Strip nav and ads to the load-bearing prose. Distrust third-party tutorials, blog posts, and Stack Overflow answers: they are dated by construction and rarely say which version they target.
+4. **Cite when it helps.** For a non-obvious choice, put the URL + section (or doc path) in the commit body, the PR, or a comment next to the config, so the next reader can re-derive it. A missing citation never blocks on its own.
+
+Memory proposes; docs dispose.
+
+---
+
+## Conflict resolution
+
+| Conflict | Winner | Why |
+|---|---|---|
+| Memory vs official docs | Docs | Memory is a lossy average of many versions; docs describe one. |
+| Two sources disagree | Official + version-matched | Vendor docs for the installed version beat any third party. |
+| Docs vs a stale tutorial | Docs | Tutorials freeze a moment; the tool moved on. |
+| Latest docs vs installed-version docs | Installed-version docs | You ship what is installed, not what is newest. |
+
+When the docs and a working example genuinely conflict and you cannot resolve it, that uncertainty is a finding: surface it, do not paper over it with a guess.
+
+---
+
+## What "cite the reference" looks like
+
+In a commit (composes with `void-commit-discipline` — the "why" carries the source):
+
+```
+chore(build): set vite `build.target` to es2022
+
+Vite 7 dropped the old `esbuild.target` shorthand; the documented field
+is now build.target. Ref: vitejs.dev/config/build-options#build-target
+(v7 docs, matches pnpm-lock resolved 7.0.x).
+```
+
+Next to non-obvious config:
+
+```ts
+// retries default changed to 0 in playwright 1.45; opt back in explicitly.
+// ref: playwright.dev/docs/test-retries (v1.45 docs)
+retries: 2,
+```
+
+What verifies a config line is the read of the version-matched docs, not the presence of a citation. A reviewer who doubts an option checks it against those docs; a concrete mismatch is a defect, a missing reference is not.
+
+---
+
+## When this applies
+
+- Writing or changing any tool config (bundler, test runner, linter, ORM, CI, framework).
+- Calling a third-party API or SDK where parameter names, defaults, or auth flow matter.
+- Choosing options that differ across major versions.
+- Upgrading a dependency across a major (re-read; do not assume the old config carries).
+
+## When this does NOT apply
+
+- First-party code in this repo (you own it; read the source, not "docs").
+- Stable, well-internalized language built-ins where no version ambiguity exists.
+- Throwaway exploration you will delete (but the moment it lands, the rule applies).
+
+---
+
+## Offline / no-network
+
+Some runs have no egress: a sandboxed autonomous worker, an air-gapped CI step. You still must not write config from memory. Two moves keep the rule intact without opening the network:
+
+1. **Inject the doc, do not fetch it.** Treat the version-matched reference as an *input*, not a side effect: pass the doc text (or a curated, version-pinned excerpt committed to the repo) into the decision as a parameter — a port — and validate its shape at the boundary with Zod before you trust it (e.g. assert the option you are about to set actually appears in the supplied reference). This is functional core / imperative shell: fetching is an adapter concern, the choice logic takes the doc as data. It composes with `void-hexagonal-architecture` and `void-security-guidance` (untrusted input is validated at the edge).
+
+2. **If no version-matched doc is reachable and the semantics you are writing are genuinely uncertain, incur a `source-debt`.** A missing citation is not a source-debt. A `source-debt` is a short, honest note, in the commit body or the PR, naming exactly which `tool@version` option was authored offline and what remains uncertain about it. It is the alternative to guessing silently, not a mandatory field: a label or checkbox may carry it if the project uses one, but neither is the authority.
+
+What matters is the verification itself: the real uncertainty is resolved against the version-matched official docs before the change ships. Once that read is done, a note, label or checkbox not yet updated never blocks on its own. The offline bypass is for *authoring* without egress, never for *shipping* config whose semantics remain unverified.
+
+This widens egress by **zero** (decision A3): offline work defers the verification behind an explicit, reviewable IOU; it never reaches for the network it was denied.
+
+---
+
+## Composition
+
+- **Upstream of `void-plan`** — stack decisions in a plan must be grounded in current official docs, not remembered defaults. A plan step that pins a library cites the doc that justifies the choice.
+- **With `void-commit-discipline`** — the mandatory "why" in the commit body is where the source citation lives. The git log becomes the audit trail of *why this config*, traceable to a versioned doc.
+- **With `void-decide`** (pack-monorepo) — a structural tool choice becomes an ADR whose "Alternatives considered" cites the official docs of each option, not folklore.
+- **Contrast with memory-driven work** — the failure mode this skill replaces is writing config from training recall and only checking docs when it breaks. Invert that order.
+
+---
+
+## Rationalizations
+
+| Rationalization | Reality |
+|---|---|
+| "I know this API, I've used it many times" | You know an average of several versions. The installed one has its own truths. |
+| "The docs will just say what I already think" | Then the read costs seconds and confirms it. When they don't, you just dodged a bug. |
+| "It compiled / it ran, so it's right" | Wrong defaults compile fine. Deprecated-but-still-working options run fine. Until they don't. |
+| "This tutorial does exactly this" | Tutorials rarely state their version and rot silently. Match the vendor docs to your lockfile. |
+| "Checking the version is overkill for a config tweak" | The tweak that broke prod was a flag renamed between minors. The check is cheap. |
+| "I'll read the docs later" | Later never comes. The read happens before the line; a citation, when useful, lands in the same commit. |
+| "Latest docs are close enough" | "Close enough" between majors is how a removed option ships to prod. |
+
+---
+
+## Verification
+
+The work is not done until the source check is done. Before marking any third-party config or usage complete:
+
+- [ ] Installed version identified from the lockfile (not the `package.json` range).
+- [ ] Official docs for **that** version read (via `/defuddle` / WebFetch, not memory or a tutorial).
+- [ ] Every non-obvious option checked against that doc; cited briefly where it helps the next reader (never blocking on its own).
+- [ ] Any memory-vs-docs conflict resolved in favor of the docs, or surfaced as an open question if irresolvable.
+
+If the version check or the read is missing, the config is written from memory. That is the state this skill exists to prevent.
+
+---
+
+## Anti-rules
+
+- MUST NOT write tool config from training memory alone — read the version-matched docs first.
+- MUST NOT skip the installed-version check — the `^` range is not the resolved version.
+- MUST NOT cite a third-party tutorial as authoritative — the official, versioned doc is the source.
+- MUST NOT land config whose semantics were not checked against the version-matched docs. A missing citation alone is not that failure.
+- MUST NOT silently pick a side when sources genuinely conflict — surface the divergence.
+
+---
+
+## When you are stuck
+
+| Problem | Solution |
+|---|---|
+| Cannot find the official docs | Start from the package homepage / repo README, follow to the versioned docs site. Avoid SEO tutorials. |
+| Docs only cover "latest" | Check the changelog / migration guide for your installed major; or read the versioned docs branch / tag. |
+| Docs and a working snippet conflict | Trust the versioned official docs. If still unresolved, surface it as an open question, do not guess. |
+| The option I remember doesn't exist | It was renamed or removed. Read the migration guide for your major. |
+| No time to read everything | Read the one section governing the option you are setting. Targeted, not exhaustive. |
+
+---
+
+## Final rule
+
+```
+Third-party config → installed version found, version-matched official docs read, source cited when it helps.
+Otherwise → it was written from memory, and memory is not a source.
+```

package/core-assets/skills/void-source-driven-development/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: active
+    codex: active
+    hermes: ci-only
+eval_targets: [claude/anthropic/opus]

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

@@ -0,0 +1,15 @@
+Sources for `void-tdd` skill (see `docs/plans/skill-audits/void-tdd.md` for full audit):
+
+- DECLIK port — /Users/folpe/Developer/DECLIK/.claude/skills/tdd/SKILL.md (377 LOC, top-5%, distills the below)
+- superpowers/test-driven-development — Iron Law + Red Flags + Common Rationalizations
+- citypaul/.dotfiles tdd — TDD Evidence in commit history pattern
+- nizos/tdd-guard — https://github.com/nizos/tdd-guard — companion hook (PreToolUse Edit/Write, 10 bypasses)
+- Kent Beck "Test-Driven Development: By Example" (2002) — foundation
+- morodomi/tdd-skills — reviewed, rejected as primary (too rigid phase-by-phase commit gates)
+
+Strategy: port-DECLIK with three minimal stack-agnostic adaptations (paths/commands read from voidcorp.config.json, DECLIK-specific refs moved to pack-monorepo).
+
+Companion hook: packages/core/claude/hooks/tdd-guard.sh (94 LOC, all 10 bypasses).
+
+DEV-444 adaptation: frontend RED now targets component/hook/store/a11y/state behavior, requires a
+keyboard regression before E2E for interactive controls, and binds proof to the current diff.