voidmachine 0.0.0 → 4.0.0

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

@@ -0,0 +1,271 @@
+---
+name: void-brainstorm
+description: "Engage on a raw idea, or the moment an exchange settles a behaviour, boundary or trade-off: pressure-test, one question at a time, 2-3 approaches, spec written and approved before any code."
+---
+
+# brainstorm — voidcorp craftsman edition
+
+Start by understanding the project context. Then ask questions one at a time to refine the idea. Once you understand what is being built, present the design in sections, get approval, write the spec to `docs/specs/`, and transition to `void-plan`. **No implementation skill, no code, no scaffolding until the spec is written and approved.**
+
+**Attribution**: see `.source`. Primary source: superpowers/brainstorm; the upstream idea-pressure-test mode is the distilled `gstack:/office-hours` diagnostic, vendored for void-machine.
+
+---
+
+## Step 0 — Notice that the exchange has become design
+
+This skill was only ever reached when someone asked for it, which is the half of
+the problem nobody was solving. Design does not usually announce itself: it
+arrives in the middle of a conversation about something else, and by the time
+anyone would think to invoke a skill the decisions have already been made and
+lost. Three of the structural decisions in this repository on 2026-08-17 were
+taken that way, written up afterwards from memory rather than from the exchange.
+
+Engage the moment the conversation starts fixing any of these, without being
+asked:
+
+- **A behaviour is being settled.** What the system does in a case nobody had
+  described yet, and the answer will outlive the conversation.
+- **A boundary is being drawn.** What owns what, what may depend on what, where
+  a responsibility stops.
+- **A trade-off is being taken.** Two credible options are compared and one is
+  chosen, especially when the losing one has real merit.
+- **A name is being fixed** for a concept the codebase will carry, or a
+  convention is being set that future work must follow.
+- **The same design question comes back a third time** in one session. Returning
+  to it means it was never actually settled.
+
+Say what you noticed, in one sentence, and start the process at Step 1. Do not
+ask for permission to think, and do not stop the work in flight: an exchange can
+carry on while its design is being written down.
+
+**Do NOT engage for**: a bug with one correct answer, a mechanical refactor, a
+naming choice local to one function, or a preference with no consequence beyond
+the file being edited. The bar is whether someone six months out would need to
+know *why*. If they would not, this is not design, and invoking here would teach
+everyone to skip Step 0 when it matters.
+
+---
+
+## HARD GATE
+
+Do NOT invoke any implementation skill, write any code, scaffold any project, or take any implementation action until:
+
+1. The spec is written to `docs/specs/YYYY-MM-DD-<topic>.md`
+2. The spec has passed self-review
+3. The user has explicitly approved the written spec
+
+**This applies to EVERY project, regardless of perceived simplicity.**
+
+The anti-pattern is "this is too simple to need a design." Every project goes through this process. Simple projects' specs are short (a few sentences for truly trivial ones), but they MUST be written and approved.
+
+---
+
+## Ingesting a forge spec
+
+If `docs/specs/` holds a spec with `source: forge` in its frontmatter (the forge→harness artifact contract), the up-front thinking is already done. **Verify and fill the gaps — do not re-ask what the spec already answers.** The 18 recon variables cover persona, pain, positioning, competition, pricing, and the visual identity; the winning design and critique verdict are attached. Read them, confirm they still hold, and ask only about what is missing (a partial spec — recon without critique, or a field absent in an older `forge_version` — is ingested for what it has, with the holes listed as the only open questions). Then go straight to writing/approving the spec. Do not restart the interview from scratch.
+
+## Pressure-testing a raw idea (upstream mode)
+
+Runs ONLY when the input is a raw *product idea* ("I want to build X"), not an already-scoped feature or a `source: forge` spec (that thinking is done). Before designing the right solution, make sure it is the right *problem*. This is the distilled `gstack:/office-hours` diagnostic, vendored here. Ambition is pushed for every subject in Step 4b, not here. Once premises hold, resume the normal design process (Step 1 onward) in the collaborative voice; this adversarial posture is scoped to this mode only.
+
+**Posture: diagnose, don't cheerlead.** Take a position on every answer and say what evidence would change your mind. No "interesting approach", no "that could work", no "you might consider" — say why it works or why it doesn't, and challenge the strongest version of the idea, never a strawman. The first answer is the polished one; push once, then again — the real answer comes on the second or third push. **Pre-empt the easy outs before they're used**: a waitlist signup is not "upset", interest is free, "people would love it" costs nothing. End every turn with one concrete assignment — a thing to go do or find out — not a question left dangling; and when the honest answer is "I haven't watched a real person struggle with this", name *that* as the finding, it is the most valuable output of the session.
+
+**The six forcing questions.** Ask one at a time; push until the answer is specific, evidence-based, and a little uncomfortable. Route by stage — you rarely need all six: pre-product → Q1,Q2,Q3 · has users → Q2,Q4,Q5 · paying → Q4,Q5,Q6 · pure infra → Q2,Q4.
+
+1. **Demand reality.** Strongest evidence someone would be genuinely upset if this vanished tomorrow — not "interested", not a waitlist signup. Push for a paying / expanding / workflow-dependent behavior. Red flag: "people say it's interesting", "500 signups".
+2. **Status quo.** What are users doing to solve this today, even badly, and what does that workaround cost them? Red flag: "nothing exists" — usually the pain isn't sharp enough.
+3. **Desperate specificity.** Name the actual human who needs this most — title, what gets them promoted or fired. Red flag: category answers ("healthcare enterprises"); you can't email a category.
+4. **Narrowest wedge.** Smallest version someone would pay for *this week*, before the platform exists. Red flag: "we need the full platform first" — attachment to architecture over value.
+5. **Observation & surprise.** Have you watched someone use it without helping — what did they do that surprised you? Red flag: surveys and demo calls (surveys lie, demos are theater).
+6. **Future-fit.** If the world looks meaningfully different in 3 years, does this become more essential or less? Red flag: "the market grows 20%/yr" — every competitor cites the same tailwind.
+
+**Escape hatch.** If the user says "just do it": ask the 2 most critical remaining questions for their stage, then move on. If they push back a second time, respect it and proceed. Only a fully-formed plan with real evidence (named users, revenue) earns a full skip — and even then, still confirm the premises and generate alternatives.
+
+## Process
+
+### Step 1 — Explore project context
+
+Check the current state: existing files, `docs/`, recent commits, related specs in `docs/specs/`. If a similar spec exists, reference it. A `source: forge` spec is the strongest such reference (see "Ingesting a forge spec" above).
+
+### Step 2 — Scope check (multi-subsystem decomposition)
+
+If the request describes multiple independent subsystems ("build a platform with chat, file storage, billing, analytics"), flag this immediately. Help the user decompose into sub-projects:
+
+- What are the independent pieces?
+- How do they relate?
+- What order should they be built?
+
+Each sub-project gets its own spec → plan → implementation cycle. Brainstorm the first sub-project through the normal flow.
+
+### Step 3 — Visual companion offer (optional, opt-in)
+
+If upcoming questions will involve visual content (mockups, layouts, diagrams), offer the browser-based companion ONCE for consent. The offer is its OWN message — do not combine with clarifying questions.
+
+```
+"Some of what we are working on might be easier to explain if I can show it
+to you in a web browser. I can put together mockups, diagrams, comparisons.
+This feature is new and can be token-intensive. Want to try it? (Requires
+opening a local URL.)"
+```
+
+Wait for the user's response. If they decline, proceed in text-only.
+
+### Step 4 — Ask clarifying questions
+
+- One question at a time. Never batch.
+- Multi-choice preferred when applicable (2–4 distinct mutually-exclusive options with brief descriptions and a recommended option labeled).
+- Open-ended fine when no obvious options exist.
+- Focus on: purpose, constraints, success criteria.
+
+**Precision & grounding** (vendored from gstack `/spec`) — ambiguity is a bug; find it:
+
+- **Read the code before asking.** Do not ask what you can read. Grep/read at least one real piece of evidence and cite `path:line` in the question. "Don't ask what you can read" beats an interview that ignores the repo.
+- **Quantify.** "Several files" is not an answer — find the exact count. "Improves performance" is not a goal — state the metric and target.
+- **Five "why" questions must be answered without hand-waving** before design: **who** is affected, the **verified current** behavior, the **desired** behavior, **why now**, and the **observable/measurable** done-signal.
+- **Think in failure modes** as a first-class axis: empty / null / enormous / duplicated / wrong-role / called-twice.
+
+### Step 4b — Push the ambition (the 10x move)
+
+Runs on **every brainstorm, whatever the subject** — a product idea, a guard, a contract, a migration. Demand pressure-testing above belongs to a raw product idea, because a merge gate has no market to interrogate; ambition is not scoped that way, since timidity is not a property of product ideas. This pass lived inside the product-idea mode and therefore never fired on a technical subject, which is most of what gets designed here.
+
+Before settling, deliberately drop the self-imposed constraints: what does this look like at 10x — no resource limit, no "we can't because"? What is the *coolest* version the user has not considered? Carry that into Step 5: always include one "ideal / most ambitious" path and one "creative-lateral" reframing, not just the safe increment. YAGNI still prunes the *final* scope — but prune down from an ambitious set; do not start timid.
+
+### Step 5 — Propose 2–3 approaches
+
+Present alternatives conversationally with trade-offs. Lead with the recommendation and the reason. Let the user redirect.
+
+### Step 6 — Present the design
+
+Once the intent is clear, present the design in sections:
+
+- Architecture
+- Components
+- Data flow
+- Error handling
+- Testing approach
+- Rollout / phases (if non-trivial)
+- TDD mode per implementation phase (strict / souple / exploratory — composes with `void-tdd` skill)
+
+Get approval AFTER each section before moving on. Scale each section to its complexity: a few sentences for simple projects, 200–300 words for nuanced ones.
+
+### Step 7 — Write the spec
+
+Write to `docs/specs/YYYY-MM-DD-<topic>.md` and commit. Frontmatter:
+
+```yaml
+---
+title: <topic>
+date: YYYY-MM-DD
+status: in-design  # → approved
+author: <user> + Claude/Codex
+ticket: <tracker id, once `void-ticket` has created it; leave empty until then>
+related: [...]
+---
+```
+
+`void-ticket` is half of a link that must exist in both directions. The spec is where
+the reasoning lives and it belongs to the project, so it survives the tracker;
+the ticket is execution state and is mutable by nature. Someone reading the
+ticket has to be able to reach the reasoning, and someone reading the spec has
+to be able to see whether it was ever executed. `void-ticket` fills this
+field when it creates the ticket and puts the reverse link in the ticket body.
+
+### Step 8 — Spec self-review pass
+
+Read the spec with fresh eyes:
+
+1. **Placeholder scan** — any "TBD", "TODO", incomplete sections, vague requirements? Fix.
+2. **Internal consistency** — do sections contradict each other? Does the architecture match the feature descriptions?
+3. **Scope check** — is this focused enough for a single implementation plan, or does it need decomposition?
+4. **Ambiguity check** — could any requirement be interpreted two different ways? If so, pick one and make it explicit.
+
+Fix issues inline. No need to re-review — just fix and move on.
+
+### Step 9 — User reviews the written spec
+
+Ask the user to review the spec file before proceeding:
+
+> "Spec written and committed to `docs/specs/<file>.md`. Please review and let me know if you want changes before we start the implementation plan."
+
+Wait for the user's response. If they request changes, make them and re-run self-review. Only proceed once the user approves.
+
+### Step 10 — Transition to `void-plan`
+
+The ONLY post-brainstorming transition. Invoke plan. Do not invoke any other skill (frontend-design, mcp-builder, etc.).
+
+---
+
+## Design principles
+
+### Design for isolation and clarity
+
+- Break the system into smaller units, each with one clear purpose.
+- Communicate through well-defined interfaces.
+- Each unit can be understood and tested independently.
+- For each unit, answer: what does it do, how do you use it, what does it depend on?
+
+Smaller, well-bounded units are easier to work with — easier for the agent to hold in context, more reliable edits.
+
+### Existing codebases
+
+- Explore current structure before proposing changes.
+- Follow existing patterns.
+- Improve adjacent code only where it serves the current goal (no unrelated refactor).
+
+---
+
+## Red Flags — thoughts that mean STOP
+
+| Thought | Reality |
+|---|---|
+| "This is too simple to need a design" | The gate applies to every project. Write the short version. |
+| "I need more context first" | Skill check comes BEFORE clarifying questions. |
+| "Let me explore the codebase first" | Sure, but the design discipline still applies. |
+| "I can check git/files quickly" | Files lack conversation context. Stay in the process. |
+| "Let me gather information first" | Process telling you HOW to gather information. |
+| "This doesn't need a formal skill" | If a skill exists, use it. |
+| "I'll just do this one thing first" | Check BEFORE doing anything. |
+| "This feels productive" | Undisciplined action wastes time. |
+
+---
+
+## Key principles
+
+- **One question at a time.** Never overwhelm with multiple.
+- **Multi-choice preferred.** Easier to answer than open-ended.
+- **YAGNI ruthlessly.** Remove unnecessary features from all designs.
+- **Explore alternatives.** Always propose 2–3 approaches before settling.
+- **Incremental validation.** Present design, get approval before moving on.
+- **Be flexible.** Go back and clarify when something doesn't make sense.
+
+---
+
+## Composition with other skills
+
+- **Raw product idea** ("I have an idea..."): pressure-test it first via the upstream mode above (the vendored `/office-hours` diagnostic), then design. Broader product *roadmap / strategy* routes to `void-plan-review` (CEO lens — challenges a written plan's premise and ambition).
+- **Downstream — `void-plan`**: the ONLY post-brainstorming transition.
+- **With `void-tdd`**: the spec declares the TDD mode for each major implementation step. Plans then uses this.
+- **With `void-hexagonal-architecture` + `void-domain-driven-design`**: these skills inform the design's structure (bounded contexts, ports, aggregates). Brainstorming consumes their vocabulary; does not duplicate their decisions.
+- **With `void-code-review`**: a PR that introduces features without a linked spec gets flagged.
+
+---
+
+## Anti-rules
+
+- MUST NOT skip the hard gate.
+- MUST NOT batch multiple questions in one message.
+- MUST NOT decide implementation details (those go to plans).
+- MUST NOT decide product roadmap / strategy (routes to `void-plan-review` CEO lens). It DOES pressure-test a raw idea's demand (the upstream mode) and push ambition on any subject (Step 4b) — both in scope, not delegated.
+- MUST NOT skip the spec-write step "because the conversation is clear."
+- MUST NOT transition to any skill other than `void-plan` post-approval.
+
+---
+
+## Final rule
+
+```
+Idea → questions → 2–3 approaches → design in sections → spec written → self-review → user approves → plan.
+Otherwise → it is not voidcorp brainstorm.
+```
+
+The hard gate exists because LLM agents write very fast code for very wrong problems. The discipline pays for itself in the first project that does not have to be rewritten.

package/core-assets/skills/void-brainstorm/harness.yaml

@@ -0,0 +1,14 @@
+# Harness metadata for this skill. Not part of the Agent Skills
+# specification, and never copied into a consumer project: the SKILL.md
+# beside it stays portable and validates against the official six fields.
+# Read by this repository's graph, and by the installer for `runtimes`.
+kind: action
+owner: folpe
+runtimes: [claude, codex]
+enforcement:
+  floor: ci
+  inline:
+    claude: active
+    codex: active
+    hermes: ci-only
+eval_targets: [claude/anthropic/opus]

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

@@ -0,0 +1,39 @@
+Sources for `void-checkpoint` (see `docs/plans/skill-audits/void-checkpoint.md` for the full audit).
+
+Original to void-machine. Written from the failure it is meant to prevent, observed repeatedly
+in this repository: a session ends, the next one re-derives the state from the diff and the
+tracker, and re-attempts something the previous session had already ruled out.
+
+Inspirations, none vendored:
+
+- gstack `/context-save` and `/context-restore` (https://github.com/garrytan/gstack) — the idea
+  that a session boundary deserves a deliberate artefact rather than an ad-hoc note. Rejected
+  from it: the save/restore pair as a symmetric mechanism. Restoring is not a skill's job here;
+  the next session reads the tracker and the memory, which are authoritative and would be
+  duplicated by a restore file. Only the closing half survives.
+
+- The programme contract at `.void/program.md` — "the declared progress provider owns mutable
+  execution state; the programme never stores a hand-maintained next unit". That rule generalises
+  into Step 0's routing table, which is the load-bearing part of the skill.
+
+- `void-learn`'s routing-first structure — the first step is deciding *where a fact
+  belongs*, not writing it. Same shape, different destinations. Also inherits its rejection of a
+  Stop-event hook: a stop payload cannot distinguish an interruption from a closed unit of work,
+  and a handoff written on a false positive is authoritative and wrong.
+
+- The proof-freshness rule is lifted from this repository's own autopilot reconciliation
+  (`proof-invalidation.ts`, DEV-464): a verification is a claim about a specific tree, and
+  reusing it after a rebase asserts something about a tree that no longer exists. The same
+  reasoning applies to a sentence in a handoff.
+
+- PrimeIntellect `prime-agent` compaction format inspired the cumulative read-files and
+  modified-files observations. Only that bounded mechanical structure is adapted; its semantic
+  summary is rejected because it lacks this skill's dead ends and labelled assumptions.
+
+Strategy: original, distilled from observed failures. What it deliberately does NOT do:
+
+- summarise the session — the diff, the commit messages and the tracker already carry what
+  happened; a narrative duplicates them and rots faster;
+- restore context on the next session — that is a read of authoritative sources, not a replay;
+- write semantic residue automatically — closing is a judgement about a unit of work. The
+  `PreCompact` hook owns only a delimited block of observed mechanical facts.

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

@@ -0,0 +1,227 @@
+---
+name: void-checkpoint
+description: Write .void/machine/checkpoint.md before a clear, an interruption, or the end of a day, so the next session resumes without re-deriving anything. Keeps only what no other artefact holds.
+---
+
+# checkpoint
+
+A session ends. The next one starts with an empty context and your name on the branch.
+
+Everything you currently hold — why that approach was abandoned, which result is proven and
+which is assumed, what you would have done next — evaporates in about a second. Reconstructing
+it costs the next session an hour, and it usually reconstructs it wrong, because the cheapest
+thing to recover is what you did and the most expensive is what you ruled out.
+
+This skill spends five minutes to buy that hour back.
+
+**Attribution**: see `.source`.
+
+---
+
+## When it fires
+
+This is a **graceful shutdown**: the moment you deliberately stop, chosen by a human, not
+guessed by a runtime. Three of them, and they are the ones that actually lose work:
+
+- **Before a `clear`.** The context is about to be discarded on purpose. Whatever was only in
+  it dies here unless it is written down first.
+- **Before an interruption.** You are stopping mid-unit, and the reason you stopped is itself
+  part of what the next session needs.
+- **At the end of a day.** The gap is long enough that you will return as a stranger to your
+  own work.
+
+Two more, less common and just as valid: the context window is close to its limit and the work
+continues afterwards, or the work is about to pass to another agent, machine, or person.
+
+Do NOT fire when the work is genuinely finished and nothing is open: there is nothing to
+resume, and a checkpoint written for a closed unit becomes a stale note nobody deletes.
+
+---
+
+## Step 0 — Route, before you write a word
+
+The failure mode of every checkpoint is that it becomes a second copy of state that already lives
+somewhere authoritative. Two copies of a fact means one of them is wrong within a day, and the
+reader cannot tell which.
+
+So the first move is triage. For every fact you are tempted to write down:
+
+| The fact is… | It belongs in | Never in the checkpoint |
+|---|---|---|
+| Execution state — status, assignee, blockers, links | the declared **progress source** | a hand-maintained current or next unit |
+| Global programme context, phase, plan and spec | **`.void/program.md`** | a session observation |
+| What the code now does | the **diff and its commit messages** | a prose summary of the change |
+| A durable rule, preference, or convention | **doctrine** (via `void-learn`) | a paragraph the next session must re-read forever |
+| A design decision with a credible alternative | an **ADR** | a bullet that loses its reasoning |
+
+What survives that filter is the checkpoint's actual subject: **the things no artefact holds** —
+the dead ends, the unproven assumptions, the freshness of your evidence, and the exact next
+move. That list is short. A checkpoint that is long has failed the triage.
+
+If routing sends something to a shared owner, propose that write and get the required human
+approval before applying it. When the owner is available, write it there **first**, then reference
+it. A checkpoint that promises "I'll file this later" is where facts go to die.
+
+---
+
+## Step 1 — Write what nothing else holds
+
+An argument passed with the invocation is what the human specifically wants carried
+over. Cover it, but never let it stand in for the routing above: what they name is one
+item of the residue, not the whole of it.
+
+In this order, because it is the order the next session needs it.
+
+**1. Where you are.** Branch, worktree, and whether anything is uncommitted. One line. If the
+working tree is dirty, say exactly which files and why they were left that way
+— an unexplained dirty tree reads as an interrupted edit and gets discarded.
+
+**2. What is proven, and against what.** Not "tests pass". Which command, on which commit. A
+proof is a claim about a specific tree; after a rebase or a dependency change it is a claim
+about a tree that no longer exists. Say `pnpm verify green on a1b2c3d`, not `everything green`.
+If you did not run it, say you did not run it.
+
+**3. What you tried that did not work.** The most valuable and most often omitted section. For
+each dead end: what you attempted, what actually happened, and why you stopped. Without it the
+next session repeats it — confidently, because it looks like the obvious first idea. This is
+the section to write even when it is unflattering.
+
+**4. What you assumed.** Label every unverified belief as unverified. "The adapter probably
+caches" and "the adapter caches, confirmed in `cache.ts:88`" are different claims, and a
+checkpoint that flattens them costs half a day. If an assumption is load-bearing, say what would
+falsify it.
+
+**5. What is open.** Blockers, decisions waiting on a human, questions with no answer yet. Each
+one with who or what unblocks it.
+
+**6. The next action.** Exactly one, exact enough to execute: a command to run, a file and line
+to open, a specific question to ask. "Continue the ticket" is not a next action. "Run
+`pnpm vitest run x.test.ts`; it fails on the third case because the fixture has no `id`" is.
+This is the first physical move for the next session, never a duplicated current or next unit and
+never a priority decision.
+
+---
+
+## Step 2 — The freshness rule
+
+Anything time-relative rots the moment you write it. Convert as you go:
+
+- "yesterday", "last week", "recently" → the absolute date.
+- "the latest version" → the version.
+- "the new file" → the path.
+- "he said" / "as discussed" → who, and what they said.
+- "it" and "that" with no antecedent in the same sentence → name the thing.
+
+The reader is a stranger with your permissions and none of your context. Write for them.
+
+---
+
+## Step 3 — Test it before you close
+
+Read what you wrote as if you had never seen this work. Then:
+
+1. **Can a stranger take the next action without asking a question?** If not, the next action is
+   not specific enough.
+2. **Does any line duplicate the progress source, program, diff, or doctrine?** Delete it and link instead.
+3. **Is every claim either proven-with-evidence or labelled as an assumption?**
+4. **Would someone reading only this repeat one of your dead ends?** If yes, the dead end is
+   missing or too vague.
+5. **Does it contain a secret, a token, a full prompt, or private source?** Then it does not
+   get written anywhere shared. Redact and reference.
+
+A checkpoint that fails any of these is not shorter than one that passes — it is longer, and wrong.
+
+---
+
+## Where it is written
+
+Write the session residue to **`.void/machine/checkpoint.md`**. This is the canonical local
+checkpoint consumed by `ResumeBundle`; REPLACE it each time rather than appending. It answers one
+question: *what was happening just before the stop*. It lives under `machine/` and is NOT
+committed because it describes one machine at one moment.
+
+The checkpoint has no network dependency. If the declared progress source or provider is
+unavailable, record that unresolved gap when it matters and still write
+`.void/machine/checkpoint.md`. Do not turn an unavailable provider into a reason to lose the
+session residue.
+
+`.void/program.md` remains the versioned global view: programme identity, plan, spec and optional
+progress locator. The program and checkpoint never store a current or next unit. Mutable progress
+stays with the declared provider; the checkpoint's exact next action is only a local physical
+resume move.
+
+One destination per fact. If you cannot decide, the fact probably failed Step 0.
+
+### The checkpoint's shape
+
+`##` sections, any subset, read leniently. Frontmatter carries `date`, `branch` and `head`; branch
+and HEAD bind the evidence to the tree it describes, and `resume` reports when either moved.
+
+```markdown
+---
+date: 2026-08-17
+branch: folpe/dev-621-resume
+head: a1b2c3d
+---
+
+## Objective        What this session was for. One line.
+## Position         Where that sits in the arc - what is done, what remains.
+## State            What is proven, and against which commit.
+## Next action      Exactly one, exact enough to execute.
+## Open loops       - one per line
+## Dead ends        - what was tried, what happened, why you stopped
+## Assumptions      - each labelled unverified
+## Working set      - the paths that were in hand
+```
+
+Position is the section people skip and then miss: returning after days, *how far along is this*
+is a different question from *what was I doing*, and nothing else in the repo answers it.
+
+Write it with `void-machine resume` in mind — that command reads this file, and reading your own
+checkpoint back is the cheapest test of whether it was worth writing.
+
+Before every semantic rewrite, read the current file and preserve the single delimited mechanical
+block from `<!-- void-machine:context-continuity:begin -->` through its matching end marker
+byte-for-byte. A checkpoint written before the product was renamed carries the same block under
+its former name: preserve it just the same, since the hook rewrites it in place on its next write.
+Require exactly one mechanical block; refuse the rewrite when more than one block exists or either
+marker is ambiguous.
+The lifecycle hook owns that block; this skill owns every semantic section around it.
+
+---
+
+## HITL
+
+This skill proposes shared writes; the human decides. The local checkpoint is the requested
+shutdown artefact. Do not move provider state as a side effect of closing a session — a session
+ending is not a unit completing. Never write a checkpoint that claims work is done when it is
+merely stopped.
+
+**The hook boundary.** `UserPromptSubmit` detects explicit close intent and can remind the model to
+invoke this skill before the closing response. `SessionEnd` can only audit checkpoint presence,
+freshness, branch and HEAD after the model is gone. Both stay advisory. `PreCompact` may preserve
+only the delimited mechanical block before known context loss. Hooks never invent or change dead
+ends, assumptions or a next action. A command such as `/clear` can still bypass the prompt hook;
+invoke this skill first.
+
+---
+
+## Red flags
+
+| Rationalization | Reality |
+|---|---|
+| "I'll remember this tomorrow" | You will remember what you did. You will not remember what you ruled out, which is the expensive half. |
+| "The diff explains it" | The diff explains the change. It never explains the three approaches that came first. |
+| "I'll write the checkpoint when I actually need it" | You need it precisely when you can no longer write it. |
+| "Let me summarize the whole session" | A narrative of what happened is not a plan for what is next. Route, then write the residue. |
+| "Everything is green" | Green against which commit, from which command? A stale proof is worse than no proof, because it is trusted. |
+| "The progress source says it all" | Then keep the checkpoint to the local residue, but verify that the provider really carries mutable status and blockers rather than assuming it does. |
+| "I'll note the dead end if it comes up again" | It comes up again in the next session, as a fresh idea, and costs the same hour twice. |
+
+---
+
+## Composition
+
+Upstream: whatever produced the work. Adjacent: `void-learn` takes durable rules out of the
+session; `void-decide` takes structural choices. Downstream: `ResumeBundle` composes the programme,
+this checkpoint and Git into the context read by the CLI and both runtimes.

package/core-assets/skills/void-checkpoint/harness.yaml

@@ -0,0 +1,14 @@
+# Harness metadata for this skill. Not part of the Agent Skills
+# specification, and never copied into a consumer project: the SKILL.md
+# beside it stays portable and validates against the official six fields.
+# Read by this repository's graph, and by the installer for `runtimes`.
+kind: action
+owner: folpe
+runtimes: [claude, codex]
+enforcement:
+  floor: ci
+  inline:
+    claude: active
+    codex: active
+    hermes: ci-only
+eval_targets: [claude/anthropic/opus]

package/core-assets/skills/void-claude-md/.source

@@ -0,0 +1,15 @@
+Sources for `void-claude-md` skill (see `docs/plans/skill-audits/void-claude-md.md` for full audit):
+
+- HumanLayer — "Writing a good CLAUDE.md" — the load-bearing insight: Claude Code wraps CLAUDE.md in a system-reminder framed "may or may not be relevant," the system prompt already carries ~50 instructions, and every added line competes for finite attention. Hence: keep it minimal and universal, never put code-style rules in it (send a linter, not an LLM), reference file:line instead of inlining rotting snippets, defer detail to docs (progressive disclosure), and prune by asking "would removing this cause an error?". https://www.humanlayer.dev/blog/writing-a-good-claude-md
+
+- HumanLayer — "Advanced Context Engineering" — context is the scarce resource; an always-on prompt spends from the same budget as every task. Push certainties to hooks (deterministic, fires 100% of the time) rather than instructions (probabilistic), use narrowly-scoped conditional guidance, and keep the file runnable. https://www.humanlayer.dev/blog/advanced-context-engineering
+
+- Anthropic Claude Code best practices — CLAUDE.md is appended to the system prompt as context the model weighs, not a hard contract; keep it concise, use it for run/build/test commands and repo conventions, and prefer settings.json for deterministic config (permissions, tool attribution). https://www.anthropic.com/engineering/claude-code-best-practices
+
+- Field reports / issues on CLAUDE.md being ignored — observed failure mode where a long CLAUDE.md's rules are dropped silently; the cure is fewer, sharper, runnable lines plus mechanical enforcement (hooks/linters/settings) rather than more prose. (community reports / GitHub issues, no single canonical URL)
+
+Strategy: distill. The HumanLayer articles supply the principles; this skill rewrites them as enforceable harness doctrine for the CLAUDE.md files the harness PRODUCES in consumer projects, adds an "Auditing an existing CLAUDE.md" pruning checklist, and the harness-standard Rationalizations + Verification sections. No verbatim vendoring.
+
+Composition: context (context is the constraint), source-driven-development (deferred docs ground config in version-matched sources), harness-evolution (the harness generates consumer CLAUDE.md files this skill governs), capture-rule (where a stated project rule lands — hook / settings / lean CLAUDE.md line / deferred doc).
+
+Companion hooks: none in v1. A future informational lint (e.g. claude-md-length / snippet-detector) is an open question in the audit note, not a v1 deliverable.