voidmachine 0.0.0 → 4.0.0

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

@@ -0,0 +1,358 @@
+---
+name: void-autopilot
+description: Use to run the continuous delivery loop, where a curator ranks the backlog, up to four workers each run void-implement to a PR, and a bounded review gates the GitHub merge queue until drained or stopped.
+---
+
+# autopilot
+
+A continuous loop that takes tickets from the tracker to the integration branch without a human
+at each merge. A curator ranks what is worth doing, up to four workers each carry one ticket to
+a pull request, a reviewer reads each one once, and GitHub merges what is green through its merge
+queue. Promotion to the branch that deploys stays human.
+
+**Attribution**: see `.source`.
+
+---
+
+## What this skill does NOT do
+
+It owns no ticket cycle. Every worker runs the canonical `void-implement` skill, whole, once per
+ticket, specialist panel included. If you find yourself writing "then the worker runs the tests,
+then reviews..." inside autopilot, stop: that behaviour has one owner, and two copies drift until
+a ticket gets a different standard depending on how it was started.
+
+It never merges on a flag. Not on the command line, not because the checks are green, not because
+the diff is small. Consent to a machine merge is a durable declaration in the programme --
+`mergeGate: union-reviewed` together with a `deployBranch` -- and there is no `--auto-merge` on
+any path. Under `mergeGate: human` a ready pull request goes to a person; that wait is by design
+and never counts toward the streak that stops the loop. Promotion from the integration branch to the one that deploys stays human
+under both gates.
+
+It never merges a change to the machinery that judges merges. A pull request touching
+`.github/**`, `scripts/independent-review-check.mjs`, `.void/program.md`, `packages/core/hooks/**`,
+what a judging workflow runs from outside `.github`
+(`scripts/promotion-authority.mjs`, `scripts/auto-merge-contract.mjs`, `scripts/verify.mjs`,
+`packages/core/enforce/**`), what judges a publication (`scripts/prepare-release-artifact.mjs`,
+`scripts/verify-release-publication.mjs` and the two release contracts they read), the loop code that believes a verdict and arms a merge (`loop.ts`,
+`loop-observe.ts`, `review-signature.ts`, `commands/autopilot-loop.ts`), or the hooks installed here (`.void/hooks/**`, `.claude/settings.json`,
+`.codex/**`, `.void/config.json`) goes to a person with the file named (`protected-path`). A rename
+counts by its source and its destination. The programme adds paths through
+`autopilot.protectedPaths`; nothing removes from that floor.
+
+It never closes, cancels or deletes a ticket, and it never touches `main`, the secrets or the
+repository settings.
+
+---
+
+## Consent and target
+
+The run takes no argument. `.void/program.md` names the progress provider, its scope, the base and
+the `autopilot` block, so there is nothing to ask: not which ticket, not which provider.
+
+That file is also the consent, and consent is never inferred. An absent `.void/program.md`, a
+`status` other than `executing`, an `autopilot` block that is missing or unreadable, or
+`autopilot.enabled: false` all mean the same thing -- say so and stop. `void-machine autopilot next`
+refuses the same cases; inventing a target claims tickets nobody agreed to hand over.
+
+---
+
+## The cursor between code and model
+
+The model renders narrow, typed judgments; the policy stays in the code. Agents keep their whole
+freedom over the work itself -- ranking, implementing, resolving a conflict, reading a diff. At
+each decision point their answer is closed, and the CLI admits it against a schema before anything
+acts. An answer that does not fit is a refusal naming the field, never an interpretation.
+
+| Decision point | Judgment the model renders | Policy the code applies |
+|---|---|---|
+| Is a ticket workable | `readiness`: `ready`, `needs-enrichment` or `ambiguous`, with a reason | only `ready` gets a slot |
+| What comes next | `queue`: ordered entries, each with a justification and a footprint | the head takes a free slot unless it collides |
+| A conflict after ejection | `conflict`: the conflicting `headSha`, `mechanical` or `semantic`, with a reason | `semantic` waits for a human |
+| A review | `review`: the `headSha` read, round 1 or 2, `blocking[]` each with location, scenario and correction, `advisory[]` | a blocking finding without a scenario is invalid; no merge without a clean verdict on the exact head; two rounds at most |
+
+Slots, collisions, review rounds, stops, resumption and the merge are the kernel's. No agent may
+skip a step, merge, or decide that a refusal does not apply to it.
+
+---
+
+## Four roles, one subject each
+
+**Curator.** Decides what is worth doing next. Touches the tracker, never code.
+
+**Orchestrator.** Runs the loop. Evaluates no ticket, edits no code, reads no diff.
+
+**Workers**, one per slot. Each carries one ticket from claim to an open pull request, in its own
+worktree, by running `void-implement` whole.
+
+**Reviewer.** The independent pass of `void-implement`, run by GitHub itself: the
+`independent-review` job, in a fresh context, on the exact head SHA of every ready pull request.
+There is no second review at merge time: its check is what GitHub requires.
+
+A role that starts doing another's job is the failure this split exists to prevent: an orchestrator
+that "just looks at the diff" becomes a reviewer nobody bounded, and a worker that posts its own
+verdict is a self-review GitHub reads as independent.
+
+---
+
+## Curator
+
+Read the real state of the project before ranking anything: the programme, the specs and plans in
+flight, the code they touch, open pull requests, recent merges, tickets waiting on a human.
+
+Walk the tracker in this order: **Todo, then Backlog, then Triage.** Rank by what the project needs
+-- what unblocks other work, what extends the work in flight, what removes a real risk -- not by
+the priority label. The label is somebody's past guess; the ranking is today's reading of the
+project.
+
+- **Realign the tracker with the ranking.** Change priority or status so the tracker says what the
+  queue says, and leave on every ticket you move a justification of one or two sentences. A move
+  without a reason is indistinguishable from a mistake.
+- **Enrich before ready.** A ticket too vague to implement goes through `void-ticket` before it can
+  be declared `ready`. One that stays ambiguous after that is `ambiguous`: it is set aside with its
+  reason, not guessed at.
+- **Name the ground.** Every queued entry carries a footprint: the paths it will touch, at least
+  one. A ticket without one is not admitted; the kernel routes on footprints and cannot protect
+  ground nobody named.
+- **Never close, cancel or delete.** Not a duplicate, not an obsolete ticket, not one you are sure
+  about. Say so in a comment and leave the decision to a person.
+- **Re-rank after every merge.** A merge changes what is relevant next, so the queue is only valid
+  until the next one lands.
+
+Return the queue as the typed `queue` judgment, at most sixteen entries. The curator can run in the
+orchestrator's session or as its own agent; either way its output is data the kernel admits, not an
+instruction the orchestrator follows.
+
+---
+
+## Orchestrator
+
+The loop is one question asked again and again: `void-machine autopilot next --json`, with the
+tracker state on stdin. The command reads the programme, GitHub, the shared git state and the stop
+signal itself; GitHub is the authority on a merge, so no agent reports it.
+
+What you pipe in is the tracker as you observed it -- `void-machine autopilot --help` gives the
+shape: `schemaVersion: 1`, the curator's `queue`, every ticket in scope with its provider status,
+`humanWait`, pull request, branch, footprint and the raw `readiness` attached to it, the `recent`
+outcomes of this run, the `liveWorkers` you actually have, and `quota` (`low` once the runtime
+reports its limit is near). Pass judgments through raw; the kernel admits each one where it is
+used, so one malformed answer refuses its own decision and nothing else.
+
+Act on each returned action, then ask again:
+
+| Action | What you do |
+|---|---|
+| `assign` | claim the ticket (In Progress, assigned), run `autopilot fingerprint --before <ticket>`, create or reuse its worktree, spawn its worker |
+| `wait` | nothing; the reason says who is working |
+| `hand-back-to-worker` | give the ticket back to its worker, alive or respawned in the same worktree, with the reason and the pull request; a respawned worker resumes its mission (see Respawning) |
+| `mark-human-wait` | record it in `recent` with its `reason`, which `recent` requires and the recap repeats, put the decision's `humanWaitLabel` on the ticket, comment the reason and detail, free the slot; keep reporting its pull request and footprint, which hold its ground until that pull request merges or closes |
+| `enable-auto-merge` | `void-machine autopilot arm --ticket <id> --pr <n> --head <headSha>`: it records the head, arms on exactly that head and reads GitHub back; never `gh pr merge --auto` by hand, never `--admin` |
+| `disable-auto-merge` | `void-machine autopilot disarm --pr <n>`, before the action that follows it for the same ticket; it turns its auto-merge off, then takes it out of the merge queue, and fails while GitHub still shows either; never `gh pr merge --disable-auto` alone, which leaves a queued pull request in the queue |
+| `rerun-review-check` | `gh run rerun <run> --failed`: the review job failed on this head without posting a verdict, a crash or an output it refused; twice at most per run, then `review-check-reruns-exhausted` |
+| `requeue` | the same command, to put an ejected head back in the queue; the kernel bounds how often |
+| `drain` | take nothing new; keep acting on the tickets in flight |
+| `freeze` | stop acting, once the disarms before it succeeded |
+| `recap` | write the final recap and end the run |
+
+A pull request observed merged has no action: move its ticket to Done, clean its worktree, count it
+in `recent`, and ask the curator to re-rank. `refusals` name judgments the kernel would not admit:
+send each back to the agent that produced it.
+
+**Spawning.** Every worker gets its worktree before it starts, at the durable location the
+doctrine's worktree rule names, reused when its branch already has one. A worker never chooses its
+own checkout and never works in the main one. When the project uses the cockpit presentation
+described in the harness's native supervision guide, each worker and reviewer is launched once in
+its own surface to the right of the orchestrator; without it, workers are native subagents. The
+presentation shows the loop; it never grants a permission, a proof or a merge.
+
+**Respawning.** A respawned worker resumes; it never starts the ticket again. Its code is in its
+worktree and its branch, its progress in its mission journal, `.void/machine/runs/<mission>/events.jsonl`
+under the installation root, which is the main checkout and not the worktree. It finds its mission
+as the open one whose `mission.json` carries the ticket id as its title, runs
+`void-machine mission resume --id <mission> --json` and acts on the recovery decision it prints,
+then goes on with `mission dispatch`. `resume` records itself once per checkpoint; it exits 1 while
+the mission waits and refuses a closed one, and neither is answered by opening a new mission: the
+worker reports it. When the worktree is gone, recreate it from the branch. When the branch the
+tracker names for the ticket is gone too, locally and on the remote, the work is lost: do not
+spawn over it, record `mark-human-wait` yourself with the reason `branch-missing`.
+
+**The fingerprint.** A worktree isolates the working tree, the index and `HEAD`, and nothing else:
+the local config and the files it includes, the stash, tags, notes, remotes, the local base and
+deploy branches, replace refs, `hooks/` and `info/` are one set for every worktree. The upstream
+(`remote`, `merge`) of every branch but the bases and the one that deploys is left out, since units
+in flight set it when they create or push their branch and drop it with a merged one; the bases'
+own settings still count. So start each worktree from
+`origin/<base>` and never move a local base branch while units are in flight. The baseline
+recorded at `assign` is written once: a second `--before` for the same ticket is refused, so a unit
+cannot re-record the state it left as the state it found. It is compared by the worker before it
+pushes, with `autopilot fingerprint --after <ticket>`, and again by the kernel before it arms a
+merge. A changed or missing baseline sends the ticket to a human, unpublished; only that person
+deletes the record.
+
+**Disarming.** Armed means GitHub merges without anyone acting again: an auto-merge request, or,
+once the checks pass on a base with a merge queue, an entry in that queue and no request at all.
+GitHub keeps an auto-merge armed across a push by anyone with write access, shows
+no armed head, and its required check trusts the status alone. So `arm` records the head it armed,
+and `next` returns `disable-auto-merge` when it can no longer vouch for an armed pull request: its
+head moved since `arm` recorded it (then `hand-back-to-worker`, `head-moved-after-arming`: the new
+head is unreviewed), the seal no longer proves a clean verdict on the armed head (then
+`mark-human-wait`, `armed-verdict-unproven`), or nothing recorded the arming (then
+`mark-human-wait`, `ambiguous-state`). An armed merge survives a tick only while the loop vouches
+for its head and hands it to nobody (`wait merging`, `rerun-review-check`): a worker at work, any
+hand-back, a human wait and an immediate stop all come with the disarm. Disarm first, always.
+
+**The review runs in GitHub.** `.github/workflows/independent-review.yml` reviews every ready
+pull request into the base on `pull_request_target`: GitHub runs its workflow, scripts and
+instructions from the default branch, which only a person merges into, so a change to the review
+takes effect once promoted there; the head is read as data and never run, and the verdict becomes the
+`independent-review` check on that head, posted by the review App, a GitHub App holding the Checks
+permission alone. Branch protection requires the check from that App, so the same name from any
+workflow's `GITHUB_TOKEN` does not count. For each merge group, `independent-review-queue.yml`, on
+`workflow_run` of `ci` and also from the default branch, posts the App's check on the group commit
+once every head of the group carries it. No key or secret for it lives on this machine, so neither a
+worker nor a compromised dependency it runs can forge an approval: the App's key and the
+`CLAUDE_CODE_OAUTH_TOKEN` live in the `independent-review` environment, whose deployment branch
+policy admits the default branch alone.
+
+**No state lives in the session.** Who holds which ticket comes from the tracker (status, assignee,
+pull request link, the human-wait label); the rest comes from GitHub. The label is the one every
+decision names in `humanWaitLabel`: `autopilot.humanWaitLabel` when the programme declares it,
+`void:human-wait` otherwise; report `humanWait` as that label's presence, nothing else. After a restart -- an OS
+update, a cut, a saturated context -- the first `next` rebuilds the slots from those two sources,
+and a ticket already held is resumed, never seated twice. Report each ticket's branch and pull
+request whenever they exist, whatever its status: a ticket still ready but with a branch or a pull
+request is a unit in flight, and the kernel resumes it instead of seating a second worker. A
+ticket whose state is ambiguous goes to a human rather than being relaunched.
+
+**Judgments live on the pull request.** The reviewer's verdict and a worker's conflict class are
+comments carrying a machine block: two HTML comment markers around a fenced JSON value. The verdict
+is posted only by the review job, beside its check; `next` believes the job's latest verdict on the
+head only when that check agrees with it, and a block anyone else posts is text. The conflict class is the block `void-machine autopilot judgment conflict-class`
+prints for the JSON on its stdin. `next` reads both from GitHub and admits them again, so the
+tracker you pipe in never carries them and a restart loses nothing.
+
+---
+
+## Workers
+
+Given: one ticket id, its worktree, its branch, the programme's plan and spec. The worker re-fetches
+the complete ticket itself; it never works from a summary.
+
+It runs `void-implement` whole in that worktree, and starts its mission with the ticket id as its
+`--title`, which is how a respawn finds it again. Before any context compaction it writes to the
+mission what it has done: each specialist result through `mission specialist-event`, each proof
+through `mission verify`, a committed candidate through `mission writer-event`. The journal accepts
+only these typed events, no free note; what is not yet one of them does not survive a respawn, and
+uncommitted edits survive only in the worktree. When its proofs are green it runs
+`autopilot fingerprint --after <ticket>`, pushes its own branch, opens one pull request towards the
+base, ready for review rather than as a draft, and moves the ticket to In Review. The review job's
+pass is that cycle's independent review; it reviews ready pull requests only, so a draft waits.
+Blocking findings come back as a hand-back and are corrected as a batch, per `void-implement`.
+
+On a hand-back the worker reads the reason: failing checks, blocking findings, a conflict, or a
+base that moved. It updates its branch by merging the base into it,
+never by rewriting pushed history, re-runs its proofs, and pushes again.
+
+May: run every `void-implement` pass whose predicate fires, run its own gates, apply a migration in
+dev/local only, push its own branch without force, and open or update its own pull request.
+
+May not: enable auto-merge, merge anything, post a verdict or re-run the review job, move a ticket to Done, close or cancel a ticket, touch another ticket's branch or worktree,
+prune the mission journals, or write the git state the repository shares -- `refs/stash`, tags,
+notes, remotes, the repository config.
+
+---
+
+## Reviewer
+
+The `independent-review` job, on every push to a ready pull request and when one is marked ready.
+Its instructions are `.github/review/prompt.md` on the base; it reads the diff and the head with
+read-only tools and returns `blocking` and `advisory` findings under a JSON schema. The job binds
+them to the head and the round, posts the verdict comment and concludes the check: success with no
+blocking finding, failure otherwise, failure too when the output is missing or out of bounds.
+
+**What blocks.** Only what is wrong or dangerous, with a concrete scenario: incorrect behaviour, a
+vulnerability, an unstable or empty proof, a broken consumer. Each blocking finding names its
+location, the scenario and the correction. Everything else is advisory. The number of blocking
+findings measures nothing; a pass that files four advisories and blocks on none is a good pass.
+
+**Advisories** of a merged ticket's verdict go into a single Triage issue per ticket, filed by the
+orchestrator, and never come back into the loop.
+
+**Rounds.** After a correction, round 2 is handed round 1's blocking findings and checks only those
+against the new diff; it opens no new general reading. Still blocking after round 2, the kernel
+hands the ticket to a human with the finding. The kernel counts rounds on GitHub, one per head the
+job blocked, not from the round a verdict announces, and a job that failed without a verdict is a
+crash it re-runs, not a round.
+
+---
+
+## Conflicts and the merge queue
+
+When the base has a merge queue, GitHub rebuilds the combined commit of every pull request ahead
+and reruns the required checks, `independent-review` included, before it merges. Two tickets green
+alone and broken together cannot reach the base.
+
+A pull request ejected from the queue whose head still passes its checks and carries a clean
+verdict has nothing for its worker to fix: the kernel answers `requeue`, at most twice for the same
+head, then sends the ticket to a human. An ejected head whose own checks fail goes back to its
+worker as failing checks. A pull request in conflict with the base goes back to its worker. The
+worker classifies the conflict as the typed `conflict` judgment on the conflicting head, posted
+through `autopilot judgment conflict-class`: `mechanical` it resolves, re-runs
+its proofs and pushes; `semantic` -- two intents that disagree -- it leaves alone, and the kernel
+sends the ticket to a human. A worker never picks a side of a semantic conflict to keep the loop
+moving.
+
+**Serial fallback.** Without a merge queue, merges run one at a time: the oldest ready pull request
+(or the one already merging) holds the turn, is updated on the base when it is behind, re-checked,
+merged, then the next. Same guarantee, lower throughput. The kernel keeps the turn; you do not.
+It holds only if the base refuses a pull request that is not up to date, so `next` checks that the
+base requires it (classic protection or a ruleset) and refuses the tick, naming the fix, when
+nothing readable says so.
+
+---
+
+## Stopping
+
+**Drain.** Requested by a person (`void-machine autopilot stop --drain`, from any pane) or reached
+on its own: nothing ready or preparable, quota low, or three tickets in a row handed to a human
+(a pull request waiting only for a human merge gate is not one).
+The loop takes nothing new, carries the tickets in flight to a merge or a human wait, closes its
+agents, cleans the merged worktrees, and writes the recap.
+
+**Now.** `void-machine autopilot stop --now`. Everything freezes, a merge GitHub would run on its
+own included: `next` returns a `disable-auto-merge` for every armed pull request, then `freeze`.
+Run the disarms, then stop. When `next` cannot read what is armed, or a disarm fails, it does not
+pretend to have frozen: disarm by hand what it names and tell the person. Nothing is lost: the
+state is in the tracker and GitHub, and a later run resumes from there.
+
+The stop file stays until someone deletes it; a new run starts only once it is gone.
+
+**The recap.** What merged, what waits and why, the advisory issues created, and the time each
+ticket took. It is the account a person reads when they come back; write it from observed state,
+never from memory of the session.
+
+---
+
+## Red flags
+
+| Rationalization | Reality |
+|---|---|
+| "The checks are green, enable auto-merge myself" | Only `enable-auto-merge` from the kernel arms a merge, and only on the SHA it names. |
+| "The worker already reviewed its diff" | Self-review is not independent. The reviewer is a separate context on the exact SHA. |
+| "Post the verdict comment by hand, it is quicker" | Only the review job's comment counts, and only its check is required. A hand-written one is text. |
+| "The review job crashed, approve it and move on" | A crash is re-run, twice at most, then a person looks. Nothing approves a head the job did not review. |
+| "That advisory matters, block on it" | Blocking needs a scenario where it is wrong or dangerous. Otherwise it goes to the Triage issue. |
+| "This duplicate ticket can just be closed" | The curator never closes. Comment, and leave it to a person. |
+| "P1 on the label, so it goes first" | The ranking reads the project, not the label. Justify the move on the ticket. |
+| "Both tickets touch different folders, seat them together" | Different folders, same lockfile is still a collision. The kernel decides. |
+| "The conflict is semantic but I see what they meant" | A semantic conflict waits for a human. |
+| "I remember which worker had which ticket" | Rebuild from the tracker and GitHub. The session is not the state. |
+| "The PR is gone from the list, it must have been merged" | Only a merged pull request observed on GitHub is a merge. |
+
+---
+
+## Composition
+
+Upstream: `void-ticket` authors and enriches the tickets and the programme descriptor. Per ticket:
+`void-implement`, entire, once, in the worker's worktree. The merge belongs to GitHub under
+`mergeGate: union-reviewed`, to a person under `mergeGate: human`, and to a person always for the
+branch that deploys.

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

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

@@ -0,0 +1,14 @@
+Sources for `void-brainstorm` skill (see `docs/plans/skill-audits/void-brainstorm.md` for full audit):
+
+- superpowers/brainstorm — primary source. Hard gate, one-question, multi-choice preferred, 2–3 approaches, spec-write, transition to plan.
+- gstack /office-hours — VENDORED (DEV-386): the YC product diagnostic (six forcing questions, anti-sycophancy, 10x ambition move) distilled into the "Pressure-testing a raw idea" upstream mode. Builder-visual/cross-model/gstack-runtime rejected. Was composed upstream; now absorbed as the gstack teardown removes it.
+- gstack /spec — VENDORED (DEV-388, the precision half): read-code-before-asking (cite path:line, "don't ask what you can read"), the five mandatory "why" questions gate, quantify-everything, and failure-mode thinking as a first-class axis. The executability gate + MVP-cut half went to plan; the single-solution persona was NOT allowed to overwrite this skill's 2-3-approaches divergence.
+- compound-engineering (EveryInc) — plan phase referenced; rejected as primary (no clear gate between explore and implement).
+- Boris Cherny "how Boris uses Claude Code" — discipline of writing the design before code.
+
+Strategy: distill. Three deliberate changes from superpowers:
+1. Spec location: docs/specs/YYYY-MM-DD-<topic>.md (consumer convention)
+2. Transition target: plan (vendored equivalent)
+3. No trigger filter on activation (per Section 0bis hedge resolution)
+
+No companion hooks; the gate is a process discipline enforced via void-code-review flags downstream.