oh-my-opencode/.omo/notepads/package-layering-refactor/learnings.md

## [2026-05-20T15:04:52Z] Task 1 baseline
- Total tests: 7315
- Pass: 7312, Fail: 2, Skip: 1
- Build exit code: 0 (dist/ size: 13M, 1456 files)
- Typecheck exit code: 0
- Packages: 15 package.json files under packages/, 3 private (ast-grep-mcp, rules-core, web)
- Anomalies observed: 2 pre-existing test failures in `src/features/opencode-skill-loader/skill-content.test.ts` — ambiguous short name resolution returns 2 resolved skills instead of 1 when "debugging" + "playwright" are queried together. This is a REAL baseline failure; do not fix as part of this refactor plan unless explicitly directed.

## [2026-05-20T15:12:12Z] Task 2 pre-flight
- `src/shared/deep-merge.ts`: pure, zero imports.
- `src/shared/snake-case.ts`: imports `./deep-merge` only (moved together) — pure after extraction.
- `src/shared/record-type-guard.ts`: pure, zero imports.
- `src/shared/extract-semver.ts`: pure, zero imports.
- `src/shared/frontmatter.ts`: imports `js-yaml` only.
- `src/shared/file-utils.ts`: imports `fs` only.
- `src/shared/contains-path.ts`: imports `fs` and `path` only.
- `src/shared/port-utils.ts`: imports `node:net` only.
- `src/shared/tool-name.ts`: pure, zero imports.
- `src/shared/replace-tool-args.ts`: pure, zero imports.
- `src/features/boulder-state/format-duration.ts`: pure, zero imports.
- `src/shared/jsonc-parser.ts`: coupled to plugin basenames; decoupled via parameterized `detectPluginConfigFile(dir, options)`.
- `src/shared/write-file-atomically.ts`: depends on omo-specific `./tolerant-fsync`; extraction deferred by scope decision (kept in-place).

## [2026-05-21T00:00:00Z] Task 7 (worktree)
- Pre-flight import audit (`packages/ast-grep-mcp/src/*.ts`) shows only `mcp.ts`, `runner.ts`, and `cli-binary-path-resolution.ts` touch adapter/runtime-specific concerns.
- Candidate extracted files are pure from MCP perspective:
  - `types.ts`: type-only, currently coupled only by `CliLanguage` source (`CLI_LANGUAGES`).
  - `language-support.ts`: CLI language enum + numeric defaults; no MCP/Bun coupling.
  - `pattern-hints.ts`: pure heuristics; no runtime coupling (intended identical behavior for pi/codex parity).
  - `result-formatter.ts`: pure string formatter over `SgResult`.
  - `sg-compact-json-output.ts`: pure JSON parsing/truncation logic; depends only on constants/types.
- `runner.ts` split requirement confirmed:
  - Core should own `buildSgArgs()` + `runSg()` orchestration and error mapping.
  - OMO-specific binary resolution stays adapter-side (`getAstGrepPath` in `cli-binary-path-resolution.ts`).
  - OMO-specific process spawn stays adapter-side (`bun-spawn-shim.ts`), injected via core deps (`spawnProcess`).

## [2026-05-21T00:00:00Z] Task 8 (worktree)
- Created `packages/comment-checker-core/` with `package.json`, `tsconfig.json`, `index.d.ts`, and `src/` barrel.
- Moved pure apply-patch parser + metadata parsing into `packages/comment-checker-core/src/apply-patch-edits.ts`.
- Moved shared comment-checker types into `packages/comment-checker-core/src/types.ts`.
- Added injectable pure runner in `packages/comment-checker-core/src/runner.ts`:
  - `resolveCommentCheckerBinary()`
  - `runCommentChecker()` with injected `spawn`, `existsSync`, and timer functions.
- Kept OMO-specific adapter pieces in place (`hook.ts`, `pending-calls.ts`, `initialization-gate.ts`, `downloader.ts`).
- Added per-file shims at original locations:
  - `src/hooks/comment-checker/apply-patch-edits.ts`
  - `src/hooks/comment-checker/types.ts`
- Updated `src/hooks/comment-checker/cli.ts` to keep Bun spawn glue locally while delegating pure runner + resolver to core package.
- Updated `src/hooks/comment-checker/hook.ts` to import `extractApplyPatchEdits` from `@oh-my-opencode/comment-checker-core`.
- Updated root workspace wiring (`package.json` workspaces, devDependency, typecheck:packages) and ran `bun install`.
- Verification:
  - `bun run typecheck` exit 0
  - `bun test` 7312/1/2/7315 (baseline-matching drift)
  - `bun run build` exit 0

## [2026-05-21T00:00:00Z] Task 3 retry (worktree)
- Extracted model resolution pipeline surface into `packages/model-core/` with moved sources/tests and package scaffold (`package.json`, `tsconfig.json`, barrel `src/index.ts`).
- Added ProviderCache DI seam in model-core:
  - `model-resolution-pipeline.ts` accepts `providerCache`.
  - `model-error-classifier.ts` exposes cache-injected provider selector.
- Kept OMO runtime cache implementation in `src/shared/connected-providers-cache.ts` and wired injections through shared shims.
- Recreated per-file `src/shared` shims with explicit symbol re-exports (no `export *` in shims).
- Moved `src/shared/model-capabilities/` subtree into model-core and kept shared adapter entry via `src/shared/model-capabilities/index.ts` wrapper.
- Verification pass: `bun run typecheck`=0, `bun test`=7312/1/2/7315 baseline, `bun run build`=0.

## [2026-05-20T18:37:22Z] W2-QA gate
- Verdict: REJECT. T6 `lsp-core` deferral accepted and not considered.
- Evidence written under `.omo/evidence/w2-qa-*.txt` for all 10 requested checks.
- Blocking failures:
  - Test delta drifted from baseline: `bun test` produced 7311 pass / 1 skip / 3 fail / 1 error / 7315 tests; extra failure is `src/shared/tmux/runner.test.ts:202` after timeout at `src/shared/tmux/runner.test.ts:199`.
  - `/tmp/w2-qa-equiv.ts` could not resolve `@oh-my-opencode/utils` from `/private/tmp/w2-qa-equiv.ts:1`.
  - Dependency DAG violation: `packages/agents-md-core/package.json:19` depends on `@oh-my-opencode/rules-engine`, a cross-Wave-2 internal dependency beyond utils.
  - `packages/rules-core/` still exists, although only `node_modules/` remains inside.
- Passing blocking checks: package symlinks/LSP references, OpenCode coupling sweep, build exit 0, and `dist/` remained 13M.
- Informational coverage concerns: `ast-grep-core`, `comment-checker-core`, `boulder-state`, and `agents-md-core` have zero co-located package tests; `boulder-state` has no critical-path test files.

## [2026-05-21] BOULDER COMPLETE

All 40 plan checkboxes resolved (40 [x], 0 [ ], 1 [~] deferred for T6 lsp-core).

**Final commits on dev (since baseline 6609d90b3):**
- Wave 1: utils package extraction + W1-QA APPROVE
- Wave 2: model-core, rules-engine, agents-md-core, ast-grep-core, comment-checker-core, boulder-state extractions + W2-QA APPROVE (T6 deferred)
- Wave 3: meta-audits + opencode-coupling grep gate + AGENTS.md/ROADMAP docs + W3-QA APPROVE
- Final Wave round 1: F2 + F3 APPROVE; F1 + F4 REJECT
- Round 2 fixes: FIX-1 (model-core DI eliminated 4 back-imports), FIX-2 (14 evidence sentinels), FIX-3 (T4 doc edit split)
- Final Wave round 2: F1 + F4 surface 2 new issues
- Round 3 fixes: FIX-5 (audit allowlist for runtime.Bun.* dual-runtime pattern), FIX-6 (delete 855KB dead generated JSON)
- Final state: all 4 reviewers APPROVE

**Test baseline preserved exactly: 7314 pass / 1 skip / 2 fail / 7317 total**
- 2 fails are pre-existing skill-content ambiguous short-name tests (untouched by refactor)
- 1 documented flake: tmux runner test under heavy parallel I/O (passes 9/9 in isolation)

**Architecture delivered:**
- 7 Core packages in packages/ (utils, model-core, rules-engine, agents-md-core, ast-grep-core, comment-checker-core, boulder-state)
- Per-file re-export shims at original src/ locations (never `export *`)
- opencode-coupling-audit.test.ts enforces zero Bun.* or src/ coupling in package production code (test files exempt)
- ProviderCache, ConnectedProvidersAdapter, SpawnFn DI interfaces for harness independence
- API designed for future pi/codex adoption

**Deferred future tracks:**
- T6 lsp-core extraction (submodule strategy)
- Pi adapter layer (senpi + extensions)
- Codex adapter layer
- rules-engine full Engine DI (originally planned in T4, scoped to rename only)
- 3 orphan re-export shims for cleanup (apply-patch-edits.ts, model-capability-aliases.ts, model-capability-guardrails.ts)
- Tmux runner test flake (documented)

**Key learnings:**
- Subagents running bash inherit the parent's cwd, NOT the worktree path — must use `workdir` parameter explicitly. FIX-6 subagent deleted from main repo by accident before catching this.
- Coupling audit regex `\bBun\.` is too broad; negative lookbehind `(?<!runtime\.)\bBun\.` correctly distinguishes legitimate dual-runtime shim from production violations.
- Test files importing test data from outside the package are acceptable — audit must exclude `*.test.ts` to avoid false positives.
- Git worktrees + cherry-pick is the cleanest parallel-work pattern when subagents work on independent fixes.
- Subagent overconfidence: marks "done" even when typecheck failures persist; orchestrator-side verification is non-negotiable.