@mettlecast/domain-cli 0.2.0

package/src/commands/doctor.ts

@@ -0,0 +1,1362 @@
+import { readdir, readFile, access, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+import { relative } from 'node:path';
+import { readdirSync, existsSync } from 'node:fs';
+
+/**
+ * Options for the doctor command.
+ * Doctor is ALWAYS strict — any FAIL causes exit code 1.
+ */
+export interface DoctorOptions {
+  /** Root directory of the project (defaults to cwd). */
+  projectRoot?: string;
+  /** Flag to run relocation of old-layout scaffold files to new layout. */
+  relocate?: boolean;
+}
+
+/**
+ * A single structural check result.
+ */
+export interface DoctorCheck {
+  /** Short name of the check (e.g. 'Domain configs valid'). */
+  name: string;
+  /** Status: PASS, WARN, or FAIL. */
+  status: 'PASS' | 'WARN' | 'FAIL';
+  /** Human-readable message. */
+  message: string;
+  /** Optional fix suggestion. */
+  fixHint?: string;
+  /** Reference to a W1 K-node ID. */
+  kNodeRef?: string;
+  /** Optional file where violation found. */
+  file?: string;
+  /** Optional line number (if applicable). */
+  line?: number;
+}
+
+/**
+ * Result of the doctor command.
+ */
+export interface DoctorReport {
+  /** Array of all checks performed. */
+  checks: DoctorCheck[];
+  /** Exit code: 0 for all PASS/WARN, 1 for any FAIL. */
+  exitCode: number;
+  /** Convenience boolean: true if exitCode === 0. */
+  pass: boolean;
+}
+
+/**
+ * Recursively find all files matching a pattern.
+ * @param dir - Directory to search
+ * @param pattern - File pattern (e.g., /\.ts$/ for TypeScript files)
+ * @returns Array of absolute file paths
+ */
+function findFiles(dir: string, pattern: RegExp): string[] {
+  const result: string[] = [];
+
+  function walk(currentPath: string): void {
+    try {
+      const entries = readdirSync(currentPath, { withFileTypes: true });
+      for (const entry of entries) {
+        const fullPath = join(currentPath, entry.name);
+        if (entry.isDirectory()) {
+          walk(fullPath);
+        } else if (pattern.test(entry.name)) {
+          result.push(fullPath);
+        }
+      }
+    } catch {
+      // Silently skip inaccessible directories
+    }
+  }
+
+  walk(dir);
+  return result;
+}
+
+/**
+ * Run all structural checks for the current TIB project.
+ * Each check runs independently; failure of one does not abort the rest.
+ *
+ * @param opts - DoctorOptions with optional projectRoot and strict mode.
+ * @returns DoctorReport with array of checks and exit code.
+ */
+export async function runDoctor(opts: DoctorOptions = {}): Promise<DoctorReport> {
+  const projectRoot = opts.projectRoot ?? process.cwd();
+
+  // Handle --relocate flag early
+  if (opts.relocate) {
+    return runRelocate(projectRoot);
+  }
+
+  const checks: DoctorCheck[] = [];
+
+  // Check 1: Domain configs valid
+  checks.push(await checkDomainConfigsValid(projectRoot));
+
+  // Check 2: No raw AWS SDK in domains
+  checks.push(await checkNoRawAwsSdk(projectRoot));
+
+  // Check 3: No cross-domain imports
+  checks.push(await checkNoCrossDomainImports(projectRoot));
+
+  // Check 4: APIs declare versions
+  checks.push(await checkApisHaveVersions(projectRoot));
+
+  // Check 5: APIs declare tenancy
+  checks.push(await checkApisHaveTenancy(projectRoot));
+
+  // Check 6: scaffold-config.json matches on-disk domains
+  checks.push(await checkScaffoldConfigMatchesDisk(projectRoot));
+
+  // Check 7: Husky hooks installed
+  checks.push(await checkHuskyInstalled(projectRoot));
+
+  // Check 8: No root-level flows (deprecated)
+  checks.push(await checkRootLevelFlows(projectRoot));
+
+  // W2 new assertions
+  checks.push(await checkApiFixtures(projectRoot));
+  checks.push(await checkEventConsumers(projectRoot));
+  checks.push(await checkMigrationTenancyTrio(projectRoot));
+  checks.push(await checkDomainRlsTest(projectRoot));
+  checks.push(await checkDomainBrainReachable(projectRoot));
+  checks.push(await checkActionsHaveTypes(projectRoot));
+  checks.push(await checkConventionEvidence(projectRoot));
+
+  // W1 tracked-files boundary checks
+  checks.push(...await checkScaffoldTrackedFilesHaveHeaders(projectRoot));
+  checks.push(...await checkSeedPagesHaveNoHeaders(projectRoot));
+
+  // Layout validation checks (new in Part C)
+  const layoutChecks = await checkLayoutPolicy(projectRoot);
+  checks.push(...layoutChecks);
+
+  // Compute exit code — doctor is always strict: any FAIL → exit 1
+  const hasFail = checks.some(c => c.status === 'FAIL');
+  const exitCode = hasFail ? 1 : 0;
+
+  return { checks, exitCode, pass: exitCode === 0 };
+}
+
+async function checkDomainConfigsValid(projectRoot: string): Promise<DoctorCheck> {
+  try {
+    const domainsDir = join(projectRoot, 'domains');
+    let domainCount = 0;
+    let failedCount = 0;
+
+    // List directories in domains/
+    const entries = await readdir(domainsDir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+      domainCount++;
+      const configPath = join(domainsDir, entry.name, 'domain.config.ts');
+      try {
+        await access(configPath);
+      } catch {
+        failedCount++;
+      }
+    }
+
+    if (failedCount === 0) {
+      return {
+        name: 'Domain configs valid',
+        status: 'PASS',
+        message: `All ${domainCount} domain.config.ts files exist and are readable`,
+        kNodeRef: 'K:runbook:add-domain',
+      };
+    } else {
+      return {
+        name: 'Domain configs valid',
+        status: 'FAIL',
+        message: `${failedCount}/${domainCount} domain.config.ts files are missing or unreadable`,
+        fixHint: `Run 'mc-domain-module add-domain <id>' for missing domains`,
+        kNodeRef: 'K:runbook:add-domain',
+      };
+    }
+  } catch (err) {
+    return {
+      name: 'Domain configs valid',
+      status: 'FAIL',
+      message: `Failed to check domain configs: ${String(err)}`,
+      kNodeRef: 'K:runbook:add-domain',
+    };
+  }
+}
+
+async function checkNoRawAwsSdk(projectRoot: string): Promise<DoctorCheck> {
+  try {
+    const domainsDir = join(projectRoot, 'domains');
+    const results: string[] = [];
+
+    // Find all .ts files in domains/
+    const files = findFiles(domainsDir, /\.ts$/);
+
+    for (const file of files) {
+      const content = await readFile(file, 'utf8');
+      if (content.includes("from '@aws-sdk/") || content.includes('from "@aws-sdk/')) {
+        // Extract the line numbers
+        const lines = content.split('\n');
+        for (let i = 0; i < lines.length; i++) {
+          if (lines[i].includes('@aws-sdk/')) {
+            results.push(`${relative(projectRoot, file)}:${i + 1}`);
+          }
+        }
+      }
+    }
+
+    if (results.length === 0) {
+      return {
+        name: 'No raw AWS SDK in domains',
+        status: 'PASS',
+        message: 'No direct @aws-sdk imports detected in domain code',
+        kNodeRef: 'K:convention:tier-1-foundations',
+      };
+    } else {
+      return {
+        name: 'No raw AWS SDK in domains',
+        status: 'FAIL',
+        message: `Found ${results.length} raw @aws-sdk imports:\n  ${results.join('\n  ')}`,
+        fixHint: 'Use domain-provided integrations or actions instead of raw AWS SDK',
+        kNodeRef: 'K:convention:tier-1-foundations',
+      };
+    }
+  } catch (err) {
+    return {
+      name: 'No raw AWS SDK in domains',
+      status: 'WARN',
+      message: `Could not check for raw AWS SDK: ${String(err)}`,
+      kNodeRef: 'K:convention:tier-1-foundations',
+    };
+  }
+}
+
+async function checkNoCrossDomainImports(projectRoot: string): Promise<DoctorCheck> {
+  try {
+    const domainsDir = join(projectRoot, 'domains');
+    const crossDomainImports: string[] = [];
+
+    const entries = await readdir(domainsDir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+      const domainId = entry.name;
+      const domainPath = join(domainsDir, domainId);
+      const files = findFiles(domainPath, /\.ts$/);
+
+      for (const file of files) {
+        const content = await readFile(file, 'utf8');
+        // Simple regex to find imports from 'domains/'
+        const importRegex = /from\s+['"]([^'"]*domains\/[^'"]*)['"]/g;
+        let match;
+        while ((match = importRegex.exec(content)) !== null) {
+          const importPath = match[1];
+          // Check if it's from a different domain
+          const domainMatch = importPath.match(/domains\/([a-z0-9-]+)/);
+          if (domainMatch && domainMatch[1] !== domainId) {
+            crossDomainImports.push(
+              `${relative(projectRoot, file)} imports from domain '${domainMatch[1]}'`
+            );
+          }
+        }
+      }
+    }
+
+    if (crossDomainImports.length === 0) {
+      return {
+        name: 'No cross-domain imports',
+        status: 'PASS',
+        message: 'No cross-domain imports detected',
+        kNodeRef: 'K:convention:no-cross-domain-import',
+      };
+    } else {
+      return {
+        name: 'No cross-domain imports',
+        status: 'FAIL',
+        message: `Found ${crossDomainImports.length} cross-domain imports:\n  ${crossDomainImports.join('\n  ')}`,
+        fixHint: 'Use domain actions or events to communicate between domains',
+        kNodeRef: 'K:convention:no-cross-domain-import',
+      };
+    }
+  } catch (err) {
+    return {
+      name: 'No cross-domain imports',
+      status: 'WARN',
+      message: `Could not check cross-domain imports: ${String(err)}`,
+      kNodeRef: 'K:convention:no-cross-domain-import',
+    };
+  }
+}
+
+async function checkApisHaveVersions(projectRoot: string): Promise<DoctorCheck> {
+  try {
+    const domainsDir = join(projectRoot, 'domains');
+    const allApiFiles: string[] = [];
+
+    // Find all API files in all domains
+    const entries = await readdir(domainsDir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+      const apiDir = join(domainsDir, entry.name, 'api');
+      const apiFiles = findFiles(apiDir, /\.ts$/);
+      allApiFiles.push(...apiFiles);
+    }
+    const apiFiles = allApiFiles;
+
+    if (apiFiles.length === 0) {
+      return {
+        name: 'APIs declare versions',
+        status: 'PASS',
+        message: 'No APIs found (optional)',
+        kNodeRef: 'K:runbook:add-domain',
+      };
+    }
+
+    // Simple heuristic: grep for 'versions:' in each API file
+    let missingVersions = 0;
+    for (const file of apiFiles) {
+      const content = await readFile(file, 'utf8');
+      if (!content.includes('versions:')) {
+        missingVersions++;
+      }
+    }
+
+    if (missingVersions === 0) {
+      return {
+        name: 'APIs declare versions',
+        status: 'PASS',
+        message: `All ${apiFiles.length} API files declare versions`,
+        kNodeRef: 'K:runbook:add-domain',
+      };
+    } else {
+      return {
+        name: 'APIs declare versions',
+        status: 'FAIL',
+        message: `${missingVersions}/${apiFiles.length} API files missing versions: field`,
+        fixHint: 'Add versions: { v1: { ... } } to defineApi calls',
+        kNodeRef: 'K:runbook:add-domain',
+      };
+    }
+  } catch (err) {
+    return {
+      name: 'APIs declare versions',
+      status: 'WARN',
+      message: `Could not check API versions: ${String(err)}`,
+      kNodeRef: 'K:runbook:add-domain',
+    };
+  }
+}
+
+async function checkApisHaveTenancy(projectRoot: string): Promise<DoctorCheck> {
+  try {
+    const domainsDir = join(projectRoot, 'domains');
+    const allApiFiles: string[] = [];
+
+    // Find all API files in all domains
+    const entries = await readdir(domainsDir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+      const apiDir = join(domainsDir, entry.name, 'api');
+      const apiFiles = findFiles(apiDir, /\.ts$/);
+      allApiFiles.push(...apiFiles);
+    }
+    const apiFiles = allApiFiles;
+
+    if (apiFiles.length === 0) {
+      return {
+        name: 'APIs declare tenancy',
+        status: 'PASS',
+        message: 'No APIs found (optional)',
+        kNodeRef: 'K:convention:tier-1-foundations',
+      };
+    }
+
+    // Simple heuristic: grep for 'tenancy:' in each API file
+    let missingTenancy = 0;
+    for (const file of apiFiles) {
+      const content = await readFile(file, 'utf8');
+      if (!content.includes('tenancy:')) {
+        missingTenancy++;
+      }
+    }
+
+    if (missingTenancy === 0) {
+      return {
+        name: 'APIs declare tenancy',
+        status: 'PASS',
+        message: `All ${apiFiles.length} API files declare tenancy`,
+        kNodeRef: 'K:convention:tier-1-foundations',
+      };
+    } else {
+      return {
+        name: 'APIs declare tenancy',
+        status: 'FAIL',
+        message: `${missingTenancy}/${apiFiles.length} API files missing tenancy: field`,
+        fixHint: "Add tenancy: 'required' | 'none' | 'system' to defineApi calls",
+        kNodeRef: 'K:convention:tier-1-foundations',
+      };
+    }
+  } catch (err) {
+    return {
+      name: 'APIs declare tenancy',
+      status: 'WARN',
+      message: `Could not check API tenancy: ${String(err)}`,
+      kNodeRef: 'K:convention:tier-1-foundations',
+    };
+  }
+}
+
+async function checkScaffoldConfigMatchesDisk(projectRoot: string): Promise<DoctorCheck> {
+  try {
+    const configPath = join(projectRoot, '.tib', 'scaffold-config.json');
+    const domainsDir = join(projectRoot, 'domains');
+
+    let configDomains: string[] = [];
+    try {
+      const configContent = await readFile(configPath, 'utf8');
+      const config = JSON.parse(configContent) as { domainIds?: string[] };
+      configDomains = config.domainIds ?? [];
+    } catch {
+      return {
+        name: 'scaffold-config.json matches on-disk',
+        status: 'FAIL',
+        message: 'Could not read .mc/scaffold-config.json',
+        fixHint: 'Ensure .mc/scaffold-config.json exists and is valid JSON',
+        kNodeRef: 'K:runbook:add-domain',
+      };
+    }
+
+    const diskDomains = new Set<string>();
+    try {
+      const entries = await readdir(domainsDir, { withFileTypes: true });
+      for (const entry of entries) {
+        if (entry.isDirectory()) {
+          diskDomains.add(entry.name);
+        }
+      }
+    } catch {
+      // domains/ might not exist yet
+    }
+
+    const inConfigButNotDisk = configDomains.filter(d => !diskDomains.has(d));
+    const onDiskButNotConfig = Array.from(diskDomains).filter(d => !configDomains.includes(d));
+
+    if (inConfigButNotDisk.length === 0 && onDiskButNotConfig.length === 0) {
+      return {
+        name: 'scaffold-config.json matches on-disk',
+        status: 'PASS',
+        message: `Configuration and disk are in sync (${configDomains.length} domains)`,
+        kNodeRef: 'K:runbook:add-domain',
+      };
+    } else {
+      const issues: string[] = [];
+      if (inConfigButNotDisk.length > 0) {
+        issues.push(`In config but not on disk: ${inConfigButNotDisk.join(', ')}`);
+      }
+      if (onDiskButNotConfig.length > 0) {
+        issues.push(`On disk but not in config: ${onDiskButNotConfig.join(', ')}`);
+      }
+      return {
+        name: 'scaffold-config.json matches on-disk',
+        status: 'FAIL',
+        message: issues.join('; '),
+        fixHint: 'Run mc-domain-module add-domain to sync config',
+        kNodeRef: 'K:runbook:add-domain',
+      };
+    }
+  } catch (err) {
+    return {
+      name: 'scaffold-config.json matches on-disk',
+      status: 'WARN',
+      message: `Could not check scaffold config: ${String(err)}`,
+      kNodeRef: 'K:runbook:add-domain',
+    };
+  }
+}
+
+async function checkHuskyInstalled(projectRoot: string): Promise<DoctorCheck> {
+  try {
+    const huskyPath = join(projectRoot, '.husky', 'pre-commit');
+    await access(huskyPath);
+    const stats = await stat(huskyPath);
+    const isExecutable = (stats.mode & 0o111) !== 0;
+
+    if (isExecutable) {
+      return {
+        name: 'Husky hooks installed',
+        status: 'PASS',
+        message: '.husky/pre-commit exists and is executable',
+      };
+    } else {
+      return {
+        name: 'Husky hooks installed',
+        status: 'WARN',
+        message: '.husky/pre-commit exists but is not executable',
+        fixHint: 'Run chmod +x .husky/pre-commit',
+      };
+    }
+  } catch {
+    return {
+      name: 'Husky hooks installed',
+      status: 'FAIL',
+      message: '.husky/pre-commit not found or not accessible',
+      fixHint: 'Run npx husky install',
+    };
+  }
+}
+
+async function checkRootLevelFlows(projectRoot: string): Promise<DoctorCheck> {
+  try {
+    const flowsDir = join(projectRoot, 'flows');
+    let files: string[] = [];
+    try {
+      files = await readdir(flowsDir);
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code === 'ENOENT') {
+        return {
+          name: 'No root-level flows (deprecated)',
+          status: 'PASS',
+          message: 'No root-level flows/ directory found',
+          kNodeRef: 'K:convention:flow-vs-subscriber-rule',
+        };
+      }
+      throw err;
+    }
+
+    const flowFiles = files.filter(f => f.endsWith('.ts') || f.endsWith('.json'));
+    if (flowFiles.length === 0) {
+      return {
+        name: 'No root-level flows (deprecated)',
+        status: 'PASS',
+        message: 'Root-level flows/ is empty — OK',
+        kNodeRef: 'K:convention:flow-vs-subscriber-rule',
+      };
+    }
+    return {
+      name: 'No root-level flows (deprecated)',
+      status: 'WARN',
+      message: `${flowFiles.length} flow(s) still in root-level flows/: ${flowFiles.join(', ')}`,
+      fixHint: 'Move these flows to domains/{owningDomain}/flows/ and delete the root-level copies.',
+      kNodeRef: 'K:convention:flow-vs-subscriber-rule',
+    };
+  } catch (err) {
+    return {
+      name: 'No root-level flows (deprecated)',
+      status: 'WARN',
+      message: `Could not check root-level flows/: ${String(err)}`,
+      kNodeRef: 'K:convention:flow-vs-subscriber-rule',
+    };
+  }
+}
+
+// ---- W2 new assertions ----
+
+/**
+ * Check 9: Every API has a fixture.
+ */
+async function checkApiFixtures(projectRoot: string): Promise<DoctorCheck> {
+  try {
+    const domainsDir = join(projectRoot, 'domains');
+    const apiWithoutFixture: string[] = [];
+
+    const entries = await readdir(domainsDir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+      const domainId = entry.name;
+      const apiDir = join(domainsDir, domainId, 'api');
+      const testDir = join(domainsDir, domainId, 'api', '__tests__');
+
+      try { await access(apiDir); } catch { continue; }
+
+      const apiFiles = await readdir(apiDir);
+      for (const file of apiFiles) {
+        if (!file.endsWith('.ts')) continue;
+        const baseName = file.replace(/\.ts$/, '');
+
+        if (!existsSync(join(testDir, `${baseName}.fixture.json`)) &&
+            !existsSync(join(testDir, `${baseName}.test.ts`))) {
+          apiWithoutFixture.push(`${domainId}/api/${file}`);
+        }
+      }
+    }
+
+    if (apiWithoutFixture.length === 0) {
+      return { name: 'Every API has a fixture', status: 'PASS',
+        message: 'All API handlers have corresponding fixture or test files',
+        kNodeRef: 'K:exit-gate:domain-complete' };
+    } else {
+      return { name: 'Every API has a fixture', status: 'FAIL',
+        message: `${apiWithoutFixture.length} API(s) missing fixture/test:\n  ${apiWithoutFixture.join('\n  ')}`,
+        fixHint: 'Create __tests__/{id}.fixture.json or __tests__/{id}.test.ts for each API',
+        kNodeRef: 'K:exit-gate:domain-complete' };
+    }
+  } catch (err) {
+    return { name: 'Every API has a fixture', status: 'WARN',
+      message: `Could not check API fixtures: ${String(err)}`,
+      kNodeRef: 'K:exit-gate:domain-complete' };
+  }
+}
+
+/**
+ * Check 10: Every event has consumer or @no-consumers annotation.
+ */
+async function checkEventConsumers(projectRoot: string): Promise<DoctorCheck> {
+  try {
+    const domainsDir = join(projectRoot, 'domains');
+    const entries = await readdir(domainsDir, { withFileTypes: true });
+
+    const eventMap = new Map<string, { domain: string; file: string }>();
+    const subscriberEvents = new Set<string>();
+
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+      const domainId = entry.name;
+      const domainPath = join(domainsDir, domainId);
+
+      const publishesDir = join(domainPath, 'publishes');
+      try {
+        for (const file of await readdir(publishesDir)) {
+          if (!file.endsWith('.ts')) continue;
+          const filePath = join(publishesDir, file);
+          const content = await readFile(filePath, 'utf8');
+          const re = /defineEvent\(\{[^}]*id:\s*['"]([^'"]+)['"]/gs;
+          let m;
+          while ((m = re.exec(content)) !== null) {
+            eventMap.set(m[1], { domain: domainId, file: filePath });
+          }
+        }
+      } catch { /* no publishes */ }
+
+      const subscribersDir = join(domainPath, 'subscribers');
+      try {
+        for (const file of await readdir(subscribersDir)) {
+          if (!file.endsWith('.ts')) continue;
+          const content = await readFile(join(subscribersDir, file), 'utf8');
+          const re = /defineSubscriber\(\{[^}]*event:\s*['"]([^'"]+)['"]/gs;
+          let m;
+          while ((m = re.exec(content)) !== null) {
+            subscriberEvents.add(m[1]);
+          }
+        }
+      } catch { /* no subscribers */ }
+    }
+
+    const orphanedEvents: string[] = [];
+    for (const [eventId, info] of eventMap) {
+      if (subscriberEvents.has(eventId)) continue;
+      try {
+        const fc = await readFile(info.file, 'utf8');
+        if (fc.includes('@no-consumers')) continue;
+      } catch { /* skip */ }
+      orphanedEvents.push(`${info.domain}/publishes → ${eventId}`);
+    }
+
+    if (orphanedEvents.length === 0) {
+      return { name: 'Every event has consumer or annotation', status: 'PASS',
+        message: `All ${eventMap.size} event(s) have consumers or @no-consumers annotations`,
+        kNodeRef: 'K:convention:flow-vs-subscriber-rule' };
+    } else {
+      return { name: 'Every event has consumer or annotation', status: 'FAIL',
+        message: `${orphanedEvents.length} event(s) without consumer or @no-consumers:\n  ${orphanedEvents.join('\n  ')}`,
+        fixHint: 'Add a subscriber or // @no-consumers: <reason> annotation',
+        kNodeRef: 'K:convention:flow-vs-subscriber-rule' };
+    }
+  } catch (err) {
+    return { name: 'Every event has consumer or annotation', status: 'WARN',
+      message: `Could not check event consumers: ${String(err)}`,
+      kNodeRef: 'K:convention:flow-vs-subscriber-rule' };
+  }
+}
+
+/**
+ * Check 11: Migrations declare tenancy trio (tenant_id, workspace_id, org_id).
+ */
+async function checkMigrationTenancyTrio(projectRoot: string): Promise<DoctorCheck> {
+  try {
+    const migrationsDir = join(projectRoot, 'db', 'migrations');
+    const domainsDir = join(projectRoot, 'domains');
+
+    let domainIds: string[] = [];
+    try {
+      domainIds = (await readdir(domainsDir, { withFileTypes: true }))
+        .filter(e => e.isDirectory()).map(e => e.name);
+    } catch { domainIds = []; }
+
+    let migrationFiles: string[] = [];
+    try { migrationFiles = await readdir(migrationsDir); } catch {
+      return { name: 'Migrations declare tenancy trio', status: 'PASS',
+        message: 'No db/migrations/ directory found (optional)',
+        kNodeRef: 'K:convention:tenancy-trio' };
+    }
+
+    const domainMigrations: { file: string; domain: string }[] = [];
+    for (const file of migrationFiles) {
+      for (const domainId of domainIds) {
+        if (file.includes(domainId)) { domainMigrations.push({ file, domain: domainId }); break; }
+      }
+    }
+
+    if (domainMigrations.length === 0) {
+      return { name: 'Migrations declare tenancy trio', status: 'PASS',
+        message: 'No domain-specific migration files found (optional)',
+        kNodeRef: 'K:convention:tenancy-trio' };
+    }
+
+    const missingTrio: string[] = [];
+    for (const { file, domain } of domainMigrations) {
+      const content = (await readFile(join(migrationsDir, file), 'utf8')).toLowerCase();
+      const missing: string[] = [];
+      if (!content.includes('tenant_id')) missing.push('tenant_id');
+      if (!content.includes('workspace_id')) missing.push('workspace_id');
+      if (!content.includes('org_id')) missing.push('org_id');
+      if (missing.length > 0) missingTrio.push(`${file} (domain: ${domain}) missing: ${missing.join(', ')}`);
+    }
+
+    if (missingTrio.length === 0) {
+      return { name: 'Migrations declare tenancy trio', status: 'PASS',
+        message: `All ${domainMigrations.length} domain migration(s) declare tenant_id, workspace_id, and org_id`,
+        kNodeRef: 'K:convention:tenancy-trio' };
+    } else {
+      return { name: 'Migrations declare tenancy trio', status: 'FAIL',
+        message: `${missingTrio.length}/${domainMigrations.length} migration(s) missing tenancy trio:\n  ${missingTrio.join('\n  ')}`,
+        fixHint: 'Add tenant_id, workspace_id, and org_id columns to migration files',
+        kNodeRef: 'K:convention:tenancy-trio' };
+    }
+  } catch (err) {
+    return { name: 'Migrations declare tenancy trio', status: 'WARN',
+      message: `Could not check migration tenancy trio: ${String(err)}`,
+      kNodeRef: 'K:convention:tenancy-trio' };
+  }
+}
+
+/**
+ * Check 12: Domain has RLS test coverage.
+ */
+async function checkDomainRlsTest(projectRoot: string): Promise<DoctorCheck> {
+  try {
+    const domainsDir = join(projectRoot, 'domains');
+    const entries = await readdir(domainsDir, { withFileTypes: true });
+    const domainsMissingRls: string[] = [];
+
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+      const domainId = entry.name;
+      const domainPath = join(domainsDir, domainId);
+      const allFiles = findFiles(domainPath, /\.(ts|json)$/);
+      let hasRlsRef = false;
+
+      for (const file of allFiles) {
+        try {
+          const lc = (await readFile(file, 'utf8')).toLowerCase();
+          if (lc.includes('rls') || lc.includes('row level security') ||
+              lc.includes('row-level-security') || lc.includes('rls-test')) {
+            hasRlsRef = true; break;
+          }
+        } catch { /* skip */ }
+      }
+
+      if (!hasRlsRef) domainsMissingRls.push(domainId);
+    }
+
+    if (domainsMissingRls.length === 0) {
+      return { name: 'Domain has RLS test', status: 'PASS',
+        message: 'All domains have RLS test coverage',
+        kNodeRef: 'K:convention:rls-per-domain-role' };
+    } else {
+      return { name: 'Domain has RLS test', status: 'FAIL',
+        message: `${domainsMissingRls.length} domain(s) missing RLS test: ${domainsMissingRls.join(', ')}`,
+        fixHint: 'Add RLS test assertions or fixtures to each domain',
+        kNodeRef: 'K:convention:rls-per-domain-role' };
+    }
+  } catch (err) {
+    return { name: 'Domain has RLS test', status: 'WARN',
+      message: `Could not check RLS test: ${String(err)}`,
+      kNodeRef: 'K:convention:rls-per-domain-role' };
+  }
+}
+
+/**
+ * Check 13: Domain reachable in brain.
+ */
+async function checkDomainBrainReachable(projectRoot: string): Promise<DoctorCheck> {
+  try {
+    const domainsDir = join(projectRoot, 'domains');
+    let domainIds: string[] = [];
+    try {
+      domainIds = (await readdir(domainsDir, { withFileTypes: true }))
+        .filter(e => e.isDirectory()).map(e => e.name);
+    } catch {
+      return { name: 'Domain reachable in brain', status: 'PASS',
+        message: 'No domains found (optional)', kNodeRef: 'K:runbook:add-domain' };
+    }
+
+    const brainEndpoint = process.env.TIB_BRAIN_ENDPOINT ?? 'http://localhost:3001';
+    let brainReachable = false;
+
+    try {
+      const controller = new AbortController();
+      const timeoutId = setTimeout(() => controller.abort(), 3000);
+      const response = await fetch(`${brainEndpoint}/api/graph/nodes`, {
+        method: 'GET', signal: controller.signal,
+        headers: { 'Content-Type': 'application/json' },
+      });
+      clearTimeout(timeoutId);
+
+      if (response.ok) {
+        brainReachable = true;
+        const data = await response.json() as { nodes?: Array<{ id?: string }> };
+        const nodeIds = new Set((data.nodes ?? []).map(n => n.id).filter(Boolean));
+        const missingNodes = domainIds.filter(d => !nodeIds.has(d));
+        if (missingNodes.length > 0) {
+          return { name: 'Domain reachable in brain', status: 'WARN',
+            message: `Brain reachable but domains not found: ${missingNodes.join(', ')}`,
+            fixHint: 'Ensure domain is registered in the TIB knowledge hub',
+            kNodeRef: 'K:runbook:add-domain' };
+        }
+      }
+    } catch { /* brain unavailable */ }
+
+    if (!brainReachable) {
+      return { name: 'Domain reachable in brain', status: 'WARN',
+        message: `Brain unavailable at ${brainEndpoint} — skipping check`,
+        fixHint: 'Start the TIB brain service or set TIB_BRAIN_ENDPOINT',
+        kNodeRef: 'K:runbook:add-domain' };
+    }
+
+    return { name: 'Domain reachable in brain', status: 'PASS',
+      message: `All ${domainIds.length} domain(s) found in brain graph`,
+      kNodeRef: 'K:runbook:add-domain' };
+  } catch (err) {
+    return { name: 'Domain reachable in brain', status: 'WARN',
+      message: `Could not check brain reachability: ${String(err)}`,
+      kNodeRef: 'K:runbook:add-domain' };
+  }
+}
+
+/**
+ * Check 14: Actions have types in .mc/actions-types.d.ts.
+ */
+async function checkActionsHaveTypes(projectRoot: string): Promise<DoctorCheck> {
+  try {
+    const typesPath = join(projectRoot, '.tib', 'actions-types.d.ts');
+    const domainsDir = join(projectRoot, 'domains');
+    const discoveredActions: string[] = [];
+
+    try {
+      for (const entry of await readdir(domainsDir, { withFileTypes: true })) {
+        if (!entry.isDirectory()) continue;
+        const actionDir = join(domainsDir, entry.name, 'actions');
+        try {
+          for (const file of await readdir(actionDir)) {
+            if (!file.endsWith('.ts')) continue;
+            const content = await readFile(join(actionDir, file), 'utf8');
+            const re = /defineAction\(\{[^}]*id:\s*['"]([^'"]+)['"]/gs;
+            let m;
+            while ((m = re.exec(content)) !== null) discoveredActions.push(m[1]);
+          }
+        } catch { /* no actions */ }
+      }
+    } catch { /* no domains */ }
+
+    if (discoveredActions.length === 0) {
+      return { name: 'Actions have types', status: 'PASS',
+        message: 'No actions found (optional)', kNodeRef: 'K:exit-gate:domain-complete' };
+    }
+
+    let typesContent = '';
+    try { typesContent = await readFile(typesPath, 'utf8'); } catch {
+      return { name: 'Actions have types', status: 'FAIL',
+        message: `.mc/actions-types.d.ts not found — ${discoveredActions.length} action(s) lack type declarations`,
+        fixHint: 'Run mc-domain-module build to generate actions-types.d.ts',
+        kNodeRef: 'K:exit-gate:domain-complete' };
+    }
+
+    const missingTypes = discoveredActions.filter(a => !typesContent.includes(a));
+    if (missingTypes.length === 0) {
+      return { name: 'Actions have types', status: 'PASS',
+        message: `All ${discoveredActions.length} action(s) have type declarations`,
+        kNodeRef: 'K:exit-gate:domain-complete' };
+    } else {
+      return { name: 'Actions have types', status: 'FAIL',
+        message: `${missingTypes.length}/${discoveredActions.length} action(s) missing from .mc/actions-types.d.ts:\n  ${missingTypes.join('\n  ')}`,
+        fixHint: 'Run mc-domain-module build to regenerate actions-types.d.ts',
+        kNodeRef: 'K:exit-gate:domain-complete' };
+    }
+  } catch (err) {
+    return { name: 'Actions have types', status: 'WARN',
+      message: `Could not check action types: ${String(err)}`,
+      kNodeRef: 'K:exit-gate:domain-complete' };
+  }
+}
+
+/**
+ * Check 15: W1 conventions have evidence in codebase.
+ */
+async function checkConventionEvidence(projectRoot: string): Promise<DoctorCheck> {
+  try {
+    const w1KNodeIds = [
+      'K:exit-gate:domain-complete', 'K:convention:tenancy-trio',
+      'K:convention:no-cross-domain-import', 'K:convention:rls-per-domain-role',
+      'K:convention:tier-1-foundations', 'K:convention:flow-vs-subscriber-rule',
+    ];
+
+    const domainsDir = join(projectRoot, 'domains');
+    let entries: { name: string; isDirectory: () => boolean }[] = [];
+    try { entries = await readdir(domainsDir, { withFileTypes: true }); } catch {
+      return { name: 'Conventions have evidence', status: 'PASS',
+        message: 'No domains found (optional)', kNodeRef: 'K:exit-gate:domain-complete' };
+    }
+
+    const missingEvidence: string[] = [];
+    for (const kNodeId of w1KNodeIds) {
+      let found = false;
+      for (const entry of entries) {
+        if (!entry.isDirectory()) continue;
+        const files = findFiles(join(domainsDir, entry.name), /\.(ts|json|md)$/);
+        for (const file of files) {
+          try {
+            const c = await readFile(file, 'utf8');
+            if (c.includes(kNodeId) || c.includes(kNodeId.split(':').pop() ?? '')) {
+              found = true; break;
+            }
+          } catch { /* skip */ }
+        }
+        if (found) break;
+      }
+      if (!found) {
+        for (const rf of [join(projectRoot, 'CLAUDE.md'), join(projectRoot, 'README.md')]) {
+          try { if ((await readFile(rf, 'utf8')).includes(kNodeId)) { found = true; break; } } catch { /* skip */ }
+        }
+      }
+      if (!found) missingEvidence.push(kNodeId);
+    }
+
+    if (missingEvidence.length === 0) {
+      return { name: 'Conventions have evidence', status: 'PASS',
+        message: `All ${w1KNodeIds.length} W1 conventions have evidence in the codebase`,
+        kNodeRef: 'K:exit-gate:domain-complete' };
+    } else if (missingEvidence.length <= 2) {
+      return { name: 'Conventions have evidence', status: 'WARN',
+        message: `${missingEvidence.length}/${w1KNodeIds.length} convention(s) lack references: ${missingEvidence.join(', ')}`,
+        fixHint: 'Add K-node references in domain files or root CLAUDE.md',
+        kNodeRef: 'K:exit-gate:domain-complete' };
+    } else {
+      return { name: 'Conventions have evidence', status: 'FAIL',
+        message: `${missingEvidence.length}/${w1KNodeIds.length} convention(s) lack references: ${missingEvidence.join(', ')}`,
+        fixHint: 'Add K-node references in domain files or root CLAUDE.md',
+        kNodeRef: 'K:exit-gate:domain-complete' };
+    }
+  } catch (err) {
+    return { name: 'Conventions have evidence', status: 'WARN',
+      message: `Could not check convention evidence: ${String(err)}`,
+      kNodeRef: 'K:exit-gate:domain-complete' };
+  }
+}
+
+/**
+ * Check W1-A: Scaffold-tracked files in scaffold-src/modules/frontend/ have @mc-scaffold: headers.
+ * Scans components/ui/, components/shell/ (non-page), lib/ for files missing the header.
+ * Status: WARN per missing file.
+ */
+async function checkScaffoldTrackedFilesHaveHeaders(projectRoot: string): Promise<DoctorCheck[]> {
+  const scaffoldFrontendSrc = join(
+    projectRoot,
+    'scaffold-src', 'modules', 'frontend', 'frontend', 'src'
+  );
+
+  const SCAFFOLD_TRACKED_DIRS = [
+    join(scaffoldFrontendSrc, 'components', 'ui'),
+    join(scaffoldFrontendSrc, 'components', 'shell'),
+    join(scaffoldFrontendSrc, 'lib'),
+  ];
+
+  // Seed page paths that live under components/shell but are NOT scaffold-tracked
+  const SEED_PAGE_PATTERN = /\/pages\//;
+
+  const missing: string[] = [];
+
+  for (const dir of SCAFFOLD_TRACKED_DIRS) {
+    const tsFiles = findFiles(dir, /\.(tsx?|css)$/);
+    for (const file of tsFiles) {
+      // Skip seed pages if somehow nested here
+      if (SEED_PAGE_PATTERN.test(file)) continue;
+      try {
+        const content = await readFile(file, 'utf8');
+        if (!content.includes('@mc-scaffold:')) {
+          missing.push(relative(projectRoot, file));
+        }
+      } catch { /* skip unreadable */ }
+    }
+  }
+
+  if (missing.length === 0) {
+    return [{
+      name: 'Scaffold-tracked files have @mc-scaffold: headers',
+      status: 'PASS',
+      message: 'All scaffold-tracked frontend files have @mc-scaffold: headers',
+      kNodeRef: 'K:convention:scaffold-tracked-files-boundary',
+    }];
+  }
+
+  return missing.map(f => ({
+    name: 'Scaffold-tracked files have @mc-scaffold: headers',
+    status: 'WARN' as const,
+    message: `scaffold-tracked file missing @mc-scaffold: header: ${f}`,
+    fixHint: 'Add `@mc-scaffold: frontend@1.0.0` header to this file.',
+    kNodeRef: 'K:convention:scaffold-tracked-files-boundary',
+    file: f,
+  }));
+}
+
+/**
+ * Check W1-B: Seed pages in scaffold-src/modules/frontend/frontend/src/pages/ must NOT have @mc-scaffold: headers.
+ * Status: FAIL per offending file.
+ */
+async function checkSeedPagesHaveNoHeaders(projectRoot: string): Promise<DoctorCheck[]> {
+  const pagesDir = join(
+    projectRoot,
+    'scaffold-src', 'modules', 'frontend', 'frontend', 'src', 'pages'
+  );
+
+  // These barrel index files ARE scaffold-managed (not seed pages)
+  const SCAFFOLD_BARREL_PATTERN = /\/index\.(ts|tsx)$/;
+
+  const violations: string[] = [];
+
+  let allPageFiles: string[] = [];
+  try {
+    allPageFiles = findFiles(pagesDir, /\.(tsx?|css)$/);
+  } catch {
+    // pages dir may not exist in this project root
+    return [{
+      name: 'Seed pages have no @mc-scaffold: headers',
+      status: 'PASS',
+      message: 'No scaffold-src/modules/frontend pages directory found — skipping',
+      kNodeRef: 'K:convention:scaffold-tracked-files-boundary',
+    }];
+  }
+
+  for (const file of allPageFiles) {
+    // Skip barrel index files (they are scaffold-tracked)
+    if (SCAFFOLD_BARREL_PATTERN.test(file)) continue;
+    try {
+      const content = await readFile(file, 'utf8');
+      if (content.includes('@mc-scaffold:')) {
+        violations.push(relative(projectRoot, file));
+      }
+    } catch { /* skip unreadable */ }
+  }
+
+  if (violations.length === 0) {
+    return [{
+      name: 'Seed pages have no @mc-scaffold: headers',
+      status: 'PASS',
+      message: 'No seed page files have @mc-scaffold: headers',
+      kNodeRef: 'K:convention:scaffold-tracked-files-boundary',
+    }];
+  }
+
+  return violations.map(f => ({
+    name: 'Seed pages have no @mc-scaffold: headers',
+    status: 'FAIL' as const,
+    message: `Seed page has @mc-scaffold: header (user-owned file): ${f}`,
+    fixHint: 'Remove the @mc-scaffold: header from this seed page — it is user-owned.',
+    kNodeRef: 'K:convention:scaffold-tracked-files-boundary',
+    file: f,
+  }));
+}
+
+/**
+ * Check Part C: Layout validation checks
+ * 1. owned files in unexpected locations
+ * 2. tracked/seed files inside .mc/
+ * 3. manifest entries pointing at missing files
+ * 4. scaffold-tracked files (with @mc-scaffold: header) that lack manifest entries
+ */
+async function checkLayoutPolicy(projectRoot: string): Promise<DoctorCheck[]> {
+  const results: DoctorCheck[] = [];
+
+  // Read manifest
+  const { readManifest } = await import('../utils/manifest.js');
+  const manifest = await readManifest(projectRoot);
+
+  if (!manifest) {
+    // No manifest — skip layout checks
+    return [];
+  }
+
+  // Check 1: owned files in unexpected locations
+  // Policy: owned files should be in .mc/ OR .github/workflows/tib-*
+  const ownedOutsideTib = manifest.files.filter(f =>
+    f.policy === 'owned' &&
+    !f.path.startsWith('.mc/') &&
+    !/^\.github\/workflows\/tib-/.test(f.path)
+  );
+  if (ownedOutsideTib.length === 0) {
+    results.push({
+      name: 'Layout: owned files in .mc/',
+      status: 'PASS',
+      message: 'All owned scaffold files are under .mc/ or .github/workflows/tib-*',
+    });
+  } else {
+    for (const f of ownedOutsideTib) {
+      results.push({
+        name: 'Layout: owned files in .mc/',
+        status: 'FAIL',
+        message: `Owned scaffold file outside .mc/: ${f.path}`,
+        fixHint: `Run 'tib doctor --relocate' to migrate ${f.path} to .mc/`,
+        file: f.path,
+      });
+    }
+  }
+
+  // Check 2: tracked/seed files inside .mc/
+  const nonOwnedInsideTib = manifest.files.filter(f =>
+    (f.policy === 'tracked' || f.policy === 'seed') &&
+    f.path.startsWith('.mc/')
+  );
+  if (nonOwnedInsideTib.length === 0) {
+    results.push({
+      name: 'Layout: no user files inside .mc/',
+      status: 'PASS',
+      message: 'No tracked/seed files incorrectly placed inside .mc/',
+    });
+  } else {
+    for (const f of nonOwnedInsideTib) {
+      results.push({
+        name: 'Layout: no user files inside .mc/',
+        status: 'FAIL',
+        message: `${f.policy} file inside .mc/ (should be user-owned, outside .mc/): ${f.path}`,
+        file: f.path,
+      });
+    }
+  }
+
+  // Check 3: manifest entries pointing at missing files
+  const { access: fsAccess } = await import('node:fs/promises');
+  const { join: pathJoin } = await import('node:path');
+  const missingFiles: string[] = [];
+  for (const f of manifest.files) {
+    try {
+      await fsAccess(pathJoin(projectRoot, f.path));
+    } catch {
+      missingFiles.push(f.path);
+    }
+  }
+  if (missingFiles.length === 0) {
+    results.push({
+      name: 'Layout: manifest entries exist on disk',
+      status: 'PASS',
+      message: `All ${manifest.files.length} manifest entries exist on disk`,
+    });
+  } else {
+    results.push({
+      name: 'Layout: manifest entries exist on disk',
+      status: 'FAIL',
+      message: `${missingFiles.length} manifest entry/entries point to missing files:\n  ${missingFiles.join('\n  ')}`,
+      fixHint: 'Run tib doctor --relocate or tib upgrade to fix missing files',
+    });
+  }
+
+  // Check 4: scaffold-tracked files (with @mc-scaffold: header) that lack manifest entries
+  const { readFile: fsReadFile } = await import('node:fs/promises');
+  const manifestPaths = new Set(manifest.files.map(f => f.path));
+  const untracked: string[] = [];
+
+  const walkDir = async (d: string): Promise<void> => {
+    const { readdir } = await import('node:fs/promises');
+    let entries;
+    try { entries = await readdir(d, { withFileTypes: true }); } catch { return; }
+    for (const entry of entries) {
+      const full = pathJoin(d, entry.name);
+      if (entry.isDirectory()) { await walkDir(full); continue; }
+      if (!/\.(ts|tsx|js|yml|yaml)$/.test(entry.name)) continue;
+      const rel = full.replace(projectRoot + '/', '');
+      if (manifestPaths.has(rel)) continue;
+      try {
+        const content = await fsReadFile(full, 'utf-8');
+        if (content.includes('@mc-scaffold:')) untracked.push(rel);
+      } catch { /* skip */ }
+    }
+  };
+
+  const dirsToScan = ['domains', '.github/workflows'];
+  for (const dir of dirsToScan) {
+    const dirPath = pathJoin(projectRoot, dir);
+    try {
+      await walkDir(dirPath);
+    } catch { /* dir missing */ }
+  }
+
+  if (untracked.length === 0) {
+    results.push({
+      name: 'Layout: scaffold-tracked files have manifest entries',
+      status: 'PASS',
+      message: 'All files with @mc-scaffold: headers are in the manifest',
+    });
+  } else {
+    results.push({
+      name: 'Layout: scaffold-tracked files have manifest entries',
+      status: 'WARN',
+      message: `${untracked.length} file(s) with @mc-scaffold: header not in manifest:\n  ${untracked.join('\n  ')}`,
+      fixHint: 'Run tib upgrade or tib doctor --relocate to register these files',
+    });
+  }
+
+  return results;
+}
+
+/**
+ * Old path → new path mapping for known scaffold files
+ */
+const RELOCATION_MAP: Array<{ oldPath: string; newPath: string; policy: 'owned' | 'tracked' | 'seed' }> = [
+  { oldPath: 'infra/modules/app.ts', newPath: '.mc/infra/modules/app.ts', policy: 'owned' },
+  { oldPath: 'infra/modules/shared/SharedStack.ts', newPath: '.mc/infra/modules/shared/SharedStack.ts', policy: 'owned' },
+  { oldPath: 'infra/modules/domains/dispatch-middleware.ts', newPath: '.mc/infra/modules/domains/dispatch-middleware.ts', policy: 'owned' },
+  { oldPath: 'infra/modules/PowerTuningStack.ts', newPath: '.mc/infra/modules/PowerTuningStack.ts', policy: 'owned' },
+  { oldPath: 'infra/cdk.json', newPath: '.mc/infra/cdk.json', policy: 'owned' },
+  { oldPath: 'infra/tsconfig.json', newPath: '.mc/infra/tsconfig.json', policy: 'owned' },
+  { oldPath: 'infra/package.json', newPath: '.mc/infra/package.json', policy: 'owned' },
+  { oldPath: 'mc-deploy.yml', newPath: '.github/workflows/mc-deploy.yml', policy: 'owned' },
+];
+
+/**
+ * Run relocation of old-layout scaffold files to new layout
+ */
+async function runRelocate(projectRoot: string): Promise<DoctorReport> {
+  const checks: DoctorCheck[] = [];
+
+  const { readManifest, writeManifest, upsertManifestFile } = await import('../utils/manifest.js');
+  const { readFile, writeFile, mkdir, unlink } = await import('node:fs/promises');
+  const { computeChecksumFile, computeChecksumString } = await import('../utils/checksum.js');
+  const { join, dirname } = await import('node:path');
+
+  const manifest = await readManifest(projectRoot);
+  if (!manifest) {
+    checks.push({
+      name: 'Relocate: manifest present',
+      status: 'FAIL',
+      message: '.mc/manifest.json not found — cannot relocate without a manifest',
+      fixHint: 'This project may not be a TIB scaffold project',
+    });
+    return { checks, exitCode: 1, pass: false };
+  }
+
+  let moved = 0;
+  let warned = 0;
+  let skipped = 0;
+
+  for (const { oldPath, newPath, policy } of RELOCATION_MAP) {
+    const oldAbsPath = join(projectRoot, oldPath);
+    const newAbsPath = join(projectRoot, newPath);
+
+    // Check if old file exists
+    const { access: fsAccess } = await import('node:fs/promises');
+    try { await fsAccess(oldAbsPath); } catch { skipped++; continue; }
+
+    // Check if it has the scaffold header (confirm it's scaffold-owned)
+    let content: string;
+    try {
+      content = await readFile(oldAbsPath, 'utf-8');
+    } catch {
+      skipped++;
+      continue;
+    }
+
+    if (!content.includes('@mc-scaffold:')) {
+      // File exists but no header — user-owned, leave it
+      checks.push({
+        name: 'Relocate: checking ' + oldPath,
+        status: 'WARN',
+        message: `${oldPath} has no @mc-scaffold: header — left in place (user-owned)`,
+        file: oldPath,
+      });
+      warned++;
+      continue;
+    }
+
+    // Check for user drift
+    const manifestEntry = manifest.files.find(f => f.path === oldPath);
+    if (manifestEntry) {
+      const diskSha = await computeChecksumFile(oldAbsPath);
+      if (diskSha && diskSha !== manifestEntry.sha256) {
+        // File has been modified — leave with warning
+        checks.push({
+          name: 'Relocate: checking ' + oldPath,
+          status: 'WARN',
+          message: `${oldPath} has local modifications — left in place. Migrate manually: move to ${newPath}`,
+          file: oldPath,
+        });
+        warned++;
+        continue;
+      }
+    }
+
+    // Check if destination already exists
+    try {
+      await fsAccess(newAbsPath);
+      checks.push({
+        name: 'Relocate: ' + oldPath,
+        status: 'WARN',
+        message: `${newPath} already exists — skipping move of ${oldPath}`,
+        file: newPath,
+      });
+      warned++;
+      continue;
+    } catch { /* destination doesn't exist, good */ }
+
+    // Move the file
+    try {
+      await mkdir(dirname(newAbsPath), { recursive: true });
+      // Copy + delete (rename may fail across filesystems)
+      await writeFile(newAbsPath, content, 'utf-8');
+
+      // Update manifest: remove old entry, add new with new path + policy
+      manifest.files = manifest.files.filter(f => f.path !== oldPath);
+      const sha256 = manifestEntry?.sha256 ?? computeChecksumString(content);
+      upsertManifestFile(manifest, {
+        path: newPath,
+        module: manifestEntry?.module ?? 'backend-lambda',
+        moduleVersion: manifestEntry?.moduleVersion ?? '1.0.0',
+        sha256,
+        wasTemplate: manifestEntry?.wasTemplate ?? false,
+        installedAt: manifestEntry?.installedAt ?? new Date().toISOString(),
+        policy,
+      });
+
+      // Delete old file
+      await unlink(oldAbsPath);
+
+      checks.push({
+        name: 'Relocate: ' + oldPath,
+        status: 'PASS',
+        message: `Moved ${oldPath} → ${newPath} (policy: ${policy})`,
+        file: newPath,
+      });
+      moved++;
+    } catch (err) {
+      checks.push({
+        name: 'Relocate: ' + oldPath,
+        status: 'FAIL',
+        message: `Failed to move ${oldPath} → ${newPath}: ${String(err)}`,
+        file: oldPath,
+      });
+    }
+  }
+
+  // Write updated manifest
+  if (moved > 0) {
+    await writeManifest(projectRoot, manifest);
+  }
+
+  // Summary check
+  checks.push({
+    name: 'Relocate: summary',
+    status: warned > 0 ? 'WARN' : 'PASS',
+    message: `Relocation complete: ${moved} file(s) moved, ${warned} warning(s), ${skipped} skipped (not present)`,
+  });
+
+  const hasFail = checks.some(c => c.status === 'FAIL');
+  const exitCode = hasFail ? 1 : 0;
+  return { checks, exitCode, pass: exitCode === 0 };
+}