voidmachine 0.0.0 → 4.0.0

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

@@ -0,0 +1,226 @@
+---
+name: void-learn
+description: Capture a lesson when it appears — a stated project rule, a recurring/deja-vu fix, an end-of-cycle pattern, or a harness gap. Routes to PROJECT-DOCTRINE, a GitHub issue, or nothing. HITL strict. Also the single door for harness feedback. Fires on "the harness should have X", "this hook is a false positive", "that skill is missing", a DX papercut worth filing, or any explicit request to send feedback about the harness itself.
+---
+
+# learn — voidcorp craftsman edition
+
+One intent — *capture a lesson before its context evaporates* — with three destinations. This skill replaces the former `compounding` + `capture-rule` + `harness-evolution` trio, which were three doors to the same action separated by ~200 lines of mutual boundary-policing. Here the first step is the routing decision; the three behaviors follow unchanged, each keeping its own strict Human-In-The-Loop gate.
+
+It writes nothing on its own. It names the lesson, decides where it belongs, and runs the matching capture — proposing every write and waiting for an explicit yes.
+
+**Attribution**: see `.source` (inherits compounding, capture-rule, harness-evolution).
+
+---
+
+## Step 0 — Recognize the signal (auto-trigger)
+
+Engage the moment any of these appears — you should not need to be asked:
+
+- **A stated rule** — imperative future ("always X", "never Y", "from now on Z"), a preference ("we don't do Y here", "I prefer X"), an anti-pattern callout ("stop doing Y"), or a memory request ("remember that Z", "n'oublie pas que").
+- **A recurring / deja-vu fix** — mid-work you catch yourself solving something *already seen*. That recognition means a pattern exists and was never captured.
+- **An end-of-cycle pattern** — a feature, bugfix, or refactor just merged; before the next task, spend two minutes extracting the reusable lesson.
+- **A harness gap** — "the harness should have caught this", a skill is missing, a rule is wrong, a hook false-positives, two skills overlap.
+
+Do NOT engage for: one-off task instructions ("fix this bug"), questions ("how do I X?"), information without imperative ("the API returns Z"), or vague future intent ("we might want X someday"). When unsure whether a signal is persistent, ask before capturing — better to skip than to spam the doctrine.
+
+---
+
+## Step 1 — Route (the one decision that matters)
+
+Name the lesson as a **generalization**, not the instance. Instance: "I fixed the null deref in `CheckoutSummary`." Pattern: "X always fails when Y." If you cannot state it in one sentence, it is an instance — drop it (see *When to drop*).
+
+Then decide the scope with one question: **"If I started a new unrelated project tomorrow, would this lesson still apply?"**
+
+| Answer | Scope | Destination | Branch |
+|---|---|---|---|
+| No — only this codebase | Project rule | `.void/PROJECT-DOCTRINE.md` | **A** |
+| Yes — every voidcorp project | Harness gap | GitHub issue on `voidcorp-core/void-machine` | **B** |
+| True but trivial / one-off | Disposable | nowhere | drop |
+
+**When the scope is genuinely ambiguous, ASK — never guess:**
+
+```
+This could go two places:
+  1. .void/PROJECT-DOCTRINE.md (this project only)
+  2. the harness itself (universal — a GitHub issue on void-machine)
+Which scope did you mean?
+```
+
+Wait for the answer. A universal rule must never land in a project doctrine, and a project quirk must never reach the tracker.
+
+---
+
+## Branch A — Project rule → `.void/PROJECT-DOCTRINE.md` (HITL strict)
+
+`PROJECT-DOCTRINE.md` is imported into every session via `@.void/PROJECT-DOCTRINE.md` in `CLAUDE.md`, so a captured rule takes effect on the next message. **Never write the file before confirmation.**
+
+### 1. Propose the wording in chat
+
+```
+Proposed rule capture:
+  Target file: .void/PROJECT-DOCTRINE.md
+  Section:     <the heading it goes under, verbatim; "new: <table name>" if created>
+  Wording:     <verbatim rule, imperative present>
+  Why:         <the user's reason, quoted; skip if none given>
+  Enforced by: <skill / hook that materializes it, or "manual review / code-review">
+Confirm? (yes / change wording / change section / skip)
+```
+
+### 2. Wait for an explicit yes
+
+Accept `yes / ok / go / vas-y / confirme / c'est ça`. Anything else — a question, silence, "maybe" — STOP and ask again. Silence is not consent.
+
+### 3. Write
+
+Append to the correct section of `.void/PROJECT-DOCTRINE.md`:
+
+```markdown
+- **<rule subject>**: <verbatim wording>.
+  - **Why**: <reason>.
+  - **Enforced by**: <skill / hook / manual review>.
+```
+
+Choose the section by meaning, then place it by what the file already holds (see *Section routing*).
+
+### 4. Confirm in chat
+
+State the file path and section, and note it is active from the next message via the import; remind the user to `git add .void/PROJECT-DOCTRINE.md` when ready. Commit as `docs(doctrine):` (never automatically).
+
+### Section routing
+
+This table is the only list of section kinds a project doctrine has. `docs/PROJECT-DOCTRINE-FORMAT.md` illustrates the shape of each one and uses the same names; it does not own a list of its own.
+
+| Section | Use for |
+|---|---|
+| **Project context** | Domain facts (users are TPE/PME French dirigeants; prod on Vercel + Neon). |
+| **Domain language** | A term this team uses with one precise meaning, so the agent uses the same word. |
+| **Quality bar** | What "done"/"shipped" means (anti-rustine, ASCII-only, no half-built features). |
+| **Hard rules** | Concrete, enforceable rules (@repo/core/logger not console.log, Zod at every boundary). |
+| **Forbidden patterns** | What this codebase paid for and will not reintroduce; reference the incident/ADR. |
+| **Trade-offs already decided** | Pointers to the project's decision records the agent must not re-litigate. |
+| **Open questions** | What the team has not decided yet, so the agent asks instead of guessing. |
+| **Project-specific skill routing** | "On THIS project, skill X triggers under Y" (apps/checkout/ → tdd strict). |
+
+Pick the kind from the rule's meaning first. If it fits several kinds, ask rather than guess.
+
+Then place it by the file's own level-2 headings, which the project owns and may word differently: the installed file is a stub, so its sections appear as they are used, and a hand-written one may predate this table.
+
+- **One heading names that kind**, whatever its wording (`Project-specific hard rules` is Hard rules, `Trade-offs already decided (link to ADRs)` is Trade-offs), so append under it. Never create a second heading for a kind the file already has.
+- **No heading names it**: create the table's name as a new level-2 heading.
+- **Two headings could hold it, or a heading matches no row plainly**: ask. Never pick the closest string.
+
+The mapping is explicit, never inferred silently: the proposal names the target heading verbatim, so the human confirms where the rule lands along with its wording.
+
+### Conflict handling
+
+Before writing, scan for a duplicate or contradiction. On a **duplicate**, offer skip / replace / keep-both. On a **direct conflict**, present existing vs new and ask replace / refine-both / skip; if replace, show the removal+addition diff before editing. Never silently merge or overwrite.
+
+---
+
+## Branch B — Harness gap → a GitHub issue (HITL strict)
+
+This branch is also where harness **feedback** lands, whatever words it arrives in: a skill that
+is missing, a hook that fired on something legitimate, a rule nobody wrote down, a papercut in
+the CLI or the docs. Infer the gap from the recent conversation, and ask one short clarifying
+question only when it is genuinely unclear — the friction is fresh, and re-interviewing the user
+about something they just lived is how a capture becomes more expensive than the gap.
+
+The gap goes **straight to a `voidcorp-core/void-machine` issue** — there is no per-project `proposed/` queue; the pre-filter is your judgment before you open it. File ONLY when it clears BOTH tests:
+
+- **Agnostic** — helps any consumer, not just this project. A project quirk belongs in `PROJECT-DOCTRINE.md` (Branch A), never on the tracker.
+- **Harness-worthy** — it would change a skill, hook, pack, CLI, or doctrine line; not a one-off preference, not already covered by an existing skill.
+
+Calibrate against the ADR sweep behind issue #34 (a full audit that rejected everything but one narrow correction). When in doubt, do NOT file — a quiet, closeable tracker beats one buried in project-flavored noise.
+
+Draft the issue, show it to the user, and on confirmation:
+
+```bash
+gh issue create --repo voidcorp-core/void-machine \
+  --title "<area>: <concise gap>" \
+  --label enhancement \
+  --body "<what happened, evidence, source-project context (repo, SHA, path), shape of the fix>"
+```
+
+The tracker **is** the triage zone: taking the issue promotes it, closing it declines it. No `promoted/` / `discarded/` bookkeeping, no `feedback push` step. A promoted issue becomes a normal PR (usually an audit note + SKILL.md + matrix row) citing the originating project. Nothing merges without human review. If `gh` is missing or unauthenticated, say so and stop — do not silently swallow the failure.
+
+### Outbound audit (obsolescence detection)
+
+The obsolescence side runs from the CLI, not from prose here: `void-machine audit` (and `--all-projects` / `--push`, #72) reads canonical `.void/runs/*/events.jsonl` journals plus legacy history and reports skills that are active / stale / never-fired, plus expensive/should-have-fired via `void-graph`. This skill's job in audit mode is to **interpret** that report and, per proposal, draft a deprecation/fusion PR — hand-authored, HITL. The audit never removes a skill, edits a SKILL.md, or touches doctrine automatically.
+
+---
+
+## Branch C — the end-of-cycle ritual (feeds A, B, or drop)
+
+At a cycle close or a deja-vu recurrence, run the two-minute extraction, then route:
+
+1. **Name the pattern, not the instance** (Step 1's generalization test).
+2. **Decide scope** — project rule (→ A), harness gap (→ B), or disposable (→ drop).
+3. **Route to the matching branch** and stop. This ritual adds the *occasion* and the *triage*; the write happens in A or B under their gates.
+
+Do not run it on an unfinished cycle — wait until the work is verified done (`void-verify`). The merge that closes the cycle is the natural trigger.
+
+---
+
+## When to drop (anti-capitalization)
+
+Capitalizing trivial instances is worse than capturing nothing: it bloats the doctrine, dilutes the signal, and trains everyone to skim past it. Drop when the lesson:
+
+- is a one-off that will not recur (a typo, a one-time migration quirk);
+- is already covered by an existing skill, rule, or hook (re-check first);
+- cannot be stated as a generalization;
+- is "nice to know" but changes no future behavior.
+
+A clean doctrine is the asset. Every entry earns its place by changing what happens next time.
+
+---
+
+## HITL is absolute
+
+- Nothing is written to `PROJECT-DOCTRINE.md` or filed as an issue without an explicit human yes.
+- This skill OPENS issues/PRs; it never merges them.
+- Usage telemetry is LOCAL only (`.void/runs/*/events.jsonl`); no network call sends it anywhere.
+
+---
+
+## Anti-rules
+
+- MUST NOT write to `PROJECT-DOCTRINE.md` before confirmation, or capture a one-off instruction as a persistent rule.
+- MUST NOT add a project rule that contradicts `PHILOSOPHY.md` (that is an ADR, written through the `void-decide` skill, not a doctrine entry).
+- MUST NOT open or promote a harness PR without confirmation, or auto-merge one.
+- MUST NOT capitalize a trivial/one-off instance, or run the ritual on an unfinished cycle.
+- MUST NOT send usage data anywhere outside the machine.
+
+---
+
+## Composition with other skills
+
+- **`void-verify`** — upstream: a cycle is not "closed" until the work is verified.
+- **`void-commit-discipline`** — a captured project rule commits as `docs(doctrine):`; a recurring review finding is a strong deja-vu signal.
+- **`void-code-review`** — a finding that recurs across PRs wants capturing; the reviewer flags PRs violating a fresh rule.
+- **`void-claude-md`** — governs the doc a rule lands in.
+- **`void-decide`** — a structural decision with a rejected alternative is an ADR, not a doctrine line.
+
+---
+
+## Verification
+
+- [ ] The signal was recognized and the lesson stated as a generalization, not an instance.
+- [ ] Scope decided explicitly (project rule / harness gap / disposable); ambiguity surfaced to the user.
+- [ ] Branch A: explicit confirmation, right section under the heading the file already has for that kind, `Why` present, no unhandled conflict, only `PROJECT-DOCTRINE.md` edited.
+- [ ] Branch B: cleared the agnostic + harness-worthy bar, issue confirmed before `gh issue create`, source context included.
+- [ ] Nothing auto-written to doctrine; nothing merged without review.
+
+---
+
+## Final rule
+
+```
+Signal appears → name the lesson as a pattern → decide scope →
+  project rule  → propose → wait for yes → write PROJECT-DOCTRINE.md → confirm
+  harness gap   → clears the bar → draft → confirm → gh issue create
+  disposable    → drop it
+Otherwise → it is not learn.
+```
+
+The doctrine evolves deliberately, one explicit step at a time — and the harness compounds because each cycle's *pattern* is routed, never the raw instance dumped in.

package/core-assets/skills/void-learn/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-llm-cost-discipline/.source

@@ -0,0 +1,13 @@
+Sources for `void-llm-cost-discipline` skill (see `docs/plans/skill-audits/void-llm-cost-discipline.md` for full audit):
+
+- Anthropic prompt caching docs — https://docs.anthropic.com/en/docs/build-with-claude/prompt-caching — foundation (cache_control, hit rate signals, TTL options)
+- Anthropic batch API — https://docs.anthropic.com/en/docs/build-with-claude/batch-processing — 50% discount for non-interactive workloads
+- Anthropic model card pricing — https://docs.anthropic.com/en/docs/about-claude/pricing — Opus 4.7 / Sonnet 4.6 / Haiku 4.5 cost ratios
+- gstack /claude-api skill — SDK mechanics, composed (we extend, not replace)
+- gstack /benchmark-models — escalation for model selection
+- OpenAI batch API docs — https://platform.openai.com/docs/api-reference/batch — tactical reference for OpenAI consumers
+- LangChain model-router patterns — partially kept (model selection logic)
+
+Strategy: original + adapt. Discipline layer on top of claude-api SDK mechanics.
+
+Companion hook: llm-cost-precommit.

package/core-assets/skills/void-llm-cost-discipline/SKILL.md

@@ -0,0 +1,299 @@
+---
+name: void-llm-cost-discipline
+description: Sonnet default (Opus needs comment), prompt caching for >1024-token prompts, batch API for non-interactive, max_tokens declared, bounded retries, no full prompts in logs. Use on LLM API calls.
+---
+
+# llm-cost-discipline — voidcorp craftsman edition
+
+LLM costs scale with usage. A 1k-token system prompt re-billed on every call is 90% waste with caching. Opus everywhere is 5× Sonnet for marginal gains. Unbounded retries on a refusal burn tokens. This skill makes cost a first-class design concern at every LLM call site.
+
+**Attribution**: see `.source`. Composed with the `claude-api` skill (SDK mechanics). Foundation: Anthropic prompt caching docs + batch API + model card pricing.
+
+---
+
+## Model selection — Sonnet default
+
+| Model | When |
+|---|---|
+| **Sonnet 4.6** | DEFAULT. Everyday agentic work, code generation, chat, multi-step reasoning. Cost-effective and capable. |
+| **Haiku 4.5** | High-volume classification, extraction, retrieval-grade Q&A. ~3× cheaper than Sonnet. |
+| **Opus 4.7** | Only when justified at the call site with a comment. High-stakes reasoning, hard QA, complex code generation where Sonnet is insufficient. ~5× Sonnet cost. |
+
+```typescript
+// allowed
+await anthropic.messages.create({
+  model: 'claude-sonnet-4-6',
+  max_tokens: 1024,
+  ...
+});
+
+// allowed (with justification)
+// using Opus because legal-document drafting needs the reasoning depth
+await anthropic.messages.create({
+  model: 'claude-opus-4-7',
+  max_tokens: 4096,
+  ...
+});
+
+// banned (Opus without comment)
+await anthropic.messages.create({
+  model: 'claude-opus-4-7',
+  max_tokens: 1024,
+  ...
+});
+```
+
+The companion hook `llm-cost-precommit` warns on `model: 'opus'` without `// using Opus because` in the diff.
+
+### When to escalate
+
+If you cannot decide which model fits without testing, benchmark the candidate models on the actual prompts — run the same prompt through each and compare cost + quality before committing.
+
+---
+
+## Prompt caching — ENABLED for >1024 tokens at >1/hour rate
+
+```typescript
+await anthropic.messages.create({
+  model: 'claude-sonnet-4-6',
+  max_tokens: 1024,
+  system: [
+    {
+      type: 'text',
+      text: longSystemPrompt,                  // 5k tokens of system prompt
+      cache_control: { type: 'ephemeral' },    // CACHE THIS
+    },
+  ],
+  messages: [...],
+});
+```
+
+The cache hit reduces per-call cost by ~90% for cached blocks. Default TTL is 5 minutes; opt into 1-hour caching for stable system prompts.
+
+### What to cache
+
+- System prompt (especially if > 1024 tokens)
+- Tool definitions
+- RAG context that is shared across requests in a session
+- Few-shot examples
+
+### What NOT to cache
+
+- User-specific content unless the cache key is also user-specific
+- Content containing user PII without explicit per-user scoping (composes with `void-security-guidance`)
+
+The companion hook `llm-cost-precommit` warns on `system` / `tools` arrays > 1024 tokens without `cache_control`.
+
+Composes with the `claude-api` skill for cache mechanics.
+
+---
+
+## Batch API for non-interactive workloads
+
+```typescript
+// banned (1000 individual real-time calls for overnight processing)
+for (const doc of largeBatch) {
+  await anthropic.messages.create({ model: 'claude-sonnet-4-6', ... });
+}
+
+// allowed (50% discount via batch)
+const batch = await anthropic.messages.batches.create({
+  requests: largeBatch.map(doc => ({
+    custom_id: doc.id,
+    params: {
+      model: 'claude-sonnet-4-6',
+      max_tokens: 1024,
+      messages: [{ role: 'user', content: docPrompt(doc) }],
+    },
+  })),
+});
+// poll until complete (24h SLA, usually faster)
+```
+
+50% discount when latency budget allows. No excuse not to use it for overnight processing, bulk analysis, async classification, periodic reports.
+
+### Heuristic
+
+- User-facing interactive (chat, agent UI) → real-time, streaming
+- Background, batch-processable, latency budget > 1 hour → batch API
+- Mixed → batch the background portion; real-time the user-facing portion
+
+---
+
+## Token budgets — declared per call site
+
+```typescript
+// banned (max_tokens unset)
+await anthropic.messages.create({ model: '...', messages: [...] });
+
+// allowed (explicit budget)
+await anthropic.messages.create({
+  model: 'claude-sonnet-4-6',
+  max_tokens: 1024,                                  // explicit cap
+  // estimated input: ~3000 tokens system + ~500 user → ~3500 in
+  messages: [...],
+});
+```
+
+Default budgets per task class:
+
+| Task | `max_tokens` default |
+|---|---|
+| Chat reply | 1024 |
+| Classification / structured extraction | 256 |
+| Code generation | 4096 |
+| Long-form generation | 4096 |
+| Tool-use orchestration | 1024 |
+
+Override per call site with rationale.
+
+---
+
+## Retries — bounded with backoff + jitter
+
+```typescript
+// banned (unbounded)
+while (true) {
+  try { return await anthropic.messages.create(...); }
+  catch { /* retry */ }
+}
+
+// allowed (composed with async-safety)
+await withRetry(
+  () => anthropic.messages.create(...),
+  {
+    maxAttempts: 3,
+    backoff: 'exponential-with-jitter',
+    // do NOT retry on these:
+    skipRetryOn: (err) => err.type === 'invalid_request_error' || err.type === 'prompt_injection_refusal',
+  },
+);
+```
+
+### Banned
+
+- Unbounded retries
+- Retrying on `invalid_request_error` (the request is malformed; retrying does nothing)
+- Retrying on prompt-injection refusal (different failure mode; treat as expected failure)
+
+---
+
+## Fallback model for critical paths
+
+```typescript
+async function generateInvoiceDraft(input: InvoiceInput): Promise<Result<Draft, ...>> {
+  const primary = 'claude-opus-4-7';
+  const fallback = 'claude-sonnet-4-6';
+  try {
+    return await callLlm(primary, input);
+  } catch (err) {
+    if (isQuotaOrOutage(err)) {
+      logger.warn({ primary, fallback, err }, 'llm_fallback');
+      return await callLlm(fallback, input);
+    }
+    throw err;
+  }
+}
+```
+
+Document the fallback at the call site. If no fallback is justified, document why ("acceptable to fail; user retries manually").
+
+---
+
+## Streaming — for user-facing interactive only
+
+```typescript
+// chat / agent UI → stream
+const stream = await anthropic.messages.stream(...);
+for await (const event of stream) { /* send to UI */ }
+
+// batch / programmatic → no stream
+const response = await anthropic.messages.create(...);
+return parseStructured(response.content);
+```
+
+Streaming overhead is wasted on machine consumers.
+
+---
+
+## Structured logging per LLM call
+
+```typescript
+// composes with void-observability
+logger.info({
+  model: 'claude-sonnet-4-6',
+  inputTokens: response.usage.input_tokens,
+  outputTokens: response.usage.output_tokens,
+  cacheCreationInputTokens: response.usage.cache_creation_input_tokens,
+  cacheReadInputTokens: response.usage.cache_read_input_tokens,
+  latencyMs: Date.now() - startMs,
+  endpoint: 'checkout_classifier',
+}, 'llm_call');
+```
+
+NEVER log the full prompt content (PII / secret risk, composes with `void-security-guidance`).
+
+The Sentry / Vercel Analytics integration in `pack-nextjs` aggregates cache hit rate, model mix, cost-per-endpoint into a cost dashboard.
+
+---
+
+## LLM I/O is untrusted (composes with void-security-guidance)
+
+- Prompt injection: user-controlled text is data, not instructions. Separate system from user clearly. Defense in depth: tool invocations re-validate at the tool boundary.
+- Output hallucination: validate with Zod if parsing structured. Never `eval()`, never `innerHTML`, never SQL / shell with LLM output.
+
+See `void-security-guidance` skill for full LLM trust-boundary patterns.
+
+---
+
+## Composition with other skills
+
+- **With the `claude-api` skill**: SDK mechanics live there; this skill = the discipline.
+- **With `void-observability`**: cost-per-call structured logs feed the dashboard.
+- **With `void-security-guidance`**: prompt content NEVER in plain logs. LLM I/O untrusted.
+- **With `void-async-safety`**: retries with backoff + jitter. LLM call failures handled with idempotency discipline.
+- **With `void-hexagonal-architecture`**: LLM SDK at an adapter behind `LlmPort`. In-memory adapter for tests.
+- **With `void-code-review`**: dimension `performance` includes LLM cost surface.
+- **Model comparison**: escalation for "which model is best for this surface?" — benchmark the candidates on real prompts (cost + quality).
+
+---
+
+## Companion hooks
+
+- `llm-cost-precommit` (pre-commit on files matching `<config.paths.ai>` or importing `@anthropic-ai/sdk`) — warns on Opus without justifying comment, missing `max_tokens`, missing `cache_control` on qualifying prompts. See `../../hooks/`.
+
+---
+
+## Anti-rules
+
+- MUST NOT decide which provider (Anthropic vs OpenAI vs Gemini) — that is a project-level ADR.
+- MUST NOT impose a model-router abstraction by default.
+- MUST NOT silently allow Opus without justifying comment.
+- MUST NOT permit unbounded retries.
+- MUST NOT permit `max_tokens` unset.
+- MUST NOT log full prompt content.
+- MUST NOT cache prompts containing user-specific PII without per-user cache keys.
+
+---
+
+## When you are stuck
+
+| Problem | Solution |
+|---|---|
+| Sonnet seems insufficient | Quantify it: benchmark Sonnet vs Opus on the actual prompts (cost + quality) before upgrading. |
+| Cache hit rate low | Prompt structure problem — variable content interleaved with stable. Restructure to put stable blocks first with `cache_control`. |
+| Cost budget exceeded | Audit via cost dashboard. Top 3 endpoints. Apply caching, batching, model downgrade where quality allows. |
+| Token budget too small | Validate via void-observability — what's the actual output size? Adjust budget OR truncate the input intelligently. |
+| Latency too high | Streaming for user-facing. Batch for background. |
+
+---
+
+## Final rule
+
+```
+Every LLM call → Sonnet by default, cache >1024 tokens, batch non-interactive, max_tokens set, retries bounded,
+                 fallback declared, structured cost logs, no prompt content in logs.
+Otherwise → it is not voidcorp llm-cost-discipline.
+```
+
+The discipline is small. The savings compound. A single agentic feature can save 70%+ via caching + Sonnet default + batch.

package/core-assets/skills/void-llm-cost-discipline/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-make-pdf/.source

@@ -0,0 +1,9 @@
+Sources for `void-make-pdf` skill (see `docs/plans/skill-audits/void-make-pdf.md` for full audit):
+
+- gstack /make-pdf (v1.57.10, ~/.claude/skills/gstack/make-pdf/) — REBUILT (DEV-391): kept the load-bearing pipeline (marked md->HTML, the HTML sanitizer for untrusted embedded HTML, the print-CSS design intent: metric-compatible sans stack for cross-OS diacritics, break-avoid). REJECTED: its dependency on the gstack browse daemon (browseClient.ts).
+- marked (^14) + puppeteer-core (^23) — the state-of-the-art md->PDF pipeline (researched, e.g. simonhaenisch/md-to-pdf, the marked+Puppeteer pattern). puppeteer-core drives the SYSTEM Chrome via `page.pdf()` — no bundled Chromium download. `page.pdf()` gives page-number footers (pageNumber/totalPages), printBackground, and precise margins that the raw `--headless --print-to-pdf` CLI flag cannot.
+- Puppeteer PDFOptions docs — https://pptr.dev/api/puppeteer.pdfoptions (source-driven: the displayHeaderFooter + footerTemplate page-number mechanism).
+
+Strategy: rebuild (REBUILD class), state-of-the-art. Engine in apps/make-pdf/ (@voidcorp/make-pdf): pure render + print-css modules, an impure pdf module (puppeteer) with injectable findChrome, an async CLI. 13 unit tests + a dogfood PDF (observed: 67 KB, page-number footer, French accents, table with €, code block).
+
+Enabler: adding these deps required the DEV-393-follow-up floor fix (ci-enforce allows a lockfile change accompanied by a manifest change) — see docs/DECISIONS.md (2026-07-10). No hand-rolled parser (rejected as a band-aid), no lockfile hand-edit.

package/core-assets/skills/void-make-pdf/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: void-make-pdf
+description: Turn a markdown file into a publication-quality PDF — marked + puppeteer-core on the system Chrome, with page-number footers. No gstack daemon. For signed deliverables (DECLIK audits).
+---
+
+# make-pdf — voidcorp craftsman edition
+
+Render a markdown file to a clean, paginated PDF with page-number footers. State-of-the-art pipeline: **`marked`** parses the markdown, **`puppeteer-core`** drives the **system** Chrome/Chromium and prints via `page.pdf()`. No gstack browse daemon; no bundled Chromium download (`puppeteer-core` uses the browser already on the machine).
+
+For French-language signed deliverables (DECLIK Audit Pulse), it keeps diacritics, tables, and code intact, never splits a table or heading across a page, and numbers the pages.
+
+The engine lives in `apps/make-pdf/` (`@voidcorp/make-pdf`). This skill tells the agent how to drive it.
+
+**Attribution**: see `.source`. Distilled from gstack `/void-make-pdf` (its `marked` pipeline + print-CSS intent + HTML sanitizer), rebuilt on `puppeteer-core` + the system Chrome instead of the browse daemon — the standard `marked` + Puppeteer approach.
+
+---
+
+## Run it
+
+```bash
+pnpm --filter @voidcorp/make-pdf make-pdf <input.md> [output.pdf] [--a4|--legal] [--margins=1in] [--title="..."]
+```
+
+- `output.pdf` defaults to the input's basename with a `.pdf` extension.
+- Default page format is US Letter; `--a4` / `--legal` switch it. `--margins` overrides the 1in default.
+- The title defaults to the first `# H1`, else "Document"; `--title` overrides.
+
+## What it does
+
+1. `marked` parses the markdown to HTML.
+2. A conservative sanitizer strips dangerous embedded HTML (`<script>`/`<iframe>`/`on*`/`javascript:` — untrusted markdown can carry raw HTML, a real trust boundary).
+3. The body is wrapped with an inlined content stylesheet: a metric-compatible sans stack (Helvetica / Liberation Sans / Arial — renders French accents on every OS) and `break-inside: avoid` on tables / figures / code.
+4. `puppeteer-core` launches the system Chrome, `page.setContent` loads the HTML, and `page.pdf()` prints it with `printBackground`, precise margins, and a **page-number footer** (`<span class="pageNumber"></span> / <span class="totalPages"></span>`).
+
+## Requirements & failure modes
+
+- **System Chrome or Chromium** must be installed (macOS: Google Chrome / Chromium / Edge; Linux: `google-chrome` / `chromium`). Set `CHROME_PATH` to override. If none is found, the CLI exits non-zero with an explicit message — never a silent failure.
+- **Relative images** in the markdown resolve against the CWD at print time; use absolute paths or run from the markdown's directory.
+
+## Anti-rules
+
+- MUST NOT depend on the gstack browse daemon or any gstack runtime.
+- MUST NOT bundle/download a Chromium (use `puppeteer-core` + the system browser).
+- MUST NOT fail silently when Chrome is absent — the error is explicit.
+- MUST NOT trust raw HTML embedded in markdown — the sanitizer runs unconditionally. (It matches `javascript:` literally; the output is printed, never live-rendered, so a surviving entity-encoded scheme is inert — harden before any live-render reuse.)
+
+## Composition
+
+Downstream: a generated deliverable is reviewed by the read-only `pdf-specialist` agent for faithful
+rendering, pagination, accessibility, and artifact evidence. The renderer owns production; the
+specialist judges the output and never edits it. `void-verify` carries that observed proof into the
+final gate.

package/core-assets/skills/void-make-pdf/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: action
+activation: on-demand
+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-merge/.source

@@ -0,0 +1,8 @@
+Sources for `void-merge` skill (see `docs/plans/skill-audits/void-merge.md` for full audit):
+
+- No upstream source. Written from the seven pull requests merged by hand in this repository on
+  2026-08-19, and from the four cases a naive "merge everything green" would have failed on.
+- gstack `/land-and-deploy` — ADJACENT, not a source: it merges one named PR and then watches a
+  deployment. This skill drains a queue and never deploys.
+- GitHub branch protection semantics (`mergeStateStatus`: BEHIND, BLOCKED, DIRTY, CLEAN) —
+  the state machine the skill reads rather than reimplements.