fix(mosaic): seed TOOLS.md from defaults on install (#458)

Co-authored-by: Jason Woltje <jason@diversecanvas.com>
Co-committed-by: Jason Woltje <jason@diversecanvas.com>

packages/mosaic/src/config/file-adapter.ts

@@ -1,5 +1,19 @@
-import { readFileSync, existsSync, readdirSync, statSync, copyFileSync } from 'node:fs';
+import { readFileSync, existsSync, statSync, copyFileSync } from 'node:fs';
 import { join } from 'node:path';
+
+/**
+ * Framework-contract files that `syncFramework` seeds from `framework/defaults/`
+ * into the mosaic home root on first install. These are the only files the
+ * wizard is allowed to touch as a one-time seed — SOUL.md and USER.md are
+ * generated from templates by their respective wizard stages with
+ * user-supplied values, and anything else under `defaults/` (README.md,
+ * audit snapshots, etc.) is framework-internal and must not leak into the
+ * user's mosaic home.
+ *
+ * This list must match the explicit seed loop in
+ * packages/mosaic/framework/install.sh.
+ */
+export const DEFAULT_SEED_FILES = ['AGENTS.md', 'STANDARDS.md', 'TOOLS.md'] as const;
 import type { ConfigService, ConfigSection, ResolvedConfig } from './config-service.js';
 import type { SoulConfig, UserConfig, ToolsConfig, InstallAction } from '../types.js';
 import { soulSchema, userSchema, toolsSchema } from './schemas.js';
@@ -131,9 +145,24 @@ export class FileConfigAdapter implements ConfigService {
   }
 
   async syncFramework(action: InstallAction): Promise<void> {
+    // Must match PRESERVE_PATHS in packages/mosaic/framework/install.sh so
+    // the bash and TS install paths have the same upgrade-preservation
+    // semantics. Contract files (AGENTS.md, STANDARDS.md, TOOLS.md) are
+    // seeded from defaults/ on first install and preserved thereafter;
+    // identity files (SOUL.md, USER.md) are generated by wizard stages and
+    // must never be touched by the framework sync.
     const preservePaths =
       action === 'keep' || action === 'reconfigure'
-        ? ['SOUL.md', 'USER.md', 'TOOLS.md', 'memory']
+        ? [
+            'AGENTS.md',
+            'SOUL.md',
+            'USER.md',
+            'TOOLS.md',
+            'STANDARDS.md',
+            'memory',
+            'sources',
+            'credentials',
+          ]
         : [];
 
     syncDirectory(this.sourceDir, this.mosaicHome, {
@@ -141,20 +170,23 @@ export class FileConfigAdapter implements ConfigService {
       excludeGit: true,
     });
 
-    // Copy default root-level .md files (AGENTS.md, STANDARDS.md, etc.)
-    // from framework/defaults/ into mosaicHome root if they don't exist yet.
-    // These are framework contracts — only written on first install, never
-    // overwritten (user may have customized them).
+    // Copy framework-contract files (AGENTS.md, STANDARDS.md, TOOLS.md)
+    // from framework/defaults/ into the mosaic home root if they don't
+    // exist yet. These are written on first install only and are never
+    // overwritten afterwards — the user may have customized them.
+    //
+    // SOUL.md and USER.md are deliberately NOT seeded here. They are
+    // generated from templates by the soul/user wizard stages with
+    // user-supplied values; seeding them from defaults would clobber the
+    // identity flow and leak placeholder content into the mosaic home.
     const defaultsDir = join(this.sourceDir, 'defaults');
     if (existsSync(defaultsDir)) {
-      for (const entry of readdirSync(defaultsDir)) {
+      for (const entry of DEFAULT_SEED_FILES) {
+        const src = join(defaultsDir, entry);
         const dest = join(this.mosaicHome, entry);
-        if (!existsSync(dest)) {
-          const src = join(defaultsDir, entry);
-          if (statSync(src).isFile()) {
-            copyFileSync(src, dest);
-          }
-        }
+        if (existsSync(dest)) continue;
+        if (!existsSync(src) || !statSync(src).isFile()) continue;
+        copyFileSync(src, dest);
       }
     }
   }