mock-to-internals-migration · v5 · 2026-07-02 · sha256 40a5b13d8dc81c1e
mock-to-internals-migration v5A

Name: mock-to-internals-migration
Author: zaxbyhub
Immutable. This exact content is served forever at /api/v1/blob/40a5b13d8dc81c1e.
---
name: mock-to-internals-migration
description: mock-to-internals-migration
triggers:
  - opt-in tool map
  - feature flag gating
  - tool registration
generated_from_knowledge:
  - 15870ee2-0813-406f-afd6-f34a05343584
  - c3bbb12e-f8de-429d-9d3a-983e7929786c
  - ece661ed-3626-4e1d-b95b-b6ab96a059e9
  - 4d22c8a2-335b-46bd-91da-7968306c6107
  - a152c109-c6f1-4338-8e18-1b98d2d358cf
  - 1baf97e1-b58e-4287-acdd-7b8c150b0e6b
  - 939330c8-be3d-4c11-842f-4a93433b7d1a
  - c66e7212-82ca-4b03-ad06-fece8199e401
  - 2041997b-c527-4cc0-bcf1-08f0cfd6777f
  - d07cf04b-05c2-4e80-b291-e2d0446d9d09
source_knowledge_ids:
  - 15870ee2-0813-406f-afd6-f34a05343584
  - c3bbb12e-f8de-429d-9d3a-983e7929786c
  - ece661ed-3626-4e1d-b95b-b6ab96a059e9
  - 4d22c8a2-335b-46bd-91da-7968306c6107
  - a152c109-c6f1-4338-8e18-1b98d2d358cf
  - 1baf97e1-b58e-4287-acdd-7b8c150b0e6b
  - 939330c8-be3d-4c11-842f-4a93433b7d1a
  - c66e7212-82ca-4b03-ad06-fece8199e401
  - 2041997b-c527-4cc0-bcf1-08f0cfd6777f
  - d07cf04b-05c2-4e80-b291-e2d0446d9d09
generated_at: 2026-07-02T02:35:49.991Z
confidence: 0.60
status: active
version: 5
skill_origin: generated
---

<!-- generated by opencode-swarm skill-generator. Do not edit by hand; edits will be preserved on regeneration only with controlled update mode. -->

# mock-to-internals-migration

## Trigger

- opt-in tool map
- feature flag gating
- tool registration

## Required Procedure

- mirror existing opt-in pattern: separate tool map constant, conditional merge in agents/index.ts, gating tests verifying disabled and enabled states
- run barrel-import-dependent tests after modifying barrel exports
- audit code structure integrity before editing a file that was recently refactored or extracted
- grep for all vi.fn(), vi.spyOn(), vi.mock() in converted files before declaring conversion complete
- spread real module exports as base of every mock.module return object
- Load .opencode/skills/writing-tests/SKILL.md before touching any test file
- run lint check (e.g. bun run lint or equivalent) as part of pre-submit verification, not just build
- check for existing wrapper patterns before applying sandbox wrapping
- design command-transformation pipelines as idempotent passes, not stacking layers
- run tests on the unmodified codebase before starting to establish a failure baseline

## Forbidden Shortcuts

- invent new tool-gating mechanisms for opt-in feature flags
- label post-change test failures as 'pre-existing' without running tests before the change

## Delegation Template

When delegating a task affected by this skill, include:

```
SKILLS: file:.opencode/skills/generated/mock-to-internals-migration/SKILL.md
```

## Reviewer Checks

- grep for import-from-barrel patterns in test files and run affected tests after barrel changes
- grep for mock.module patterns that lack ...realModule spread
- grep for mock.module calls to confirm they spread real exports
- confirm bun:test isolation patterns match skill guidelines
- verify wrapCommand idempotency by calling it twice on the same command and confirming output equals single-call output
- Run `git diff <base>..<head> --name-only` and confirm file presence before marking introduced_by_pr: YES or NO

## Test Engineer Checks

- Add or update tests covering the trigger condition and the forbidden shortcut.

## Source Knowledge IDs

- 15870ee2-0813-406f-afd6-f34a05343584 — Pre-existing opt-in maps (memory, external_skills, skills) follow a consistent pattern — when implementing new gates, mirror the existing structure (separate SKILL_AGENT_TOOL_MAP, conditional merge in agents/index.ts) rather than inventing new mechanisms.</item>
- c3bbb12e-f8de-429d-9d3a-983e7929786c — When adding new exports to barrel files (e.g. src/tools/index.ts), verify all existing test files that import from that barrel still resolve correctly — new exports should not shadow or break existing import paths used by dependent tests.
- ece661ed-3626-4e1d-b95b-b6ab96a059e9 — Verify baseline code structure is sound before making modifications; an incomplete refactor split leaves structure broken and causes edits to fail validation
- 4d22c8a2-335b-46bd-91da-7968306c6107 — Partial Vitest→bun:test mock conversion causes runtime TypeErrors; when converting any test file, audit ALL mock.api usage to ensure complete migration — a single unconverted vi.fn() left next to a bun.mock() causes reset() to fail at runtime
- a152c109-c6f1-4338-8e18-1b98d2d358cf — Always spread real module exports into mock.module returns to prevent undeclared overrides from leaking across tests and causing intermittent failures
- 1baf97e1-b58e-4287-acdd-7b8c150b0e6b — Always load the writing-tests skill before modifying test files — SKILL_COMPLIANCE:none on a test-refactor task means the required skill was bypassed, increasing risk of mock isolation bugs and test pollution.
- 939330c8-be3d-4c11-842f-4a93433b7d1a — Coders must run lint alongside build before submitting — a clean build does not imply a clean lint, and lint failures force revision rounds that are entirely preventable.
- c66e7212-82ca-4b03-ad06-fece8199e401 — wrapCommand and similar command-transformation functions must be idempotent: detect and skip re-wrapping if the target executor has already applied its sandbox envelope (check for existing bwrap/sandbox-exec/Win32 wrapper patterns before wrapping again).
- 2041997b-c527-4cc0-bcf1-08f0cfd6777f — A test failure observed after your changes cannot be classified as 'pre-existing' without a pre-change baseline run — post-hoc attribution to pre-existing failures is unreliable and masks genuine regressions
- d07cf04b-05c2-4e80-b291-e2d0446d9d09 — When confirming a change in review, ensure the change is actually present and causally attributable to the PR; unverifiable attributions break the review gate.