Exclude AppleDouble companions from test discovery (#11)

docs/METADATA_DISCOVERY.md

@@ -0,0 +1,53 @@
+# macOS metadata and source discovery
+
+macOS can create AppleDouble companions whose path components start with `._`.
+These files contain filesystem metadata and are not application source. On the
+external-drive review checkout, the former Vitest include pattern selected
+`src/avatar/._*.test.ts` files and attempted to transform their binary contents.
+TypeScript 5.8 already skips the tested dot-prefixed paths with its existing
+`src` include. Its new explicit exclusions document the same metadata policy
+while preserving compiler options and ordinary input discovery.
+
+Shared source issue [#11](https://git.whoagland.com/phenom/healer-man/issues/11)
+owns the default discovery correction:
+
+- `vite.config.ts` retains `configDefaults.exclude` and adds `**/._*` plus
+  `**/._*/**` to the test exclusions.
+- `tsconfig.app.json` retains its compiler options and `include: ["src"]`.
+  Its exclusions retain the package-directory defaults and add the same
+  metadata patterns.
+
+The two patterns cover companion files and files inside a companion directory,
+including nested directories. A component must start with `._`; ordinary
+underscore names and names containing those characters elsewhere remain source.
+Existing metadata files are retained. This changes root input discovery;
+TypeScript's normal handling of explicit imports still applies.
+
+`tools/verify-appledouble-metadata-discovery.mjs` supplies a focused regression
+proof through actual Vitest discovery/execution and TypeScript configuration
+input parsing. It uses fresh task-owned fixtures to verify the rejection path
+and two ordinary test sentinels to verify continued execution. It does not certify
+full application typechecking, a browser production build, gameplay, balance,
+character rendering or dungeon behavior.
+
+Exact commands, input identities and observed results accompany the issue and
+`metadata-discovery-validation.json`. Shared source issue
+[#9](https://git.whoagland.com/phenom/healer-man/issues/9) still owns its separate
+browser build/live visual acceptance gap. Native checkpoint
+[#292](https://git.whoagland.com/Codex/healer-man-godot/issues/292) is already
+installed and merged. This tooling change requires no native runtime rebuild:
+the native writable source mirror is a subset without these browser configs.
+
+Run the focused proof after installing the repository dependencies:
+
+```sh
+node tools/verify-appledouble-metadata-discovery.mjs --evidence-dir /absolute/fresh-path
+```
+
+Use a fresh absolute path outside the checkout. The helper keeps its fixtures
+and reports; it refuses existing destinations, overlap and symlink paths. It
+works from another current directory and uses the Node executable that launched
+it. The final external-drive control records three binary metadata transform
+failures; fixed Vitest defaults run both ordinary tests. TypeScript API and CLI
+resolve the same two ordinary inputs, with and without the explicit metadata
+filters. The Vite/Node configuration typecheck passes.

docs/metadata-discovery-validation.json

@@ -0,0 +1,41 @@
+{
+  "schemaVersion": 1,
+  "date": "2026-10-10",
+  "issue": "https://git.whoagland.com/phenom/healer-man/issues/11",
+  "coordinator": "/root",
+  "session": "01a11cd3-fa7c-7510-ba8f-bc7a3d0310a6",
+  "sourceBase": "812162320d9bf041a1b635b553576962238e5138",
+  "files": {
+    "vite.config.ts": "c394d03344dd8cef5f5488e00e892e3a53b84d2374068688fdb1459114e5627c",
+    "tsconfig.app.json": "5cde2a8b2bd61121fbac7051ce403475ab487314b3970cadde8733ff5013292c",
+    "tools/verify-appledouble-metadata-discovery.mjs": "7ffc8b265d589c65e74122bd90062cc75413b52ffa4bb1daf737a22fcb128674"
+  },
+  "proof": {
+    "path": "diagnostics/metadata-validation/attempt-08/report.json",
+    "sha256": "fa33b3b0bbbd4ce1f6141319ebe2a4f8b465aa408c865a8ea259cc8a2ca6f30e",
+    "portableAlternateCwd": "/Volumes/backup1tb-2",
+    "toolVersions": {
+      "vitest": "3.2.7",
+      "vite": "7.3.6",
+      "typescript": "5.8.3"
+    },
+    "controlBinaryMetadataFailures": 3,
+    "candidateVitestOrdinaryTests": 2,
+    "candidateTypeScriptApiAndCliOrdinaryInputs": 2,
+    "metadataFileAndNestedDirectoryExcluded": true,
+    "ordinaryDotUnderscoreFragmentRetained": true,
+    "vitestDefaultsRetained": true,
+    "typescriptBaselineAlreadySkippedDotPaths": true
+  },
+  "nodeConfigTypecheck": {
+    "passed": true,
+    "receiptSha256": "c2dee7d831ab89628589267892058210f700f96ce69af6fe05f5b7ecaa33f29b"
+  },
+  "limits": [
+    "Root input discovery only; explicit imports use normal compiler rules",
+    "No full application typecheck/build, balance, gameplay or graphics certification",
+    "TypeScript explicit exclusions preserve observed TS5.8 behavior",
+    "Native input mirror lacks browser configs; no native runtime installation",
+    "Existing metadata files and other workers edits retained"
+  ]
+}