npm - voidmachine - Versions diffs - 0.0.0 → 4.0.0 - Mend

voidmachine 0.0.0 → 4.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (341) hide show

package/core-assets/skills/void-commit-discipline/SKILL.md ADDED Viewed

@@ -0,0 +1,211 @@
+---
+name: void-commit-discipline
+description: Conventional Commits + mandatory "why" in body + scope + breaking-change marking. ASCII-only (no em dash, no emoji). Co-author trailer for AI pair. The git log is documentation. Use at every commit.
+---
+# commit-discipline — voidcorp craftsman edition
+The git log is the project's living narrative. "fix stuff" / "wip" / "asdf" destroy that narrative. Conventional Commits give shape; the mandatory "why" in the body gives substance. This skill enforces both.
+**Attribution**: see `.source`. Foundation: Conventional Commits spec + Folpe "always say why" + citypaul commit guidance.
+---
+## Format
+```
+<type>(<scope>): <subject>
+<blank line>
+<body explaining WHY — the rationale, the constraint, the spec link>
+<blank line>
+<footers — BREAKING CHANGE, Co-Authored-By, Closes #N>
+```
+### Types (allowed list)
+| Type | When |
+|---|---|
+| `feat` | New observable behavior (new feature, new endpoint, new component visible to users / consumers) |
+| `fix` | Bug fix. Composes with `void-debug` (the why = the root cause) |
+| `void-refactor` | Structural change without behavior change. Composes with `void-refactor` (named Fowler move) |
+| `test` | Add / modify tests without changing production code. Includes `test: reproduce <bug>` from `void-debug` |
+| `docs` | Documentation only |
+| `chore` | Repo maintenance (config, scripts, tooling) without user-visible effect |
+| `build` | Build system / dependencies |
+| `ci` | CI configuration / workflows |
+| `perf` | Performance improvement with measurement |
+| `style` | Formatting only (Biome auto-fix, etc.) |
+No invented types (`improve:`, `tweak:`, `cleanup:`). Reach for one of the above or split the commit.
+### Subject rules
+- Imperative mood: "add", "fix", "refactor" — NOT "added", "adds", "adding"
+- Lowercase
+- No period at the end
+- ≤ 72 characters
+- Specific: "fix race in webhook handler" > "fix bug"
+### Body rules
+- Always present for `feat`, `fix`, `void-refactor`, `perf` commits. Optional for trivial `chore` / `style`.
+- Wrapped at ≤ 72 columns
+- Explains the WHY: rationale, constraint, spec link, root cause
+- Multi-line bullets fine
+- ASCII only — no em dash, no emoji (the harness invariant)
+### Footers
+- `BREAKING CHANGE: <description>` for breaking changes (forces a major version bump under SemVer)
+- `Closes #<issue>` / `Refs #<issue>` for issue references
+- `Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>` for AI pair commits
+---
+## Examples
+### feat with spec link
+```
+feat(checkout): add discount code application to cart
+Why: spec docs/specs/2026-05-29-discount-codes.md approved 2026-05-30.
+The cart accepts a `discountCode` field; valid codes apply percentage
+or fixed-amount discounts at checkout time. Composes with the existing
+Money value object for precision.
+Closes #142
+Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
+```
+### fix with root cause
+```
+fix(orders): handle null customer email in receipt generation
+Why: a small fraction of legacy orders have a null customer email
+(pre-validation rollout, see migration 0042). The receipt generator
+threw on null, surfaced as 500s on /api/orders/{id}/receipt.
+Root cause: the receipt builder assumed Email is always present.
+Fix: receipt builder falls back to "unknown@example.invalid" with
+a structured log entry tagged orphan_email_receipt for auditing.
+Prevention: a backfill migration is queued (see plan
+plans/2026-06-02-email-backfill-plan.md) to set valid emails on
+legacy rows.
+Closes #248
+```
+### refactor (named Fowler)
+```
+refactor(checkout): extract calculateDiscount helper
+Why: the inline calculation in CheckoutService grew to ~40 lines
+with three branches. Extracted to a pure helper to enable unit
+tests at the calculation level (composes with the new discount
+strategy tests in PR #142).
+Named refactor: Extract Function (Fowler 2018).
+```
+### BREAKING CHANGE
+```
+feat(api)!: rename /orders/:id/items endpoint to /orders/:id/line-items
+Why: ubiquitous-language alignment. The team uses "line item"
+consistently in the domain (per docs/DOMAIN.md). The API path
+matched. BREAKING CHANGE for any external consumer.
+BREAKING CHANGE: the path /orders/:id/items no longer exists.
+Consumers MUST migrate to /orders/:id/line-items. The legacy
+path will return 410 Gone for 30 days, then be removed.
+Closes #157
+```
+---
+## Banned
+### Vacuous subjects
+- "wip", "asdf", "stuff", "fix bug", "update", "tweak", "cleanup"
+The author cannot tell, the reviewer cannot tell, future maintainers cannot tell. Reject at commit time.
+### Mixed-intent commits
+- `feat: add discount + fix unrelated bug` — split.
+- `refactor: extract helper and add validation` — split (composes with `void-refactor` Two-Hat).
+- `fix: bug A and bug B` — split.
+The companion hook `tidying-commit-prefix` (already shipped) flags `refactor:` with behavior-change keywords in body.
+### Em dash, emoji, non-ASCII
+The harness invariant: English ASCII commit messages. Hyphens (`-`) for ranges, hyphens for parenthetical, not em dash. The companion hook `no-emdash-no-emoji-in-commit-msg` blocks.
+### Missing "why" for substantive commits
+`feat:` / `fix:` / `refactor:` / `perf:` without a body explaining why = rejected. The commit message is documentation.
+### AI authorship without trailer
+Commits produced in pair with an AI agent include `Co-Authored-By`. Authorship transparency.
+---
+## Bug fix commit pairs (composes with void-debug)
+A bug fix is TWO commits:
+1. `test: reproduce <bug summary>` — the failing test that demonstrates the bug
+2. `fix: <root cause description>` — the implementation that resolves it
+Combined into one commit = rejected. The pair makes the regression-prevention explicit in `git log`.
+---
+## Companion hooks
+- `commitlint-precommit` (commit-msg, in `pack-monorepo`) — already in void-starter. Enforces conventional commits.
+- `tidying-commit-prefix` (commit-msg, already shipped in core/hooks) — warns on mixed-intent `refactor:` commits.
+- `refactor-named-grep` (commit-msg, already shipped) — warns on `refactor:` without a Fowler name.
+- `no-emdash-no-emoji-in-commit-msg` (commit-msg, in `pack-monorepo`) — blocks em dash and emoji.
+---
+## Composition with other skills
+- **Runs AFTER `void-verify`** — the completion handoff produces the "what done"; this skill frames it for git.
+- **With `void-debug`** — bug fix commit pairs (`test:` then `fix:`).
+- **With `void-refactor`** — Two-Hat principle, named Fowler refactors in subjects.
+- **With `void-brainstorm` + `void-plan`** — substantive commits link to their spec / plan in the body.
+- **With `void-code-review`** — review comments respect the commit boundaries (do not request mixing intent).
+---
+## Anti-rules
+- MUST NOT decide whether the change itself is correct (that is the upstream skills' job).
+- MUST NOT permit vacuous subjects.
+- MUST NOT permit em dash / emoji / non-ASCII.
+- MUST NOT permit `feat:` / `fix:` / `refactor:` without a body why.
+- MUST NOT combine bug-fix `test:` and `fix:` commits.
+- MUST NOT silently allow invented commit types.
+---
+## Final rule
+```
+Every commit → conventional format + imperative subject ≤ 72 + body explains WHY + ASCII + AI co-author trailer.
+Substantive (feat/fix/refactor/perf) → body mandatory.
+Otherwise → it is not voidcorp commit-discipline.
+```
+The git log is the project's narrative. Write it as if a future debugger will thank you — because one will.

package/core-assets/skills/void-commit-discipline/harness.yaml ADDED Viewed

@@ -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-context/.source ADDED Viewed

@@ -0,0 +1,15 @@
+Sources for `void-context` skill (see `docs/plans/skill-audits/void-context.md` for full audit):
+- Anthropic / Claude Code best practices — context management guidance: use /clear between unrelated tasks; /compact <focus> to condense long sessions; delegate investigation to subagents to protect the main window. https://www.anthropic.com/engineering/claude-code-best-practices
+- Anthropic engineering — "Effective context engineering for AI agents" (context as a finite, attention-competing budget; subagents return distilled conclusions, not raw material). https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents
+- Boris Cherny / Cat Wu (Claude Code creators) interviews — "context is the fundamental constraint" of an agent; subagents exist to protect the main context window from heavy exploration. (Latent Space / podcast appearances on Claude Code.)
+- "get-shit-done" / Ralph-style autonomous loops — anti-context-rot principle: decompose long tasks and persist state with its authoritative owner so work survives a context reset rather than living in conversation history.
+- superpowers/dispatching-parallel-agents + superpowers/subagent-driven-development — composed (vendored targets) for fan-out investigation and subagent-run plan steps.
+- PrimeIntellect `prime-agent` compaction format — adapted only for cumulative bounded read and
+  modified file observations; its semantic summary format is not copied.
+Strategy: distill. Distill the load-bearing context principles from Claude Code official best-practices and the creators' framing, plus the anti-context-rot / on-disk-state principle from autonomous-loop practice. Rewritten for void-machine; absorbs the "context-engineering / anti-context-rot" concept. Composes with debug (investigate without drowning context), plan (on-disk state), and subagent delegation.
+Companion mechanism: the shared `context-continuity` lifecycle handler observes bounded usage and
+working-set facts, preserves them at `PreCompact`, and can emit one configured threshold nudge.
+It does not invoke `/clear`, `/compact`, or a semantic checkpoint.

package/core-assets/skills/void-context/SKILL.md ADDED Viewed

@@ -0,0 +1,167 @@
+---
+name: void-context
+description: Context is the agent's core constraint. Use when a task spans many files, a session mixes subjects, corrections loop, or replies forget earlier constraints. Clear, compact, delegate to subagents.
+---
+# context — voidcorp craftsman edition
+The context window is not infinite scratch space; it is the single fundamental constraint on an agent's reasoning. Everything in it competes for attention, and a polluted window degrades quality silently — the model does not announce that it forgot your earlier constraint, it simply drops it. This skill teaches you to treat context as a managed budget: clear it between unrelated tasks, compact it when long, delegate heavy reading to fresh-context subagents, and keep durable state on the filesystem so it survives any reset.
+**Attribution**: see `.source`.
+---
+## Why context is the constraint
+A long session accumulates dead weight: abandoned approaches, stale file dumps, three superseded versions of the same plan, two failed fix attempts. The model attends to all of it. The symptom is never an error — it is a slow rot: the agent re-asks a settled question, contradicts a decision made earlier, or "fixes" something already correct. By the time you notice, the window has been degraded for many turns.
+So the discipline is proactive, not reactive. You manage the budget before it overflows, the same way you would not wait for an OOM to think about memory.
+---
+## The four moves
+### 1. `/clear` between unrelated tasks
+When you finish one task and start a logically separate one, run `/clear`. Carrying the first task's context into the second is the "kitchen-sink session" anti-pattern: nothing in the residue helps the new task, and all of it competes for attention. If work remains open, invoke `void-checkpoint` first: `/clear` has no pre-event, and the harness cannot preserve semantic residue after it is gone.
+Rule of thumb: if the next task would not cite anything from the current conversation, clear first.
+### 2. The two-correction reset
+If two attempts to correct the agent both fail, **stop stacking a third correction**. Each failed correction adds confused context (the wrong attempt, your patch, the next wrong attempt) that makes the third try worse, not better.
+Instead:
+1. `/clear`.
+2. Re-prompt from scratch with a single reformulated statement that folds in what the failures taught you ("X must handle the empty case, and must not touch the cache layer").
+A clean window with a sharp prompt beats a dirty window with three patches. Correcting over and over is the most common way a session quietly rots.
+### 3. `/compact <focus>` for long-but-coherent work
+When a task is genuinely long and coherent (not mixed subjects, just big), do not clear — you would lose the thread. Run `/compact <focus>` to summarize the history down to what matters, naming the focus so the compaction keeps the relevant fil rather than a generic digest.
+Use `/clear` when subjects changed; use `/compact` when the subject is the same but the history is heavy. The `PreCompact` hook preserves the bounded mechanical block before compaction; it does not invent dead ends, assumptions, or the next action.
+### 4. Delegate heavy investigation to fresh-context subagents
+Exploration is the biggest context sink: reading twenty files to answer one question dumps twenty files into the window, of which you needed two sentences. Push that work into a subagent with its own fresh context. The subagent reads broadly and returns only its conclusion; your main window receives the answer, not the raw material.
+This is the cure for "infinite exploration," where the agent keeps reading more files in a widening search and the window fills with material it will never cite. Dispatch a subagent, state the question, accept the conclusion.
+Vendored targets: `superpowers:dispatching-parallel-agents` (fan out several investigations at once) and `superpowers:subagent-driven-development` (run independent plan steps in subagents). Until vendored, use those directly.
+A subagent must return a **compacted structured summary** — findings, the answer, the relevant file:line pointers — never the raw bytes it read. Raw output dumped back into the main window defeats the delegation.
+---
+## Frequent intentional compaction
+Treat context usage like a gauge you keep in a healthy band, not a tank you fill to the brim. Aim to keep effective usage around **40–60%**; a window run to the limit reasons worse long before it errors.
+- When `.void/config.json` declares a reliable `context.windowTokens`, the lifecycle hook can emit one `void-checkpoint` nudge per cycle at the configured 40–60% threshold (50% by default). Without that denominator it reports no percentage and emits no threshold nudge.
+- After each verified phase, route durable programme and provider state to their owners, invoke `void-checkpoint` for session residue, then trim the chat. The disk is the durable record; the window is working memory.
+- Compaction is a deliberate move you schedule, not an emergency you react to. Do it at clean boundaries (phase done, gate passed), where the summary is easy to write and nothing in flight is lost.
+The hook never invokes `/clear` or `/compact`, and never writes a semantic checkpoint. Its nudge is advisory; the runtime and the agent still own those actions.
+## Leverage hierarchy
+Errors compound asymmetrically by stage. A bad research conclusion cascades into thousands of wrong lines; a bad plan into hundreds; a bad line of code stays mostly local and isolated.
+So concentrate human review and verification **upstream**: research > plan > code. The cheapest place to catch a mistake is the research summary, the next-cheapest is the plan, and the most expensive is after it is coded. Spend scrutiny where leverage is highest, not evenly.
+---
+## Anti-context-rot: state lives on the filesystem
+A long task must not keep its state only in the conversation, because the conversation is the thing you will reset. Durable state goes on disk:
+- The versioned programme descriptor and its linked plan/spec, when a programme exists.
+- Mutable execution state in the declared progress provider, never duplicated locally.
+- `.void/machine/checkpoint.md` for session residue and the bounded mechanical working set.
+- Durable decisions in ADRs and reusable rules in doctrine, through their owning skills.
+The test: **if you `/clear` right now, can the next session pick up the task from disk alone?** If not, the state is trapped in the window and one reset will lose it. Write it down first.
+Decompose long tasks into sub-tasks with their own gates (composes with `void-plan`). Each sub-task is small enough to run in a clean-ish window; the plan file stitches them across resets.
+---
+## Signs you must act
+| Signal | What it means | Move |
+|---|---|---|
+| Reply forgets a constraint you set earlier | Window degraded; constraint scrolled out of effective attention | `/compact <focus>` or `/clear` + re-prompt |
+| Two corrections in a row failed | Correction stacking; context now confused | two-correction reset (`/clear` + reformulate) |
+| Subjects are mixing (the agent references the previous task) | Kitchen-sink session | `/clear` |
+| Responses slowing / wandering, search widening | Infinite exploration, window bloated with file dumps | delegate to a fresh-context subagent |
+| You are about to read many files to answer one question | Exploration sink | delegate to a subagent, take the conclusion |
+---
+## Operating procedure
+1. **Before a new task**: is it related to the current one? No → checkpoint any open residue, then `/clear`. Yes → continue.
+2. **Before heavy reading**: will this dump many files for a small answer? Yes → dispatch a subagent.
+3. **During a long coherent task**: window feeling heavy but subject unchanged → `/compact <focus>`.
+4. **On a stuck correction loop**: hit two failed corrections → `/clear`, reformulate the prompt with the lessons folded in.
+5. **Throughout a long task**: persist plan + notes to disk so any reset is survivable.
+---
+## Rationalizations
+| Rationalization | Reality |
+|---|---|
+| "Keeping everything in context is safer — I might need it." | The model attends to all of it; the irrelevant 90% degrades the relevant 10%. Keeping everything is the harm, not the safety. |
+| "One more correction will fix it." | After two failures, the third inherits a confused window. A clean re-prompt wins. |
+| "Clearing loses my work." | It loses semantic residue that was only in chat. Route state and invoke `void-checkpoint` first; then `/clear` has a durable recovery point. |
+| "Reading the files myself is faster than dispatching a subagent." | Faster this turn, slower every turn after — those files now sit in your window forever. The subagent returns the conclusion, not the bytes. |
+| "The session is fine, no errors." | Context rot produces no errors. It produces dropped constraints and repeated questions. Silence is not health. |
+| "Compacting might drop something important." | Name the focus. `/compact <focus>` keeps the named thread; an unmanaged window drops things at random instead. |
+---
+## Composition with other skills
+- **`void-debug`**: investigate without drowning the window — gather evidence in a subagent, bring back the timeline and root cause, not every log line read.
+- **`void-plan`**: owns the approved execution structure; mutable progress remains with its declared provider.
+- **`void-checkpoint`**: owns semantic session residue; the lifecycle hook owns only the delimited mechanical block it must preserve.
+- **`superpowers:dispatching-parallel-agents`** (vendored target): fan out independent investigations to protect the main window.
+- **`superpowers:subagent-driven-development`** (vendored target): run independent plan steps in fresh-context subagents.
+This skill absorbs the "context-engineering / anti-context-rot" concept; other skills do the work, this one keeps the window clean enough for them to do it well.
+---
+## Anti-rules
+- MUST NOT run a single giant session across many unrelated tasks — `/clear` between them.
+- MUST NOT stack a third correction after two failed ones — reset and reformulate.
+- MUST NOT keep task state only in the conversation — persist plan and notes to disk.
+- MUST NOT do heavy multi-file exploration in the main window when a subagent can return the conclusion.
+- MUST NOT treat "no error" as "context is healthy" — rot is silent.
+---
+## Verification
+- [ ] Unrelated tasks are separated by a `/clear` (no kitchen-sink session).
+- [ ] No correction stacked beyond two attempts without a reset + reformulation.
+- [ ] Long coherent work was `/compact <focus>`-ed rather than left to bloat.
+- [ ] Heavy investigation was delegated to a fresh-context subagent that returned only its conclusion.
+- [ ] Programme, provider state, checkpoint residue, decisions, and doctrine are routed to their single authoritative owners before a reset.
+- [ ] Open semantic residue is checkpointed before `/clear`; no hook capability is assumed beyond mechanical preservation and an advisory nudge.
+- [ ] Acting on degradation signals before they compound, not after errors appear.
+---
+## Final rule
+```
+Context is the budget. Clear between subjects, reset after two failed corrections,
+compact long threads, delegate exploration to fresh-context subagents, keep state on disk.
+Otherwise → the window rots silently and quality drops with no warning.
+```

package/core-assets/skills/void-context/harness.yaml ADDED Viewed

@@ -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: standard
+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-debug/.source ADDED Viewed

@@ -0,0 +1,11 @@
+Sources for `void-debug` skill (see `docs/plans/skill-audits/void-debug.md` for full audit):
+- gstack /investigate — VENDORED (DEV-388): the four-phase mechanism + Iron Law were already this skill's core (superpowers lineage, ~85-90% overlap); DEV-388 folded the remaining diagnostic aids (pattern-lookup table, 3-strike rule, blast-radius gate, instrument-to-confirm, recurring-bug-smell, red-flags). Everything else was deliberately NOT re-vendored (already present).
+- superpowers/debug — composed, similar discipline, cross-reference for anti-drift psychology.
+- "5 Whys" (Toyota / Taiichi Ohno) — questioning loop for the analyze phase.
+- Brian Kernighan "The Practice of Programming" debugging chapter — mental model: rubber duck, narrow search space.
+- Julia Evans "Debugging" zine + blog — https://jvns.ca — tactical tips for system debugging.
+Strategy: distill (gstack /investigate now fully vendored, DEV-388, not composed). void-machine composition added (TDD failing test before fix, root-cause section in PR body, observability-first when visibility is gap, refactor composition for structural roots).
+No new companion hooks (composed with existing tdd-guard + code-review).

package/core-assets/skills/void-debug/SKILL.md ADDED Viewed

@@ -0,0 +1,211 @@
+---
+name: void-debug
+description: "Four phases (investigate, analyze, hypothesize, implement). Iron Law: no fix without a failing test reproducing the bug AND a root cause. Bug fix commit pairs. Use on bug or test failure."
+---
+# debug — voidcorp craftsman edition
+A bug fix without a root cause is a band-aid. The bug recurs in three months under a different name, and the next debugger inherits the band-aid. `void-debug` enforces four phases (investigate → analyze → hypothesize → implement), with a failing test that reproduces the bug landing BEFORE the fix.
+**Attribution**: see `.source`. The gstack `/investigate` methodology is vendored here (DEV-388); the four-phase discipline is `superpowers:debug`.
+---
+## Iron Law
+```
+No fix without:
+  (a) a root cause identified, AND
+  (b) a failing test that reproduces the bug.
+```
+"It works now" is not a root cause. Suspect cosmic-ray fixes.
+---
+## Four phases
+### Phase 1 — Investigate (gather evidence)
+Collect what you can OBSERVE before reasoning. The goal is signal, not theory.
+- Reproduce the bug at least once locally (or capture the prod conditions if not).
+- Gather: stack trace, recent commits, related logs, recent infra changes, recent migrations.
+- Note: when did it start? What changed?
+- If reproduction requires data you do not have, **invoke `void-observability` first** — add the visibility, then come back.
+Deliverable: a one-paragraph timeline + reproducible steps (or a recorded "last working commit").
+### Phase 2 — Analyze (find the pattern)
+Find the smallest example that reproduces. Narrow the search space:
+- **Time**: binary-search the commit history. Last working SHA? First failing SHA?
+- **Code**: which module? Which file? Which function?
+- **Input**: which value class? Boundary case? Empty? Negative?
+- **Environment**: which user? Which region? Which browser? Which timezone?
+Apply **5 Whys** (Toyota): for non-obvious bugs, ask "why does this happen" 3–5 times until you stop hitting symptoms.
+Deliverable: narrowed reproduction + 5-Whys chain (in the PR body later).
+### Phase 3 — Hypothesize (testable theory)
+State the root cause as a theory you can test:
+> "The validation runs before authentication. An unauthenticated user can trigger expensive DB lookups by sending an invalid payload."
+A good hypothesis:
+- Explains the observation (necessary condition).
+- Predicts the behavior change after fix (sufficient condition).
+- Is testable — you can write a failing test for it.
+If the hypothesis does not predict a falsifiable behavior change, it is a guess. Keep analyzing.
+### Phase 4 — Implement (fix + verify)
+In this order:
+1. **Write the reproducing test** (in `strict` mode per `void-tdd`). It must fail on `main`.
+2. **Commit**: `test: reproduce <bug summary>`.
+3. **Implement the fix**. The test now passes; other tests still pass.
+4. **Commit**: `fix: <root cause description>`. Composes with `void-commit-discipline` (the "why" is the root cause).
+5. **Verify pristine output** — no warnings, no leaked logs.
+6. **Root-cause section in PR body** — see template below.
+### Banned
+- Combining the reproducing test and the fix in one commit. Bug fix commit pairs are non-negotiable.
+- Adding the test "later" after the fix.
+- Marking the bug closed without an explanation that survives scrutiny.
+---
+## Root-cause section in PR body
+Every bug-fix PR includes:
+```markdown
+## Root cause
+**Symptom**: <one sentence — what the user saw>
+**Narrowing**:
+- Last working commit: <sha or "unknown — first observed in prod">
+- Smallest reproduction: <steps or test>
+- Affected paths: <files / endpoints / users>
+**5 Whys**:
+1. Why does the API return 500? → unhandled exception in checkoutCart
+2. Why is the exception unhandled? → repository returns null instead of Result
+3. Why does the repository return null? → migration added column but seed lacks it
+4. Why does the migration not include the seed? → seed file path not tracked by migration runner
+5. Why is the seed file path not tracked? → introduced in PR #142, never run in CI
+→ Root cause: PR #142 introduces seed-coupled migrations without CI coverage
+**Fix**: <one sentence>
+**Prevention**: <how this class of bug is now caught — usually a new test, a new hook,
+or an ADR>
+```
+This section persists. `git blame` archaeology rewards the next debugger.
+---
+## When the root cause is "we cannot see what happened"
+If Phase 1 cannot reproduce because production lacks visibility:
+1. **STOP debugging the symptom.**
+2. **Invoke `void-observability`** — add structured logs, trace IDs, breadcrumbs, error boundaries at the suspect surface.
+3. **Deploy the observability fix** (with `void-commit-discipline` "why: investigating prod issue X").
+4. **Wait for the next occurrence** — now with signal.
+5. **Resume debug Phase 1** with real data.
+Guessing in the dark produces "fixes" that may move the bug rather than solve it.
+---
+## When the root cause is structural
+If Phase 3 hypothesis is "the architecture allows this state to exist":
+- The fix is a refactor (composes with `void-refactor` and `void-hexagonal-architecture` / `void-domain-driven-design`).
+- Invoke the `doctrine-critic` agent to judge the structural root before the refactor.
+- Compose with `void-brainstorm` + `void-plan` if the refactor is large enough to need a spec.
+- Two-Hat principle: the structural fix (refactor) and the bug close commit separately — though they live in the same PR with explicit ordering.
+---
+## Flaky tests are bugs too
+A "flake" is a non-deterministic test. It is a bug — not a CI inconvenience to retry around.
+Run `void-debug` on the flake:
+- Phase 1: gather flake conditions (which CI run, which time of day, which order).
+- Phase 2: narrow — timing assumption? Shared state? Network? Randomness without a seed?
+- Phase 3: hypothesis (e.g., "test depends on global Date — fix by injecting a clock port").
+- Phase 4: failing test that DEMONSTRATES the flake, then the fix.
+Retry-until-green is rejected.
+---
+## Diagnostic aids (vendored from gstack `/investigate`)
+**Pattern lookup** — before theorizing, match the symptom against a common class:
+| Pattern | Signature | Where to look |
+|---|---|---|
+| Race condition | intermittent, timing/load-dependent, "works when I step through" | shared mutable state, missing `await`, unordered async |
+| Nil propagation | NPE / undefined far from its origin | an optional assumed present at a boundary |
+| State corruption | wrong value, no error | a write path skipping validation, or a stale cache |
+| Integration failure | works in isolation, fails wired up | contract mismatch at the adapter, env / config drift |
+| Config drift | works locally, fails in one env | env-specific value, unpinned dependency |
+**Instrument to confirm, before editing.** Add a temporary log/assertion at the suspected cause and match it against the reproduction *before* writing any fix. A hypothesis you have not observed is still a guess.
+**3-strike rule.** Three failed hypotheses → stop treating it as a simple bug. It is likely architectural: instrument-and-wait, or escalate to a structural review (see "When the root cause is structural").
+**Blast-radius gate.** If the fix touches > 5 files, stop and ask: proceed / split / rethink. A wide fix for a narrow bug is usually the wrong layer.
+**Recurring bug = architectural smell.** `git log` the affected files for prior fixes. The same file fixed three times is not coincidence — the root is structural, not the latest symptom.
+**Red flags** (each means you are guessing): "a quick fix for now" (there is no for-now); proposing a fix before tracing the data flow; each fix revealing a new problem (wrong layer).
+---
+## Composition with other skills
+- **Upstream — `void-observability`**: if visibility is the gap, fix it first.
+- **With `void-tdd`**: the reproducing test is written in strict mode. The fix follows the cycle.
+- **With `void-code-review`**: PR body includes the root-cause section. The reviewer verifies the test reproduces the bug before the fix.
+- **With `void-refactor`**: structural fixes compose with void-refactor's Two-Hat principle.
+- **With `doctrine-critic` agent**: for structural roots affecting multiple bugs of the same kind.
+- **With `void-commit-discipline`**: `fix:` commits include the "why" (root cause).
+- **`gstack:/investigate` is fully vendored here** (DEV-388): its diagnostic aids (pattern lookup, 3-strike, blast-radius, instrument-to-confirm) are the section above; the phase skeleton + Iron Law + regression-test rule were already this skill's core (deliberately not re-vendored).
+---
+## Anti-rules
+- MUST NOT close a bug without a root cause the developer can explain.
+- MUST NOT allow "I will add the test later" — the test exists alongside or before the fix.
+- MUST NOT permit retry-until-green for flakes.
+- MUST NOT silently widen the scope of the fix PR (Two-Hat).
+- MUST NOT skip observability when the root cause is visibility.
+- MUST NOT defer to `void-migrations` for non-migration bugs.
+---
+## Final rule
+```
+Bug → investigate → analyze → hypothesize → reproduce in test → fix → verify → PR with root cause.
+Otherwise → it is not voidcorp debug.
+```
+The discipline pays off the second time the bug would have recurred — and it does, often.

package/core-assets/skills/void-debug/harness.yaml ADDED Viewed

@@ -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]