voidmachine 5.0.7 → 6.0.0

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

@@ -7,7 +7,14 @@ description: Use when taking a single ticket from ready through shipped at exper
 
 One ticket, taken from ready to shipped, with the coverage a senior expert team would give it: architecture, tests, end-to-end, UX, security, review. This is the single canonical definition of "execute one ticket well." Both interactive work and `void-autopilot` delegate here, so the cycle is defined once and improving it improves both.
 
-**Core principle:** Speed comes from skipping ceremony on trivial work, never from skipping a pass whose trigger fired. The triage is keyed to observable predicates (does it touch a boundary, a UI, a trust edge), not to a feeling that the change "looks simple."
+**Core principle:** keep the senior engineering floor, scale the work to the actual change.
+This skill owns applicability across the cycle: inspect the affected behavior, boundary and risk
+once; load the relevant standards and consult the primary domain specialist before coding.
+An explicit user request with clear scope and acceptance criteria is an executable unit; a
+tracker ticket, separate spec or plan is not required merely to begin authorized work.
+Stop when acceptance criteria, applicable proofs and independent review are satisfied.
+Preferences and optional improvements never start another correction cycle. TDD before new
+behavior, security, KISS and SOLID remain requirements; ceremony is not a substitute for them.
 
 **Attribution**: see `.source`.
 
@@ -22,6 +29,16 @@ capability fallbacks follow that policy without skipping triggered quality gates
 Preserve one `leadWriterId` through corrections; the coordinator retains user intent
 and decisions. Pass any orchestrator-owned panel contract unchanged.
 
+## Optional usage linkage
+
+At work start, when both the existing mission ID and exact native session journal ID are known,
+the coordinator runs `void-machine mission usage-bind --id <mission> --source <session-journal>`.
+This begins prospective counting without changing installed hooks. Never guess a journal from
+recent activity, timestamps or an inherited thread/session variable; a shared session is not
+worker isolation. If identification is unavailable, report unknown and continue the authorized
+work. The coordinator owns this action, not an ID reconstruction task for the user. `void-verify`
+closes the interval and reports once at the end; no per-edit command or extra delivery gate.
+
 ## Canonical team orchestration
 
 When the caller supplies `panel.provider: orchestrator`, the orchestrator owns specialist
@@ -37,8 +54,8 @@ materializes its runtime-neutral specialist envelopes from the current plan.
    the worktree and code; specialists and the independent reviewer never edit.
 2. Start with `mission start --ticket <ticket>` and follow `mission dispatch --id <mission>
    --json`. The frozen task and controller own routing, state and correction budget. Normal
-   dispatch starts the writer without a compulsory preparation panel. Consult a targeted native
-   specialist only when a concrete risk or unresolved question warrants advice (pass 5).
+   dispatch starts the writer without a compulsory preparation panel. The writer still obtains
+   the primary domain specialist advice required by pass 5 before production edits.
    For canonical `invoke-specialists` actions, pass each envelope unchanged through
    `void-orchestrate` and record actual starts/results with `mission specialist-event --id <mission>`.
    Reconcile any existing invocation; a missing response resumes its run, never another cycle.
@@ -98,24 +115,24 @@ Do NOT use this to plan several tickets (that is `void-plan`) or to author the t
 
 Run in order. Each pass names the skill it composes and the predicate that fires it. `ALWAYS` passes never skip; conditional passes skip only when their predicate is false. You ALWAYS evaluate every predicate yourself against the actual change: a ticket declaration may ADD a pass, never cancel one whose predicate fired.
 
-1. **Ingest + completeness gate** (ALWAYS). Fetch the complete ticket, including native relations: scope, AC, DoD, edge cases, declared passes, blockers. If `.void/program.md` scopes the unit, also read its global plan and spec. Confirm the unit is ready and nothing is missing or ambiguous. If a gap or uncovered angle exists, loop back to `void-ticket` to complete it before coding, do not paper over it. For a provider-backed unit, move it to the declared started state and assign it to the current maintainer before the first implementation edit. Load or compile the canonical mission plan and verify its hash before any specialist invocation; missing or conflicting plan data is degraded, not guessed.
-2. **Architecture pass** (IF it touches structure, a module boundary, the data model, or public types). Compose `void-hexagonal-architecture`, `void-domain-driven-design`, agents `type-design-analyzer` + `doctrine-critic`. Confirm the applicable ADR is honored.
+1. **Ingest + completeness gate** (ALWAYS). Read the complete explicit request or ticket, available acceptance criteria, affected contracts and real blockers. Reuse decisions already authorized in the conversation. Resolve only ambiguities that change the result, safety or scope; missing labels or a prose template do not block implementation. Use `void-brainstorm` for an unresolved structural choice and `void-plan` for dependent steps that need durable coordination, not for routine edits. For provider-backed work, read native relations and claim it before edits. A scoped programme still supplies its linked plan/spec; canonical specialist requests still require the authenticated mission plan.
+2. **Architecture pass** (IF structure, a module boundary, data model or public contract changes). Apply `void-hexagonal-architecture` and `void-domain-driven-design` to the affected boundary. Keep KISS and SOLID: a layer or branded type earns its place through an invariant, responsibility or substitution contract, not its name. Consult `type-design-analyzer` or `doctrine-critic` when a concrete design question needs that expertise. Honor applicable ADRs; use `void-decide` only for a lasting structural choice.
 3. **Source grounding** (ALWAYS; the source depends on what the change touches). Read the relevant sources before the first line, per the Anti-rustine section of `PHILOSOPHY.md`. For a third-party configuration, schema or call signature, compose `void-source-driven-development`: official documentation **of the installed version**, never an upgrade by default. For internal code, read the owning contract, types, source and project docs of what you are about to change. Assumed semantics produce bugs that cost hours to find, and the assumption is invisible in the diff — which is why this runs before the writing rather than at review. Cite a source briefly when it helps understand or record a choice; a missing citation never blocks on its own.
 4. **Migration safety** (IF it changes a DB schema or ships a migration). Compose `void-migrations` (and `void-drizzle-migration-safe` on a Drizzle/Postgres stack): zero-downtime, two-phase, batched backfill, locking analysis. **Once the migration is generated and safety-reviewed, apply it to the dev/local database before the TDD and E2E passes run** — otherwise those tests execute against a stale schema and prove nothing about the new shape. **This cycle only ever applies to dev/local; production migrations run through CI / GitHub Actions on merge, never from a worker or this session** (see the `void-migrations` anti-rule). A schema change must never reach the rest of the cycle without this pass.
-5. **Targeted preparation advice** (IF a concrete risk or unresolved question warrants a specialist). Use the existing professional passes and `void-orchestrate` to consult only the relevant native specialist. Bind the question to the actual brief, cited artifacts, boundary or risk being examined; revisit only the affected advice when those materially change. Baseline/profile applicability alone does not require a panel, and advice is not an automatic canonical gate. With `panel.provider: orchestrator`, consume its supplied advice without launching a duplicate. For canonical `invoke-specialists` actions, preserve runtime, agentName, missionId, contextPack, reviewSubject and reviewScope; record actual starts/results, never invented receipts. Reconcile uncertain invocations before launching, keep at most four simultaneous agents, and never fail one on a wait timeout. Preserve real unresolved findings and author-owned evidence obligations. Already-started preparation may finish as advice after writer admission; it cannot satisfy final code review or authorize a new preparation invocation after implementation starts.
+5. **Targeted preparation advice** (IF production behavior, a coding contract or implementation structure changes). Detect the affected domains and invoke the primary domain specialist before implementation through `void-orchestrate`; reuse its advice through corrections unless its actual inputs change. Add an expert only for a distinct risk the primary cannot cover. Give the accepted brief, affected contract and bounded question; collect its actual response before code. Documentation-only, generated-only or mechanical changes with no behavioral/contract effect need no coding specialist. This advice is not an automatic canonical gate or a quorum of every applicable profile. With `panel.provider: orchestrator`, consume its supplied advice without duplication. For canonical `invoke-specialists`, preserve runtime, agentName, missionId, contextPack, reviewSubject and reviewScope; record actual starts/results. Reconcile uncertain invocations, keep at most four simultaneous agents, and never treat a wait timeout as failure. Preserve real unresolved findings and author-owned evidence obligations; advice never substitutes for final independent review.
 6. **TDD implementation** (ALWAYS). During development, the coordinator may create or reuse a draft pull request for the branch. Keep work-in-progress PRs in draft and run focused local checks; do not wait for full remote CI per iteration. `void-verify` owns the transition to complete integration checks and its portable CI template. The single lead writer composes `void-tdd` + `void-testing`. Red, green, refactor. Unit tests for the behavior, green before moving on. Review specialists remain read-only.
 7. **Async + idempotency** (IF it sends email, calls an external side-effecting API, enqueues a job, or mints a single-use token). Compose `void-async-safety`: idempotency keys, replay/dedup window, bounded retries, single-use enforcement.
-8. **End-to-end tests** (IF it touches a user-facing flow). Write/extend the E2E suite (Playwright). The path a user actually walks, not just the unit.
-9. **UX/UI pass** (IF it touches a UI surface). The interface is held to production craft, not just "it renders". Compose `void-frontend-design` (build-time craft) + `void-ui-review` (the audit/critique ceiling: AI-slop test, squint test, interaction-state coverage, technical audit) + `void-accessibility`, across the baseline (BACK+FRONT parity, mobile and desktop, and the states a user actually hits — loading / error / empty). Browser-verified QA (live screenshots) runs via `void-qa` (the claude-in-chrome MCP). A UI ticket is not shippable until this pass is **verified, not assumed**.
-10. **Security pass** (ALWAYS a quick scan; DEEP if it touches a trust boundary: external input, auth, RLS/tenancy, untrusted content, secrets, or a side-effecting action). Compose `void-security-guidance` + `void-security-audit`.
+8. **End-to-end tests** (IF changed user behavior crosses integration boundaries that focused tests cannot prove). Extend the relevant journey in the configured E2E suite. Reuse an existing current proof that already covers the changed contract; do not add a duplicate journey for a local presentation edit.
+9. **UX/UI pass** (IF a UI contract changes). Apply `void-frontend-design` and `void-accessibility` to affected controls, states and viewports. Verify keyboard/touch parity and mobile/desktop behavior for the changed surface through focused tests and `void-qa`. Use `void-ui-review` for a new or materially redesigned journey, or a specific unresolved usability defect; a local edit does not trigger a full application audit. Existing design standards remain binding.
+10. **Security pass** (ALWAYS inspect the change; focused analysis IF a trust boundary changes). Apply `void-security-guidance` to external input, auth, tenancy, untrusted content, secrets and side effects as they are designed and implemented. A final security review does not replace safe boundaries during development. `void-security-audit` is a deliberately requested deep audit, not an automatic second full review of every ticket.
 11. **Review** (ALWAYS). Run the single independent general review in the bounded cycle above. Compose `void-code-review` for that pass. Relevant preparation specialists advise before implementation; they are not a mandatory repeated post-implementation panel. After corrections, inspect only the affected findings and behavior. Findings are judged by demonstrated consequence, not reviewer majority.
    **Judge the change against the economy-of-means section of `PHILOSOPHY.md`**: a judgment, not a score, explained briefly only when that helps record a choice. It blocks only on a demonstrated defect (security, broken behavior, or a boundary or contract violated with a real consequence); anything else is advisory.
    **Review the draft against the anti-patch rule.** The review is real; no verbal ritual is required. The first implementation that comes to mind is often a patch at the wrong level of abstraction: tokenising a string where the API takes a typed schema, mocking a field the real adapter never returns, disabling a flag instead of understanding what it blocks. A V0 mock mirrors the real adapter's signature, never a convenience one. It is judged **here**, on the first draft, because before the writing there is nothing to judge — and it does not belong to the Architecture pass, since a patch slips in precisely through the changes that touch no structure at all.
-12. **Verification before completion** (ALWAYS). Compose `void-verify`: typecheck, tests, hooks, both viewports, all observed not assumed. **A red suite is adjudicated before proceeding** (from gstack `/ship`): each failure is *in-branch* (you touched the test/code, or it traces to the diff → it is yours, fix it) or *pre-existing* (neither touched → offer fix / TODO / skip); ambiguous defaults to in-branch. Test on the **merged base**, not the stale branch. Completion requires the independent review, resolution of blocking defects, and fresh applicable verification proofs; native runtime attestation alone is not a delivery prerequisite.
+12. **Verification before completion** (ALWAYS). Compose `void-verify`, which owns the single informational ticket-end usage recap: applicable typecheck, tests, hooks and affected viewports, all observed not assumed. Reuse proofs whose declared inputs are unchanged; re-run affected proofs, plus required integration checks on the candidate. **A red suite is adjudicated before proceeding** (from gstack `/ship`): each failure is *in-branch* (you touched the test/code, or it traces to the diff → it is yours, fix it) or *pre-existing* (neither touched → offer fix / TODO / skip); ambiguous defaults to in-branch. Test on the **merged base**, not the stale branch. Completion requires the independent review, resolution of blocking defects, and fresh applicable verification proofs; native runtime attestation alone is not a delivery prerequisite.
 13. **Dogfood the shipped surface** (IF the ticket adds or changes a CLI command, a hook, an executable skill, or any output a person will read). Run the thing, on the **real repository**, and quote what came back in the evidence.
     This exists because the passes above have a measured hit rate of zero on a whole class of defect. Six shipped on 2026-08-06 with typecheck, lint, 2,700 tests and five CI checks green: five were caught by using the thing on the real tree, one by the harness itself, none by CI and none by the human merge gate. One of them reported "5 path(s) not extracted" about files it had read, parsed and indexed — the exact lie the feature existed to prevent — and it surfaced by running the command on the repo, after merge. Under autopilot nobody comes back to the previous ticket, so a defect found that way is a defect not found at all.
     **A fixture is not a dogfood.** The fixture is the shortcut that would have missed every one of the six: the two oversized generated artifacts that exposed the false count existed only in the real tree. **And "the command did not crash" is not an observation** — the output has to be read, and quoted rather than summarised as "works". A surface that genuinely cannot run here (a deploy, a remote service) has its limitation named, never worked around in silence. Keep the run read-only or reversible.
-14. **Dispose of what you found** (ALWAYS). A cycle surfaces defects that are not this ticket: an incoherent skill, a stale doc, a contract that lies. Do not file them on their merits. Compare each against the unit you are building, judged against the program objective: it either blocks this unit and is fixed here, or it beats this unit and becomes the next one, or it is **dropped**. Write one recap line per finding naming what it lost to. Record only evidence that cannot be reconstructed — a failure seen once, a measurement — with the command that replays it. The admission rules are `void-ticket`'s; this pass is where they fire.
+14. **Dispose of what you found** (ALWAYS). A cycle surfaces defects that are not this ticket: an incoherent skill, a stale doc, a contract that lies. Do not file them on their merits. Compare each against the unit you are building, judged against the program objective: it either blocks this unit and is fixed here, or it beats this unit and becomes the next one, or it is **dropped**. Report only findings that affect delivery, a human decision or unreconstructable evidence; do not produce a dropped-findings ledger. Record only evidence that cannot be reconstructed — a failure seen once, a measurement — with the command that replays it. The admission rules are `void-ticket`'s; this pass is where they fire.
 15. **Ship** (ALWAYS). Compose `void-commit-discipline`, reuse the existing PR for the branch (create one only if absent), attach verification evidence, and mark the same pull request ready when the candidate meets the review handoff requirements. Then move a tracker-backed ticket to **In Review**. Move it to **Done** only after merge and final verification of the merged state. Commits are **bisectable** — one logical change each, dependency-ordered (infra → domain + tests → edge/UI + tests), each independently valid. Under `void-autopilot` the worker is commit-only: it returns the commit and proof references to the coordinator, who owns pushes, PR creation/readiness and tracker updates. The worker never enables auto-merge, merges, posts the review status or moves the ticket to Done; the loop's reviewer performs the independent review of step 11 on the PR head SHA.
 
 ---
@@ -135,6 +152,28 @@ Never place secrets, full prompts, full model responses, or private source in tr
 
 ---
 
+## Primary domain advice
+
+Select the smallest useful expertise from the actual changed contract, not every touched filename.
+
+| Main change | Primary specialist |
+| --- | --- |
+| UI interaction / rendering | `frontend-engineer`; `experience-designer` for unresolved journey design |
+| Business invariants / domain model | `domain-architect` |
+| Public API / integration contract | `api-integration-engineer` |
+| Persistent schema / backfill | `data-migration-engineer` |
+| Security / auth / tenancy | `security-engineer` |
+| Runtime reliability / async operations | `observability-sre-engineer` |
+| Measured performance bottleneck | `performance-engineer` |
+| CLI / SDK / developer workflow | `devex-docs-engineer` |
+| Cross-module structure | `solution-architect` |
+
+If several domains change, the primary covers the dominant contract and requests only missing
+expertise for a distinct risk. Record the selection and actual result in existing task evidence.
+If the required capability is unavailable, state that limit and its delivery consequence; never
+invent consultation or start another preparation loop. Runtime-native advice is sufficient;
+creating an extra mission ledger solely to count the consultation is not required.
+
 ## Triage: what "fast" means
 
 Evaluate every predicate against the actual change. Never let an upstream declaration suppress a pass whose predicate is true.
@@ -145,11 +184,12 @@ Evaluate every predicate against the actual change. Never let an upstream declar
 | Architecture | structure / boundary / data model / public type | yes |
 | Source grounding | always (official docs if third-party, project contracts if internal) | no (source varies) |
 | Migration safety | DB schema change or migration | yes |
-| TDD implementation | always | no |
+| Domain advice | behavior, coding contract or implementation structure changes | yes |
+| TDD implementation | new or changed behavior; preserve existing proof for mechanical work | no when applicable |
 | Async + idempotency | email / external side effect / job / single-use token | yes |
-| End-to-end tests | user-facing flow touched | yes |
-| UX/UI | UI surface touched | yes |
-| Security | always (deep if trust boundary) | no (depth varies) |
+| End-to-end tests | changed journey needs integration proof | yes |
+| UX/UI | affected UI contract; full audit only for a material journey change | yes |
+| Security | inspect every change; focused analysis of changed trust boundaries | no (scope varies) |
 | Review | always | no |
 | Verification | always | no |
 | Dogfood | CLI command / hook / executable skill / output a person reads | yes |
@@ -166,7 +206,7 @@ Evaluate every predicate against the actual change. Never let an upstream declar
 | "One-line change, skip the review" | Review is ALWAYS. One-liners ship the worst regressions. |
 | "No UI here, skip security" | Security quick-scan is ALWAYS; a backend input is a bigger injection surface than a button. |
 | "Tests after, ship now, it works" | TDD is ALWAYS. Tests written after green prove nothing about intent. |
-| "It hits a trust boundary but it is internal" | Internal still gets the DEEP security pass. Tenancy leaks are internal. |
+| "It hits a trust boundary but it is internal" | Internal trust boundaries still need focused security analysis. Tenancy leaks are internal. |
 | "Going fast means skipping E2E" | Fast skips passes whose PREDICATE is false, not the ones that fired. |
 | "The ticket looked complete, skip the gate" | The gate is one read. A missing edge case found now is hours saved later. |
 | "It works, I'll clean it up after" / "I'll mock that field to unblock the test" | That IS the patch, and it sits at the wrong level. The test going green is not the evidence — refactor the approach, do not paper over it. |
@@ -179,14 +219,11 @@ Violating the letter of the triage is violating its spirit: the predicate decide
 
 ---
 
-## Model tier by pass (frugality, no quality loss)
-
-Tokens follow stakes: mechanical work runs cheap, judgment runs at full strength. This never cheapens a judgment pass — the predicate that fires a pass also sets its tier.
+## Native model choice
 
-- **Mechanical (may run a cheaper model)**: the ingest read, artifact/mirror regeneration, a trivial edit whose predicate fired nothing else.
-- **Judgment (stay top-tier)**: architecture, DEEP security, the review adversarial pass, verification adjudication of a red suite, and any brainstorm/design step.
-- **Subagents carry their own tier**: `doctrine-critic` / `silent-failure-hunter` / `code-explorer` run sonnet; `type-design-analyzer` runs sonnet, `migration-planner` opus (see the agent frontmatter). This skill composes them; it does not override their tier.
-- **Interactive vs worker**: run interactively, the cycle uses the session model (the human's choice); the tiering above is realized when the cycle runs as a `void-autopilot` **worker**, where the worker's model is set from the ticket's stakes (`workerTier`, top-tier by default). A light ticket's whole cycle runs cheaper; a high-stakes one stays full-strength.
+`void-orchestrate` owns model selection from the task's risk, explicit user choice and actual
+native controls. Use that policy for specialists and writers; keep the assigned writer's full
+quality cycle. This workflow adds no model names, worker-tier field or second selection rule.
 
 ## Composition
 

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

@@ -7,6 +7,9 @@ description: Sonnet default (Opus needs comment), prompt caching for >1024-token
 
 LLM costs scale with usage. A 1k-token system prompt re-billed on every call is 90% waste with caching. Opus everywhere is 5× Sonnet for marginal gains. Unbounded retries on a refusal burn tokens. This skill makes cost a first-class design concern at every LLM call site.
 
+This skill governs application LLM API call sites, not coding-agent runtime selection;
+`void-orchestrate` owns native agent model choices.
+
 **Attribution**: see `.source`. Composed with the `claude-api` skill (SDK mechanics). Foundation: Anthropic prompt caching docs + batch API + model card pricing.
 
 ---

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

@@ -40,6 +40,36 @@ or act on an unrelated project. Native work independent of that action may conti
   mandatory independent review or required isolation remains a blocker; do not
   replace it with self-review or silently weaken its requirement.
 
+## Native model choice
+
+Use the current runtime's declared model/effort controls and project-configured identifiers.
+An explicit user choice wins; do not infer availability, price or capability from a product name.
+Without an explicit choice, match the bounded task to an available native configuration:
+
+| Work | Selection |
+| --- | --- |
+| Mechanical lookup, extraction, formatting | An economical model when supported and sufficient |
+| Domain advice or implementation | Enough capability for the actual contract and uncertainty |
+| Sensitive architecture/security, independent review, failed-proof adjudication | Retain judgment capability; never downgrade just for cost |
+
+Keep the assigned writer and reuse valid specialist advice. Do not restart a retained context
+merely to change its model; the writer's whole quality cycle stays intact. A cheaper explicit
+choice never waives acceptance or independent review: report insufficient capability as a
+conflict, rather than silently upgrading or claiming the quality requirement is met.
+
+- Discover supported identifiers and controls before dispatch; pass only supported options.
+  Respect native constraints between model overrides, effort and context/fork modes.
+- An unavailable explicit choice stops the dependent launch with its cause and next action.
+  If no explicit choice exists and selection is unsupported, inherit/default transparently;
+  do not claim that a particular model or lower price was selected.
+- Diagnose an unsupported optional setting instead of passing it anyway. Do not silently
+  change provider, credentials, permissions or the user's choice to make a launch work.
+- Reconcile an uncertain launch before retrying the same work. At most one retry for a
+  confirmed transient failure; otherwise report the limitation. Never cascade across models.
+- Requested and observed models differ: retain the requested option in the ordinary brief,
+  and report the effective model only when the runtime supplies it; otherwise it is unknown.
+  Use existing evidence/reporting, not a new registry. Report cost/time only when observed.
+
 ## First ticket and optional worker tabs
 
 SessionStart discovers Herdr even before central mission files exist. Its advice
@@ -97,6 +127,18 @@ Never invent a durable inbox. Preserve formal receipts separately from working n
 
 ## Short native specialists
 
+`void-implement` owns domain detection and the required primary domain consultation before coding.
+Dispatch that smallest relevant expert set once, collect actual advice and reuse it while its
+inputs hold. This skill owns transport and provenance, not a second applicability policy or
+an all-specialist preparation quorum. Extra experts need a distinct uncovered risk.
+
+For a lightweight consultation outside formal dispatch, after the native call actually succeeds
+and returns a context ID, the coordinator may record `void-machine mission advisory-start --id
+<mission> --specialist core:<role> --runtime claude|codex --context <actual-native-context>`.
+This is a coordinator-observed usage receipt, not `specialist-event`, completion or review proof.
+Never record a planned/failed start, reconstruct past receipts, or block delivery on missing
+telemetry. Repeated submission of the same context is idempotent; a different role conflicts.
+
 Pass the returned specialist envelope unchanged: runtime, agentName, missionId,
 contextPack and, when present, reviewSubject and reviewScope. Invoke the runtime's
 native fresh-context primitive; native Agent calls are not intercepted. Keep the

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

@@ -20,11 +20,11 @@ do not independently approve plans or start implementation.
 
 ## When to invoke
 
-Invoke immediately after `void-brainstorm` approves a spec. The plan is the next deliverable before any code.
+Use when approved work has dependencies, several units or continuity needs worth recording. A bounded request with clear acceptance criteria can go directly to `void-implement`; a plan is not required merely because code will change.
 
 **A `source: forge` spec is a ready spec.** When `docs/specs/YYYY-MM-DD-<slug>.md` carries `source: forge` in its frontmatter (the forge→harness artifact contract), consume it **directly** — it already holds the 18 recon variables, the winning design, and the critique verdict, so `void-brainstorm` need not have run. Plan from it as-is; if it is partial (missing critique, or a field absent in an older `forge_version`), plan around the holes and flag them as the first open decisions rather than re-deriving the whole thing.
 
-Do NOT invoke without an approved spec. If you find yourself wanting to plan without a spec, that means brainstorm was skipped — go back.
+Use the approved spec or explicit user request as the source. If a material design choice is missing, resolve that choice with `void-brainstorm`; do not restart settled discovery.
 
 ---
 
@@ -64,9 +64,7 @@ Each implementation step has this shape:
 - **Depends on**: [step-3, step-5] (or "none")
 - **TDD mode**: strict | souple | exploratory
 - **Verification gate**: <what must pass before moving to step N+1>
-- **Expected commits**:
-  - `test: <reproducing or new behavior>`
-  - `feat: <implementation>` (or `fix:` / `refactor:` per `void-commit-discipline`)
+- **Expected change**: one logical, bisectable commit or dependency-ordered commits; RED/GREEN evidence is retained independently of commit boundaries
 - **Notes**: <constraints, gotchas, hook implications>
 ```
 
@@ -86,7 +84,7 @@ Each step's gate states which checks must pass before moving on. Examples:
 
 - `tsc --noEmit && vitest run --filter checkoutCart`
 - `pre-commit hooks dry-run on staged set` (composes with `tdd-guard`, `tigerstyle-check`, `no-any-grep`, etc.)
-- `mutation testing score ≥ 90%` (strict mode steps with critical surface)
+- the configured mutation threshold, when the project has a mutation runner
 
 The gate is observable. The user sees the output before the next step begins.
 
@@ -165,7 +163,7 @@ After writing the plan, scan for:
 3. **Missing TDD mode** — every implementation step declares one? Fix.
 4. **Unrealistic dependencies** — does step N actually need step N-1, or could they parallelize?
 5. **Missing execution handoff** — a standalone plan has a correct resume point; a tracker-backed program has the complete stable order/dependency table?
-6. **Frontmatter `spec:`** — links back to the approved spec?
+6. **Source of authority** — links to the approved spec when present, otherwise records the explicit request?
 7. **Executability gate** (vendored from gstack `/spec`) — could an *unfamiliar* implementer or agent execute this plan with **zero follow-up questions**? Walk one step as if you'd never seen the codebase: is every file named, every metric quantified, every acceptance criterion observable? Any "figure it out at implementation time" is an ambiguity to resolve now.
 
 Fix inline. Then user-review gate.
@@ -174,12 +172,9 @@ Fix inline. Then user-review gate.
 
 ## User-review gate
 
-Ask the user to review the plan before execution begins:
-
-> "Plan written and committed to `docs/plans/<file>.md`. Please review and let me know if you want changes before we start executing."
-
-Wait for response. If changes requested, make them and re-run self-review.
-
+For already authorized scope, do not request approval again for the plan's formatting or routine
+sequencing. Link the plan and proceed. Ask only for a new consequential choice, expanded scope
+or declared human gate; continue independent authorized work while it is unresolved.
 ---
 
 ## Transition to execution
@@ -213,7 +208,7 @@ Set `high_risk: true` when the plan touches:
 
 ## Composition with other skills
 
-- **Upstream — `void-brainstorm`**: the approved spec is the input.
+- **Upstream**: the approved `void-brainstorm` spec or explicit complete user request supplies scope.
 - **Downstream — `void-ticket`**: converts a multi-ticket plan into native tracker items and installs its active handoff.
 - **Downstream — `void-implement`**: executes one complete ticket and maintains its tracker lifecycle.
 - **With `void-autopilot`**: drains independent ready tickets only through its attended flow.
@@ -227,11 +222,11 @@ Set `high_risk: true` when the plan touches:
 
 ## Anti-rules
 
-- MUST NOT plan without an approved spec.
+- MUST NOT invent scope beyond the approved spec or explicit request.
 - MUST NOT skip TDD mode declaration per implementation step.
 - MUST NOT skip verification gates per step.
 - MUST NOT omit the applicable execution handoff: resume point for standalone work, tracker table for a multi-ticket program.
-- MUST NOT skip the spec link in frontmatter.
+- MUST NOT omit the source of authority: link the spec when present, otherwise record the explicit request.
 - MUST NOT execute the plan (downstream skills do that).
 
 ---
@@ -239,7 +234,7 @@ Set `high_risk: true` when the plan touches:
 ## Final rule
 
 ```
-Approved spec → plan written → self-review → user approves → ticket or implement.
+Approved scope → useful sequence → self-review → resolve only new decisions → ticket or implement.
 Otherwise → it is not voidcorp plan.
 ```
 

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

@@ -5,7 +5,7 @@ description: "Live browser QA of a running web app via the claude-in-chrome MCP:
 
 # 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.
+You are a QA engineer AND a bug-fix engineer. Test a running web app like a real user within the selected scope, exercising its controls, forms and relevant states, 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).
 
@@ -52,10 +52,10 @@ Command mapping from the old gstack browse (`$B`) to the MCP:
 
 ## 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.
+- **Diff-aware** (default for change verification, including when its URL is supplied) — read the diff, map the changed contract to affected pages, controls, states and viewports. Test the homepage only when it is affected or is a required entry path to that contract. Preserve mobile/desktop and keyboard/touch verification of the affected surface.
+- **Full** (explicitly requested audit) — systematic exploration across the requested site scope, evidence-backed issues and health score. A URL alone identifies the target; it does not select a full audit.
 - **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.
+- **Regression** (`--regression <baseline.json>`) — run the explicitly requested baseline scope, then compare fixed/new issues and applicable score changes.
 - **Report-only** (`--report-only`, the old `/qa-only`) — phases through Report, then STOP. No fix loop, no commits.
 
 ## Precondition: clean working tree
@@ -65,18 +65,18 @@ Each fix must be its own atomic commit, so before fixing, `git status --porcelai
 ## 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.
+2. **Explore** — visit only the selected mode's pages and affected states. 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`.
+4. **Health score** (only for an explicitly requested full audit or scored baseline) — 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** (only for an explicitly requested visual audit, a new or materially redesigned journey, or an unresolved in-scope usability defect) — compose `void-ui-review` and hand the relevant current-diff screenshots to `core:visual-craft-director` in fresh context. Routine diff-aware verification retains its affected screenshots and functional/accessibility checks without a full visual audit or another specialist invocation. 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** — Diff-aware verification fixes only demonstrated in-scope blocking defects in the changed contract. Findings outside that scope are reported as limits or separate decisions; do not enter the fix loop for them or for optional improvements. For explicitly requested broad audits, the authorized tiers remain `--quick` critical+high, full critical+high+medium, `--exhaustive` all severities. Severity alone never expands the authorized scope. Mark unfixable-from-source issues as deferred.
+7. **Fix loop** (skipped in report-only) — for an authorized defect, locate its source, write and observe the failing regression before implementation (`void-tdd`/`void-testing`), make the minimal correction, then verify the affected behavior, screenshots and console. Commit the logical fix `fix(qa): <issue>` with its cause and actual proof. Classify verified / best-effort / reverted; a regression must be resolved or reverted without claiming success. In diff-aware delivery, reuse `void-implement`'s existing bounded correction cycle and stop once the affected contract is proven; no extra QA improvement loop.
+8. **Self-regulation** (explicit broad audit) — 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** — state the scope, affected states/viewports verified, real defects, proof, fix status and material limits. Include a health-score delta only when that mode requested a score. A local change needs no whole-site score or unrelated N/A rows. Write 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-ui-review`** — this skill owns driving the browser and the functional/fix loop; `void-ui-review` owns the visual-craft judgment when step 5 applies; local diff-aware verification does not automatically invoke a full audit. 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.
@@ -95,8 +95,9 @@ Each fix must be its own atomic commit, so before fixing, `git status --porcelai
 ## 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.
+Running app → select authorized scope → load browser → verify affected states/viewports →
+record evidence → fix only in-scope defects with RED/GREEN → stop when proven → report.
+Scoring and broad visual exploration apply only to the modes that request them.
 Report-only stops before the fix loop. Otherwise → it is not voidcorp qa.
 ```