voidmachine 0.0.0 → 5.0.0

package/core-assets/skills/void-plan-review/SKILL.md

@@ -0,0 +1,128 @@
+---
+name: void-plan-review
+description: "Critique a written plan (not a diff) via four lenses: CEO premise/ambition, Eng test-coverage, Design states/slop, DevEx time-to-first-value. Proposes findings; the author disposes."
+---
+
+# plan-review — voidcorp craftsman edition
+
+`void-brainstorm` pressure-tests the idea and `void-plan` authors the plan. This skill sits between the written plan and implementation: it **critiques an already-written plan** from up to four expert lenses, surfaces findings one decision at a time, and appends an Implementation Tasks list to the plan. It is read-mostly — it **proposes**; the plan's author (you, via `void-plan`) **disposes**. It never writes code and never restructures the plan itself.
+
+Invoke it on a plan in `docs/specs/` or `docs/plans/` before the plan becomes tickets. Pick one lens, several, or `all` (the orchestrated pass, below).
+
+**Attribution**: see `.source`. Distilled from gstack `/plan-ceo-review`, `/plan-eng-review`, `/plan-design-review`, `/plan-devex-review`, `/autoplan` (methodology only; the runtime and the named-founder rosters are rejected).
+
+---
+
+## The shared contract (every lens obeys this)
+
+- **Scope gate first.** Before reviewing, state what the plan touches and what is explicitly NOT in scope. A plan touching > 8 files or > 2 new services is a size smell — flag it before anything else.
+- **One finding = one decision.** Surface findings interactively, one at a time, each as a concrete decision with 2-3 options (always including "do nothing / defer") and a recommendation mapped to a stated preference. Never dump a wall of findings.
+- **Severity**: `P1` blocks ship · `P2` same-branch follow-up · `P3` later. Effort is dual-scaled (human hours vs AI-agent minutes — completeness is cheap when an agent implements).
+- **Findings become tasks, not edits.** The lens appends an Implementation Tasks list (P1/P2/P3) to the plan. It does not silently rewrite the plan; the author folds the fixes in. Registries the plan should already contain (Not-in-scope, What-already-exists, diagrams) are `void-plan`' job — the lens flags their absence, it does not own them.
+- **Verdict**: `CLEARED` (no P1 unresolved) or `NOT CLEARED` with the blocking findings named.
+- **Optional second opinion.** For a high-stakes plan, run one independent pass (a fresh subagent, or a second model) and surface only where it disagrees — cross-model tension is signal.
+
+---
+
+## Lens: CEO — is this the right thing, at the right ambition?
+
+The only lens that may challenge the **premise** and say "scrap it, do this instead." It accepts nothing as given.
+
+- **Premise & leverage**: right problem? a cheaper reframing? real outcome vs a proxy metric? cost of doing nothing? what existing code already solves each sub-problem?
+- **Trajectory**: current → delta → 12-month ideal. Reversibility 1-5 (one-way vs two-way door); path dependency; debt introduced; "obvious to a new engineer in 12 months?"
+- **Alternatives are mandatory**: 2-3 approaches, weighting *minimal-viable* and *ideal-architecture* equally, each with effort/risk/reuse; recommend one; do not proceed without approval. (Authoring the chosen approach is `void-plan`' job — the lens forces the comparison, not the write-up.)
+
+**Scope mode** (pick once, up front — this is the plan-level 10x move):
+- `EXPANSION` — cathedral: run the 10x check, sketch the Platonic-ideal version, name ≥ 5 delight opportunities. Default for greenfield.
+- `SELECTIVE` — hold rigor as the baseline, then offer neutral expansion candidates + platform potential to cherry-pick. Default for an enhancement.
+- `HOLD` — maximum rigor, no expansion; > 8 files / > 2 services is a smell. Default for a bugfix.
+- `REDUCTION` — ruthless minimum. Default for a > 15-file plan.
+
+**Verdict shape**: CRITICAL GAP / WARNING / OK per area, plus the unresolved decisions.
+
+---
+
+## Lens: Eng — is this buildable, testable, and will it not break?
+
+The gating lens. Owns the deep **test-coverage trace** no other lens does. Four sections, each answered even when "no issues":
+
+- **Architecture**: boundaries and dependency direction, coupling / SPOFs, scaling, security architecture, the distribution/build pipeline, and one realistic production-failure scenario per new codepath.
+- **Failure modes**: every codepath walked for four data paths — happy / nil / empty / upstream-error. A failure that is neither rescued nor tested is a CRITICAL GAP.
+- **Tests**: detect the framework; trace every branch, error, and null path; map interaction edge cases (double-submit, navigate-away, stale data, slow network, concurrency); decide unit vs E2E vs eval per behavior. **A regression fix ships with a test — non-negotiable.** Emit a coverage map of what is and isn't covered.
+- **Performance**: N+1, unbounded memory, missing caching on hot paths.
+
+**Output**: per-finding `[severity] (confidence N/10) file:line`, and quote the line that motivates each finding (no quote → it is unverified, drop the confidence). Verdict CLEARED / NOT CLEARED gates the plan.
+
+---
+
+## Lens: Design — what does the user perceive on screen?
+
+Scope-gated: no UI in the plan → skip. Judges what reaches the user's eyes.
+
+- **Information architecture**: explicit primary / secondary / tertiary emphasis per screen.
+- **Interaction-state coverage**: every state the user actually hits — loading, empty, error, success, partial — described as what the user *sees*. A missing state is a first-class plan gap, not a detail.
+- **Journey & emotional arc**: the 5-second / 5-minute / 5-year read of the feature.
+- **AI-slop risk**: classify the surface (marketing vs app-UI vs hybrid) and hold it to the matching bar; reject generic-AI-generated patterns. (Bar and blacklist re-derived from OpenAI's "designing delightful frontends" + Krug — cited in `.source`, composes with `void-frontend-design` / `void-ui-review`.)
+- **Responsive & a11y**: per-viewport intent, keyboard path, ARIA, 44px targets, 4.5:1 contrast — as plan requirements, not afterthoughts.
+
+**Output**: rate each dimension `N/10 → M/10` with the fix written into the plan; "design-complete" when every dimension ≥ 8.
+
+---
+
+## Lens: DevEx — is the developer-facing surface a good journey?
+
+Scope-gated: no API / CLI / SDK / library / docs surface → skip. Audits the developer journey from "never heard of it" → hello-world → upgrade. Signature metric: **time-to-first-value (TTHW)**, scored against real competitors (verify with a web search, do not invent numbers).
+
+- **Getting started**: one-command install, try-before-install, steps to a working example.
+- **Interface design**: guessable naming, sensible defaults, coverage vs dropping to raw HTTP, progressive disclosure.
+- **Error messages**: trace three real error paths — each names the problem, the cause, the fix, and links docs.
+- **Docs**: findable in 2 minutes, copy-paste works, version-matched.
+- **Upgrade path**: blast radius, deprecation warnings, codemods, semver honored.
+- **Dev environment**: LSP autocomplete, non-interactive CI, types, hot reload, cross-platform.
+
+**Output**: a DX scorecard (each dimension Score/Prior/Trend + TTHW tier + competitive rank); TTHW > 10 min is blocking; any dimension < 6 is critical DX debt. This lens judges the *plan's promises*; once the surface ships, `void-devex-audit` measures the reality against them.
+
+---
+
+## `all` — the orchestrated pass (replaces gstack autoplan)
+
+Runs the applicable lenses in the fixed order **CEO → Design → Eng → DX** (Design/DX skipped when their scope gate is empty). The order is load-bearing: each phase completes and writes its findings before the next. autoplan is a **mode here, not a separate skill** — once the lenses are one skill, an orchestrator that "runs the four" is a mode, not a new subject (YAGNI).
+
+Between phases, auto-decide only the safe class; escalate the rest:
+- **Decision taxonomy**: *Mechanical* (one correct answer) → auto-decide. *Taste* (defensible either way) and *User-challenge* (contradicts a stated goal) → surface to the human, never auto-decide.
+- **Decision principles** for the Mechanical class: choose completeness; fix the whole blast radius (auto-approve in-radius expansions under ~1 day / 5 files / no new infra); when two fixes are equivalent, take the cleaner one without agonizing; reject duplication, reuse; explicit-and-graspable beats clever; bias toward flagging over blocking.
+- **Cross-lens synthesis**: a concern raised by 2+ lenses is a high-confidence theme (the dedup that makes the multi-lens pass worth more than four solo runs).
+- **One final gate**: present the aggregated, deduped task list and the auto-decision audit trail; the human approves / overrides / challenges / revises-and-re-runs the affected lens. The pass drives to this gate; it never auto-applies plan edits beyond appending the task list.
+
+---
+
+## Composition & boundaries
+
+- **Downstream of `void-plan`** (which authors the plan) and **upstream of implementation** (`void-implement`). It reviews the artifact `void-plan` produced.
+- **Not `void-brainstorm`**: brainstorm pressure-tests the *idea* (is there demand?); plan-review critiques the *written plan* (is it the right shape, buildable, complete?). Different artifact, different question.
+- **Not `void-code-review`**: that reviews a *diff*; this reviews a *plan* before any code exists.
+- **Not `doctrine-critic`**: that judges a diff against VoidCorp doctrine; this critiques a plan across product/eng/design/DX lenses.
+- **Composes with `void-frontend-design` / `void-ui-review`** (the Design lens defers UI build-craft and audit to them), `void-devex-audit` (the DevEx lens's shipped-surface counterpart — this judges the plan, that measures the deployed reality), and `void-security-guidance` / `void-security-audit` (the Eng lens routes a deep security concern there).
+
+---
+
+## Anti-rules
+
+- MUST NOT rewrite the plan — it appends a findings/task list; the author folds fixes in.
+- MUST NOT own plan structure or registries (Not-in-scope, diagrams) — that is `void-plan`.
+- MUST NOT re-litigate the idea's demand — that is `void-brainstorm`.
+- MUST NOT review code or a diff — that is `void-code-review`.
+- MUST NOT auto-decide a Taste or User-challenge call — those go to the human.
+- MUST NOT dump findings in bulk — one finding, one decision.
+- MUST NOT vendor the gstack runtime or the named-founder "how great X think" rosters.
+
+---
+
+## Final rule
+
+```
+Written plan → pick lens(es) → one finding at a time → Implementation Tasks appended → CLEARED verdict.
+The lens proposes; the author disposes. Otherwise → it is not voidcorp plan-review.
+```
+
+A plan reviewed by the right lens before it becomes tickets is cheaper by an order of magnitude than the same gap found in code review.

package/core-assets/skills/void-plan-review/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-qa/.source

@@ -0,0 +1,15 @@
+Sources for `void-qa` skill (see `docs/plans/skill-audits/void-qa.md` for the full distribution matrix):
+
+- gstack /qa (1642 LOC, "Test → Fix → Verify") — VENDORED (DEV-390): the QA methodology. Kept + distilled: the QA-engineer-AND-bug-fixer role, test-as-a-user (never read source to test), the modes (diff-aware default / full / quick / regression), the clean-working-tree precondition for atomic fix commits, the Orient → Explore → Document → Score → Triage → Fix-loop → Self-regulate → Report workflow, the per-page checklist (interactive / forms / navigation / empty-loading-error-overflow states / console-after-every-interaction / responsive), the two evidence tiers (interactive before/after vs static single shot), the health-score rubric (per-category deductions + weights), the atomic `fix(qa):` commit-per-fix + re-verify + regression-test + verified/best-effort/reverted classification, and the WTF self-regulation stop-and-ask heuristic.
+- gstack /qa-only (1214 LOC) — VENDORED as the `--report-only` mode (phases through Report, no fix loop). No second skill: report-only is a mode, not a subject.
+- gstack /design-review (1952 LOC), live half — the live-screenshot visual QA is re-homed here as the "visual pass" that COMPOSES `void-ui-review` (which already owns the visual-craft methodology: register split, squint test, interaction-state coverage, technical audit). This skill drives the browser; void-ui-review supplies the bar. No duplication.
+- REPOINTED, not ported: every gstack `$B <cmd>` browse-daemon call (goto/snapshot/click/fill/console/viewport/screenshot) maps onto the `mcp__claude-in-chrome__*` MCP tools (navigate/computer/read_page/form_input/read_console_messages/resize_window/gif_creator/read_network_requests), with `tabs_context_mcp` called first. Full daemon port was ~190 CDP/Chromium files and weeks of work; the re-point is the same prose on a browser layer Claude Code already ships. This IS the epic's "Vague 4" claude-in-chrome re-point.
+- REJECTED (gstack runtime, not doctrine): the browse binary + `./setup` + bun bootstrap, CDP-mode detection, gbrain/learnings search + log, telemetry/review-log, the `~/.gstack/projects` + chromium-profile cookie import (claude-in-chrome uses the user's real logged-in Chrome, so cookie import is moot — documented as a rejection per the ticket), TESTING.md / CLAUDE.md auto-edit.
+- REJECTED (scope creep, routed elsewhere): the entire Test-Framework-Bootstrap block (detect runtime → research → install → write TESTING.md). Standing up a test framework is `void-tdd`/`void-testing`, not QA. A QA skill that also bootstraps a framework is two subjects; the ticket's "un sujet, un skill" forbids it.
+
+Strategy: distill + repoint. One skill, one subject ("live browser QA of a running web app"). qa-only folds in as a mode; the visual pass composes ui-review; the regression test composes tdd/testing. < 30% overlap is structural: this drives the browser + functional/fix loop; ui-review judges visuals; devex-audit audits dev surfaces; tdd/testing author suites.
+
+Companion change (same ticket, gated by Folpe): the "Never use mcp__claude-in-chrome__*" rule in ~/.claude/CLAUDE.md predates the claude-in-chrome adoption and makes this skill unusable; it is lifted in the same move.
+
+DEV-444 adaptation: UI evidence now covers mobile and desktop applicable states, carries the current
+diff identity, and is handed to a fresh Visual Craft Director; unavailable browser proof blocks.

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

@@ -0,0 +1,103 @@
+---
+name: void-qa
+description: "Live browser QA of a running web app via the claude-in-chrome MCP: systematic exploration, edge/error/empty states, atomic fix loop, evidence-backed report. Report-only mode available."
+---
+
+# qa — voidcorp craftsman edition
+
+You are a QA engineer AND a bug-fix engineer. Test a running web app like a real user — click everything, fill every form, check every state — using the **claude-in-chrome MCP** to drive the browser. When you find a bug, fix it in source with an atomic commit, then re-verify. Produce a structured report with before/after evidence.
+
+This tests the *shipped, running app* through a real browser. It is not unit/E2E authoring (`void-tdd` + `void-testing` own that), and it does not judge visual craft from code (`void-ui-review` owns that — this skill composes it for the live visual pass).
+
+**Attribution**: see `.source`. Vendored from gstack `/void-qa` + `/qa-only` + the live half of `/design-review`, repointed off the gstack browse daemon onto the claude-in-chrome MCP already present in Claude Code. The gstack runtime (browse binary, gbrain/learnings, telemetry, `~/.gstack` artifacts, test-framework bootstrap) is rejected.
+
+---
+
+## When to invoke
+
+- Verifying a running app after a change (the default: a feature branch, "does it actually work?").
+- Auditing a deployed site for bugs and broken flows.
+- A report-only pass (no fixes) before a review or handoff.
+
+Do NOT use this to author a unit/E2E suite (`void-tdd`/`void-testing`), to audit UI craft from code (`void-ui-review`), or to audit a dev-facing API/CLI/SDK surface (`void-devex-audit`).
+
+## Browser tooling: claude-in-chrome (load first)
+
+The execution primitives are the `mcp__claude-in-chrome__*` tools. If they are deferred, load the core set in **one** ToolSearch call before anything else:
+
+`select:mcp__claude-in-chrome__tabs_context_mcp,mcp__claude-in-chrome__navigate,mcp__claude-in-chrome__computer,mcp__claude-in-chrome__read_page,mcp__claude-in-chrome__tabs_create_mcp,mcp__claude-in-chrome__read_console_messages,mcp__claude-in-chrome__form_input,mcp__claude-in-chrome__gif_creator,mcp__claude-in-chrome__resize_window,mcp__claude-in-chrome__read_network_requests`
+
+Command mapping from the old gstack browse (`$B`) to the MCP:
+
+| Need | claude-in-chrome tool |
+|------|-----------------------|
+| Session tab context (**call first**) | `tabs_context_mcp` |
+| Open the target in a **new** tab | `tabs_create_mcp` |
+| Navigate | `navigate` |
+| Click / type / screenshot | `computer` |
+| Fill a form field | `form_input` |
+| Read DOM / accessibility tree | `read_page` |
+| Console errors after an action | `read_console_messages` (filter with `pattern`) |
+| Network (data-fetch 404s) | `read_network_requests` |
+| Responsive viewport | `resize_window` |
+| Record a repro | `gif_creator` |
+
+## Hard constraints (claude-in-chrome reality)
+
+- **`tabs_context_mcp` first**, every session. Never reuse a tab id from another session; open a fresh tab with `tabs_create_mcp` unless the user names a tab.
+- **Permissions are per-site.** If a site is not authorized and permission is refused, STOP and tell the user which site to allow — never loop retrying the same denied call.
+- **Never trigger a JS dialog** (`alert`/`confirm`/`prompt`) or a browser modal — they block the extension and kill the session. For repro debugging use `console.log` + `read_console_messages`, not `alert`. Warn the user before touching any element that may open one.
+- **Not headless.** claude-in-chrome drives the user's real, interactive Chrome (already logged in — no cookie import, no `~/.gstack/chromium-profile`). QA in a cloud/cron session with no interactive Chrome is **out of scope** — an assumed limitation the browse daemon did not have; say so rather than faking it.
+- After 2-3 failed tool calls, a page that will not load, or unexpected tangents: stop and ask the user, do not keep retrying.
+
+## Modes
+
+- **Diff-aware** (default on a feature branch with no URL) — read the branch diff, map changed files to affected pages/routes, detect the local dev server, test only those pages plus a homepage smoke. The common case.
+- **Full** (a URL is given) — systematic exploration of every reachable page; 5-10 well-evidenced issues; health score.
+- **Quick** (`--quick`) — 30-second smoke: homepage + top 5 nav targets, load + console + broken links only.
+- **Regression** (`--regression <baseline.json>`) — run full, then diff against a prior baseline: fixed vs new vs score delta.
+- **Report-only** (`--report-only`, the old `/qa-only`) — phases through Report, then STOP. No fix loop, no commits.
+
+## Precondition: clean working tree
+
+Each fix must be its own atomic commit, so before fixing, `git status --porcelain` must be empty. If dirty, ask the user to commit / stash / abort first (recommend commit — preserve their work before QA adds fix commits). Report-only mode may run on a dirty tree.
+
+## Workflow
+
+1. **Orient** — `tabs_context_mcp`, open the target in a new tab, screenshot, read the page, check console. Detect the framework (Next.js `__next` / `_next/data`; Rails `csrf-token`; SPA = client routing) and note it. For an SPA, map nav from `read_page` (client routes, not raw links).
+2. **Explore** — visit pages systematically. Per page: visual scan of the screenshot; click interactive elements; fill + submit forms (empty, invalid, edge, overflow); walk navigation in and out; exercise **the states a user actually hits — empty, loading, error, overflow**; check console after every interaction; for responsive, `resize_window` then **verify the screenshot dimensions actually changed** — on some setups it resizes the window without re-rendering to a true mobile viewport, so confirm before trusting a "mobile" shot (else note responsive as unverified). Depth over breadth: more time on core flows (auth, checkout, search), less on static pages.
+3. **Document** — write each issue the moment you find it, never batch. Two evidence tiers: an **interactive** bug gets a before-screenshot, the action, an after-screenshot (a `gif_creator` repro for a flow); a **static** bug gets one annotated screenshot. Verify a bug reproduces once before writing it. For a UI quality pass, capture mobile and desktop for every applicable state and bind each capture to the current diff hash; a later CSS/UI diff makes it stale. Redact credentials (`[REDACTED]`). Surface every screenshot to the user (Read the file) — otherwise it is invisible.
+4. **Health score** — per-category 0-100 (Console, Links, Visual, Functional, UX, Performance, Content, Accessibility) minus severity deductions (critical -25 / high -15 / medium -8 / low -3), weighted average. Record it as the baseline.
+5. **Visual pass** — for visual/interaction judgment on the live screenshots, compose `void-ui-review`, then hand the current-diff evidence to `core:visual-craft-director` in fresh context. This skill drives the browser; `void-ui-review` supplies the craft bar; the specialist owns the independent verdict. If the browser or required captures are unavailable, report the UI pass blocked rather than certifying from prose.
+6. **Triage** — sort by severity; fix per tier: `--quick` critical+high · standard (default) +medium · `--exhaustive` +low. Mark unfixable-from-source (third-party, infra) as deferred.
+7. **Fix loop** (skipped in report-only) — per issue in severity order: locate source (grep/glob — only now do you read code); make the **minimal** fix (no refactor, no scope creep); commit one fix `fix(qa): <issue> — <desc>`; re-test the page with a before/after pair + console + a regression test that reproduces the bug (compose `void-tdd`/`void-testing` — assert behavior, not "it renders"); classify **verified / best-effort / reverted** (`git revert` on a regression → defer).
+8. **Self-regulation** — every 5 fixes or after any revert, stop and evaluate: reverts, fixes touching many files, all-low-severity remaining, and unrelated-file edits all raise the "this is going wrong" signal. Above the threshold, or past a hard cap of ~50 fixes, STOP and show the user before continuing.
+9. **Report** — issues with severity + evidence + fix status (verified/best-effort/reverted/deferred) + commit SHA; health-score delta baseline → final; a one-line PR summary ("QA found N, fixed M, health X → Y"). If the final score is worse than baseline, warn prominently. Write it under the project's report location, not `~/.gstack`.
+
+## Composition & boundaries
+
+- **With `void-ui-review`** — this skill owns driving the browser and the functional/fix loop; `void-ui-review` owns the visual-craft judgment applied to the live screenshots (step 5). No restated design rules here.
+- **With `void-tdd` / `void-testing`** — the regression test in the fix loop is authored per their discipline. This skill finds bugs in a running app; they own how the test that locks the fix is written.
+- **Not `void-devex-audit`** — that audits a developer-facing surface (API/CLI/SDK/docs journey, TTHW); this QAs an end-user web app in a browser. Different surface.
+- **Not E2E authoring** — Playwright suites are `void-testing`'s output; this is exploratory human-style QA of the deployed thing.
+- **Supersedes** gstack `/void-qa`, `/qa-only`, and the live-screenshot half of `/design-review`.
+
+## Anti-rules
+
+- MUST NOT test by reading source — test as a user; read code only in the fix loop, to locate the bug.
+- MUST NOT trigger a blocking JS dialog / modal — it kills the claude-in-chrome session.
+- MUST NOT reuse a cross-session tab id, or assume a headless/CI browser — mark non-interactive sessions out of scope.
+- MUST NOT bundle fixes — one atomic `fix(qa):` commit each; revert on regression.
+- MUST NOT include credentials in the report — `[REDACTED]`.
+- MUST NOT bootstrap a test framework or edit CI/CLAUDE.md — that is `void-tdd`/`void-testing`, not QA.
+- MUST NOT vendor the gstack runtime (browse binary, gbrain/learnings, telemetry, `~/.gstack` artifacts, cookie-profile import).
+
+## Final rule
+
+```
+Running app → load claude-in-chrome (tabs_context first) → orient → explore every state → document with
+evidence → score → triage → atomic fix + regression test + re-verify → self-regulate → report.
+Report-only stops before the fix loop. Otherwise → it is not voidcorp qa.
+```
+
+QA is the discipline of hitting the app the way a user will, before the user does — and, when it breaks, fixing it under the same evidence bar that found it.

package/core-assets/skills/void-qa/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-refactor/.source

@@ -0,0 +1,9 @@
+Sources for `void-refactor` skill (see `docs/plans/skill-audits/void-refactor.md` for full audit):
+
+- Kent Beck "Tidy First?" 2023 — https://www.oreilly.com/library/view/tidy-first/9781098151232/ — separate Tidyings from Behavior Changes, Two-Hat principle
+- Martin Fowler "Refactoring" 2nd ed. 2018 — https://martinfowler.com/books/refactor.html — catalog of named refactors + smells catalog
+- Michael Feathers "Working Effectively with Legacy Code" 2004 — Sprout Method, Wrap Method for legacy/untested code
+- citypaul/.dotfiles refactor notes — Tidy-First commit cadence
+- Joshua Kerievsky "Refactoring to Patterns" — referenced, used sparingly (not daily practice)
+
+Strategy: distill. Author for void-machine with two modes mirroring tdd. Reject monolithic-rewrite framing. Companion hooks: tidying-commit-prefix, refactor-named-grep. Allowed Fowler names in ../../hooks/fowler-refactors.txt.

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

@@ -0,0 +1,220 @@
+---
+name: void-refactor
+description: Tidy-First. Tidyings commit separately from behavior changes (Two-Hat). Named Fowler refactors only. Tests stay green. Two modes (strict/souple). Use when improving structure without behavior change.
+---
+
+# refactor — voidcorp craftsman edition
+
+Refactoring changes structure, not behavior. The moment behavior changes, you stop refactor and switch to `void-tdd`. Tidyings and Behavior Changes never share a commit. Named refactors from the Fowler catalog, executed mechanically. Tests stay green at every step.
+
+**Attribution**: see `.source` in this directory. Primary sources: Kent Beck "Tidy First?" 2023, Martin Fowler "Refactoring" 2nd ed. 2018, Michael Feathers for legacy code.
+
+---
+
+## The Two-Hat principle (Beck)
+
+You wear ONE hat at a time:
+
+- **Tidying hat**: structure changes only. No new behavior. No new tests. Tests stay green.
+- **Behavior Change hat**: new feature, bugfix, anything that changes observable outcomes. Goes through `void-tdd`.
+
+Switching hats means committing. Mixing hats in one commit is rejected.
+
+### Why this matters
+
+A commit that does both is unreviewable (the reviewer cannot tell which line is structural and which is functional) and unrevertable (you cannot back out the structural part without losing the feature). The discipline forces clarity.
+
+---
+
+## Cycle
+
+```
+1. Pick a smell (or a Fowler trigger)
+2. Pick a named refactor (Fowler catalog)
+3. Execute mechanically (IDE refactor when possible)
+4. Run tests → green
+5. Commit with the refactor name in the message
+6. (loop until done)
+```
+
+If tests turn red at step 4, you have changed behavior. Back out, recategorize as `void-tdd` work, restart.
+
+---
+
+## Modes
+
+| Mode | Posture | When |
+|---|---|---|
+| **strict** | One Tidying = one commit, named after the Fowler refactor | When `void-tdd` is in strict for the target paths |
+| **souple** | Mechanical batch Tidyings allowed (same Fowler move applied N times, e.g., 10 Rename Variable) | When `void-tdd` is in souple, or target paths are in `exploratory` |
+
+`exploratory` is not a refactor mode — exploratory code is meant to be thrown away, not refactored.
+
+### Auto-selection
+
+Mirror the `void-tdd` mode for the target paths. Override via `// refactor-mode: strict` or `// refactor-mode: souple` at the file header.
+
+---
+
+## Named refactors (Fowler catalog)
+
+Use a name from the catalog. Vague "restructure somehow" is rejected.
+
+### Common refactors
+
+| Refactor | When |
+|---|---|
+| **Extract Function** | A block of code does a sub-task that has a name. Give the name a function. |
+| **Inline Function** | A function's body is as clear as its name. Inline it. |
+| **Extract Variable** | An expression is hard to understand. Name it with a `const`. |
+| **Inline Variable** | A variable's name adds no clarity. Inline. |
+| **Rename Variable** / **Rename Function** | Better name. Use IDE Rename Symbol. |
+| **Move Function** | The function belongs to another module / class. |
+| **Replace Conditional with Polymorphism** | A `switch` on type is repeated. Move dispatch to the types. (Use sparingly; discriminated unions + exhaustive switch is often better in TS than classes.) |
+| **Replace Magic Number with Symbolic Constant** | Magic numbers (or magic strings) without context. Name them. |
+| **Decompose Conditional** | Complex `if` expression. Extract Variable on each branch's condition + Extract Function on each body. |
+| **Replace Primitive with Branded Type** | Composes with `void-typescript-strict`. `string` UserId → `UserId` branded. |
+| **Replace Loop with Pipeline** | Imperative loop accumulating into an array. Use `.map().filter().reduce()`. |
+| **Replace Function with Command** | Function with many parameters and state. Object with a `run()` method. |
+| **Separate Query from Modifier** | A function that returns AND mutates. Split into `getX()` and `setX()`. |
+
+The allowed-names list is maintained in `../../hooks/fowler-refactors.txt`. The companion hook `refactor-named-grep` warns on `refactor:` commits without a recognized name.
+
+### When to use a named refactor
+
+- **Code smell triggers** a refactor. Smells from Fowler's catalog: Long Function, Long Parameter List, Divergent Change, Shotgun Surgery, Feature Envy, Data Clumps, Primitive Obsession (→ branded types), Speculative Generality, Comments-as-Apology.
+- **A new feature** would be hard to add into the current shape → refactor BEFORE adding.
+- **A just-implemented feature** surfaced a structural insight → refactor AFTER.
+
+NOT triggers:
+
+- "The code is ugly" without a current task — leave it
+- "Anticipating future flexibility" — YAGNI
+
+---
+
+## Tidy-First vs Tidy-After (Beck)
+
+| Pattern | When |
+|---|---|
+| **Tidy First** | Adding the feature into current shape is hard. Tidy the area first, in separate commits, then add the feature. |
+| **Tidy After** | The feature reveals the better structure. Add the feature (via `void-tdd`), then tidy in separate commits. |
+
+Either is fine. Choose by which path is cheaper.
+
+---
+
+## Sprout / Wrap for legacy / untested code (Feathers)
+
+When the target code has no tests and you need to change it:
+
+- **Sprout Method**: do not modify the legacy code. Sprout the new logic into a new, tested function. Call the new function from the legacy code at a clear point.
+- **Wrap Method**: when the legacy function is called many places, wrap it: rename `oldFn` → `oldFnRaw`, write a new `oldFn` that delegates to `oldFnRaw` and adds the new behavior (with tests).
+
+Both let you add tested behavior without refactor untested code first. Refactor inward once a test seam exists.
+
+---
+
+## Commit cadence
+
+### Strict mode
+
+```
+refactor: extract validateEmail helper
+refactor: rename userQty to userCount
+refactor: move formatCurrency to @repo/format
+feat: add invoice discount calculation
+```
+
+Each refactor commit names a Fowler move. Each refactor is small enough to review at a glance.
+
+### Souple mode
+
+```
+refactor: rename UserDto fields to camelCase (15 occurrences, IDE Rename)
+refactor: replace inline magic numbers with TAX_RATE constants (8 sites)
+feat: add invoice discount calculation
+```
+
+Batch is allowed if the move is the same Fowler refactor applied mechanically. Multiple different refactors do NOT batch — that drifts back to "cleanup."
+
+---
+
+## Banned
+
+### Big-bang rewrites
+
+"Let's rewrite this module" is not a refactor — it is a feature project. Goes through `void-brainstorm` + `void-plan` + `void-tdd`. Rewrites lose context, regress invariants, and never quite catch up to the original.
+
+### `refactor: misc cleanup` commits
+
+Either name the Fowler refactor, or split. This is the path to a `git log` that says nothing.
+
+### Mixed-intent commits
+
+`refactor: extract helper and add validation` mixes hats. Split:
+
+- `refactor: extract validateEmail helper`
+- `feat: add stricter email validation`
+
+The companion hook `tidying-commit-prefix` warns on `refactor:` commits whose body indicates behavior-change keywords (`feat`, `fix`, `void-implement`, `add`).
+
+### Speculative refactor for future flexibility
+
+YAGNI. Refactor when current code resists current task. Future-proof abstractions cost more than they save in > 80% of cases.
+
+### Pattern-target refactor as a default
+
+Reach for "Refactor toward Strategy / Visitor / etc." only when the pattern is the documented destination. Daily practice is the Fowler catalog, not the GoF.
+
+---
+
+## Composition with other skills
+
+- **With `void-tdd`**: the R step of RED-GREEN-REFACTOR delegates here. The refactor mode mirrors the tdd mode.
+- **With `void-testing`**: tests stay green at every step. This skill must not add new tests (adding tests = behavior addition).
+- **With `void-code-review`**: review surfaces refactor candidates ("function has 4 levels of nesting → Extract Function"). This skill decides + executes.
+- **With `void-hexagonal-architecture`** / **`void-domain-driven-design`**: cross-boundary refactors (Move Class across packages) — the architecture skill decides target placement; this skill executes mechanically.
+- **With `void-typescript-strict`**: "Replace Primitive with Branded Type" is a Fowler-Primitive-Obsession-driven move executed here, validated by typescript-strict.
+
+---
+
+## Companion hooks
+
+- **`tidying-commit-prefix`** (commit-msg) — warn if `refactor:` subject is paired with behavior-change keywords in body
+- **`refactor-named-grep`** (commit-msg) — warn if `refactor:` subject does not contain a known Fowler refactor name (allowlist in `fowler-refactors.txt`)
+
+See `../../hooks/`.
+
+---
+
+## Anti-rules
+
+- MUST NOT change observable behavior. Any behavior change → stop, switch to `void-tdd`.
+- MUST NOT add new tests (that is a behavior addition or a coverage backfill, both via `void-tdd`).
+- MUST NOT decide whether the refactor is worth doing (taste / cost call escalates to user).
+- MUST NOT batch unrelated refactors in one commit, even in `souple`.
+- MUST NOT silently allow "cleanup" mixed-intent commits.
+
+---
+
+## When you are stuck
+
+| Problem | Solution |
+|---|---|
+| Tests turn red on a refactor | Behavior changed. Back out. Recategorize as `void-tdd` work. |
+| Cannot pick a Fowler name | The change is probably a behavior addition disguised as structural. Re-examine. |
+| Code has no tests | Sprout Method or Wrap Method (Feathers) first. Then refactor inward. |
+| Refactor crosses package boundary | Compose with `void-hexagonal-architecture` matrix first. Then execute. |
+| Want to "clean up" | Pick a current task that triggers the cleanup, or leave it. |
+
+---
+
+## Final rule
+
+```
+Refactor → named Fowler move, tests green at every step, separate commit, no behavior change.
+Otherwise → it is not a voidcorp refactor.
+```
+
+Refactoring is mechanical. The risk is in mixing it with feature work, not in the move itself.

package/core-assets/skills/void-refactor/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: 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-retrospective/.source

@@ -0,0 +1,9 @@
+Sources for `void-retrospective` skill (see `docs/plans/skill-audits/void-retrospective.md` for full audit):
+
+- gstack /retro (1770 LOC) — VENDORED (DEV-396): the git-history signal methodology (window gathering: commits/authors/files/types, hotspots, test-vs-prod ratio, PR size, regressions, recurring-fix files). Its data-gathering reads gstack state (~/.gstack/, timeline.jsonl); the harness version reads git log / PRs (gh) / .void/usage.log instead.
+- Rejected (documented): the quantified-self gamification — focus score, ship-of-the-week, personal/team streaks, the week-over-week leaderboard. Productivity gamification, not craftsman doctrine: it optimizes a number, not the code. Kept the signal methodology, dropped the scoring/ranking apparatus.
+- Rejected: all gstack runtime (preamble, gbrain, telemetry, voice, plan-mode, history-save to gstack paths).
+
+Strategy: distill + dedicated skill. Its mapped target `void-learn` no longer exists (fused into learn, issue #75), and a periodic window review is a distinct subject from learn's point capture — folding would violate one-skill-one-subject and overflow 400 LOC. So a light dedicated skill that FEEDS learn. See docs/DECISIONS.md (2026-07-10, DEV-396) and the DEV-386 split decision that spun this out.
+
+No companion hooks; it reads and reports, writing nothing into doctrine (learn owns the HITL write).

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

@@ -0,0 +1,71 @@
+---
+name: void-retrospective
+description: "Periodic engineering retro over a window: read git log / PRs / .void, surface signals (hotspots, test ratio, commit types, regressions), turn them into improvement decisions feeding learn."
+---
+
+# retrospective — voidcorp craftsman edition
+
+`void-learn` catches ONE lesson the moment it appears. This skill is the opposite cadence: a deliberate look back over a **window** (a week, a cycle, a sprint) to find the patterns no single moment surfaces — what the codebase's own history is telling you. It reads signals, turns them into concrete improvement decisions, and routes each durable pattern into `void-learn`.
+
+Invoke it on a cadence ("weekly retro", "retro since the last release"). It reads and reports; it does not change code.
+
+**Attribution**: see `.source`. Distilled from gstack `/retro` — the git-history signal methodology, with the quantified-self gamification (focus score, ship-of-the-week, streaks) deliberately dropped as out of craftsman scope.
+
+---
+
+## Data sources — agnostic and durable
+
+Read only sources that survive any tool teardown. **Never** `~/.gstack/` or gstack telemetry.
+
+- **git log** over the window: commits with author, timestamp, subject, files changed, insertions/deletions. The spine of the retro.
+- **Conventional-commit types** parsed from subjects: `feat` / `fix` / `void-refactor` / `test` / `chore` / `docs`.
+- **PRs** via `gh pr list --state merged --search "merged:>=<date>"` when a GitHub remote exists.
+- **`.void/runs/*/events.jsonl`** (plus legacy logs when present): which skills actually fired.
+- **Test vs production files**: classify changed paths (`test/`, `spec/`, `__tests__/`, `*.test.*`) to compute the test-to-prod ratio.
+
+If a source is absent (no remote, no `.void/`), note it and proceed with what exists.
+
+## Signals to compute (not scores)
+
+Report each as an observation with the evidence, not a leaderboard number:
+
+- **Commit-type mix** — the `feat`/`fix`/`void-refactor`/`test` ratio. A fix-heavy window points at a quality or root-cause gap; a zero-refactor window at accreting debt; a zero-test window at a discipline slip.
+- **Hotspots** — the files changed most often. A file touched in many commits/PRs is either the active surface or a design pressure point.
+- **Recurring-fix files** — files that received multiple `fix:` commits. Composes with `void-debug`: a file fixed three times is an architectural smell, not three coincidences.
+- **Test-to-prod ratio** — production LOC changed vs test LOC changed. A ratio trending toward zero is the signal that matters most.
+- **PR size distribution** — small vs large PRs. A window of large PRs points at insufficient vertical slicing (composes with `void-plan`).
+- **Regressions** — `fix:` commits that reference a prior feature, or reverts. Each is a candidate for a "prevention" decision.
+
+## Output — a report that ends in decisions
+
+1. **Window summary** — dates, commit count, PR count, the signals above with their evidence (file:count, ratio, examples). Plain observations, no gamified ranking.
+2. **Improvement decisions** — the point of the retro. For each signal that warrants action, state a concrete change: a test to add, a file to refactor, a hook to propose, a convention to adopt. Not a vague "do better."
+3. **Route each durable pattern to `void-learn`** — a decision that generalizes ("this class of bug keeps recurring in the adapter layer") is captured as a lesson, HITL. The retro surfaces the pattern; `void-learn` decides where it belongs and writes it (with confirmation). The retro itself writes nothing into doctrine.
+
+## Rejected — gstack gamification (documented)
+
+Deliberately NOT vendored: the **focus score**, **ship-of-the-week**, **personal/team streaks**, and the week-over-week trend leaderboard. These are quantified-self productivity gamification, not craftsman doctrine — they optimize a number, not the code. The signal methodology (what the git history reveals) is kept; the scoring/ranking apparatus is dropped.
+
+## Composition & boundaries
+
+- **Feeds `void-learn`** — the retro is a *discovery* pass over a window; `void-learn` is the *capture* of one lesson. Different subject, different cadence (window vs point). The retro routes patterns to it, never duplicates its HITL write.
+- **With `void-debug`** — the recurring-fix-file signal is that skill's "recurring bug = architectural smell" seen at the window scale.
+- **With `void-plan`** — a large-PR window is a slicing signal; the fix is smaller vertical slices.
+- **Live/visual dashboards** — deferred; this skill produces a text report. Any richer visualization is out of scope.
+
+## Anti-rules
+
+- MUST NOT depend on `~/.gstack/` or any gstack telemetry (it disappears at teardown).
+- MUST NOT reintroduce the gamification (focus score, ship-of-the-week, streaks).
+- MUST NOT write into doctrine — it proposes decisions and routes durable patterns to `void-learn` (HITL).
+- MUST NOT change code — it reads history and reports.
+- MUST NOT duplicate `void-learn`'s point-capture — this is the window-review cadence.
+
+## Final rule
+
+```
+Window → git log / PRs / .void → signals (types, hotspots, test ratio, regressions) → improvement decisions → route durable patterns to learn.
+Otherwise → it is not voidcorp retrospective.
+```
+
+The history is already telling you where the debt and the recurring pain are. The retro is the discipline of listening to it on a cadence.

package/core-assets/skills/void-retrospective/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]