@sanqianx/project-knowledge 4.8.0 → 5.0.0

package/_modules/knowledge-engine/src/migration.js

@@ -1,88 +0,0 @@
-'use strict';
-const fs = require('node:fs');
-const path = require('node:path');
-const crypto = require('node:crypto');
-const AtomicFile = require('./runtime/atomic-file');
-const { validateClaim } = require('./runtime/commit-reconciler');
-const { validateSha } = require('./runtime/scanner');
-const { initialRuntime } = require('./store');
-
-// Only frozen analysis artifacts cross this boundary, never shell settings,
-// registries or credentials. Canonical knowledge files stay where they are.
-async function importLegacyState(coordinator, input) {
-  const { store, layout } = coordinator;
-  if (!/^cutover-[a-f0-9-]{36}$/.test(input.migrationId || '') || !path.isAbsolute(input.sourceDataDir || '') || !Array.isArray(input.projects)) throw failure('INVALID_ARGUMENT');
-  if (store.state.migrations?.includes(input.migrationId)) return { reused: true };
-  if (coordinator.executionEnabled || coordinator.active.size) throw failure('ENGINE_NOT_PAUSED');
-  const backup = path.join(input.sourceDataDir, 'recovery', 'engine-cutover', input.migrationId);
-  if (!fs.existsSync(path.join(backup, 'snapshot.json'))) throw failure('MIGRATION_BACKUP_MISSING');
-  const snapshot = AtomicFile.readJsonStrict(path.join(backup, 'snapshot.json'));
-  if (snapshot.migrationId !== input.migrationId || snapshot.sourceDataDir !== input.sourceDataDir) throw failure('MIGRATION_BACKUP_MISMATCH');
-  input = snapshot;
-  const mappings = ['runs', 'claims', 'promotions', 'processed-commits'].map(kind => [path.join(input.sourceDataDir, 'runtime', kind), layout.getRuntimePath(kind)]);
-  mappings.push([path.join(input.sourceDataDir, 'recovery', 'promotions'), layout.getRecoveryPath('promotions')]);
-  for (const projected of input.projects) mappings.push([path.join(input.sourceDataDir, 'projects', projected.registration.projectId), layout.getProjectMetadataDir(projected.registration.projectId)]);
-  function remap(value) {
-    if (Array.isArray(value)) return value.map(remap);
-    if (value && typeof value === 'object') return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, remap(item)]));
-    if (typeof value === 'string' && path.isAbsolute(value) && !value.includes('\n')) {
-      const mapping = mappings.find(([from]) => layout.isPathInside(from, value));
-      if (mapping) return path.join(mapping[1], path.relative(mapping[0], value));
-    }
-    return value;
-  }
-  function copy(source, target) {
-    if (!fs.existsSync(source)) return;
-    const stat = fs.lstatSync(source);
-    if (stat.isSymbolicLink() || !layout.isPathInside(backup, source, { realpath: true }) || !layout.isPathInside(store.dataDir, target, { realpath: true })) throw failure('MIGRATION_UNSAFE_PATH');
-    if (stat.isDirectory()) {
-      for (const entry of fs.readdirSync(source)) copy(path.join(source, entry), path.join(target, entry));
-      return;
-    }
-    if (!stat.isFile()) throw failure('MIGRATION_UNSAFE_PATH');
-    let bytes = fs.readFileSync(source);
-    if (source.endsWith('.json')) bytes = Buffer.from(JSON.stringify(remap(JSON.parse(bytes.toString('utf8'))), null, 2));
-    if (fs.existsSync(target)) {
-      if (!fs.readFileSync(target).equals(bytes)) throw failure('MIGRATION_ARTIFACT_CONFLICT');
-    } else AtomicFile.writeFileAtomic(target, bytes);
-  }
-  for (const kind of ['runs', 'claims', 'promotions', 'processed-commits']) copy(path.join(backup, 'runtime', kind), layout.getRuntimePath(kind));
-  copy(path.join(backup, 'recovery', 'promotions'), layout.getRecoveryPath('promotions'));
-  for (const { registration, runtime } of input.projects) {
-    const project = store.addProject(registration).project;
-    if (project.migrationId === input.migrationId) continue;
-    if (store.state.runs.some(run => run.projectId === project.projectId)) throw failure('MIGRATION_PROJECT_ALREADY_ACTIVE');
-    const next = initialRuntime(registration);
-    if (runtime.lastAnalyzedCommit) next.lastAnalyzedCommit = validateSha(runtime.lastAnalyzedCommit);
-    next.conversationBaselineCursor = runtime.conversationBaselineCursor ?? next.conversationBaselineCursor;
-    if (runtime.conversationBaselineCursors) {
-      if (Object.entries(runtime.conversationBaselineCursors).some(([journal, cursor]) => !/^(global|sha256:[a-f0-9]{64})$/.test(journal) || !Number.isSafeInteger(cursor) || cursor < 0)) throw failure('MIGRATION_INVALID_BASELINE');
-      next.conversationBaselineCursors = { ...runtime.conversationBaselineCursors };
-    }
-    next.analysis.consumedRequirementIds = (runtime.analysis?.consumedRequirementIds || []).filter(id => typeof id === 'string');
-    next.index.dirty = runtime.index?.dirty === true;
-    const claim = runtime.analysis?.activeClaim;
-    if (claim) {
-      validateClaim(claim, project.projectId, validateSha(claim.commitSha));
-      const claimKeys = ['schema', 'projectId', 'commitSha', 'parents', 'triggerFirstSeen', 'requirementIds', 'requirementBinding', 'conversationSnapshotHash', 'conversationTurnIds', 'conversationEventIds', 'promptTemplateVersion', 'promptHash', 'patchHash', 'evidenceHash', 'evidenceManifestHash', 'retrievalManifestHash', 'knowledgePath', 'runId', 'operationId', 'phase', 'attempt', 'fingerprint'];
-      next.analysis.activeClaim = remap(Object.fromEntries(claimKeys.filter(key => claim[key] !== undefined).map(key => [key, claim[key]])));
-      next.analysis.status = claim.phase;
-    }
-    for (const name of ['conversation-events.jsonl', 'commit-boundaries', 'commit-conversations']) copy(path.join(backup, 'projects', project.projectId, name), path.join(layout.getProjectMetadataDir(project.projectId), name));
-    project.runtime = next;
-    project.migrationId = input.migrationId;
-    store.save();
-    if (claim) {
-      const run = store.addRun({ projectId: project.projectId, commitSha: claim.commitSha, trigger: 'upgrade-recovery' });
-      store.updateRun(run.runId, { analysisRunId: claim.runId, phase: 'recovering' });
-    } else if (next.index.dirty && next.lastAnalyzedCommit) {
-      const run = store.addRun({ projectId: project.projectId, commitSha: next.lastAnalyzedCommit, trigger: 'upgrade-index-recovery' });
-      store.updateRun(run.runId, { promotedAt: new Date().toISOString(), phase: 'index-pending', state: 'index-pending', indexState: 'failed' });
-    }
-  }
-  store.state.migrations = [...(store.state.migrations || []), input.migrationId];
-  store.save();
-  return { migrated: input.projects.length, fingerprint: crypto.createHash('sha256').update(JSON.stringify(input.projects.map(p => [p.registration.projectId, p.runtime.lastAnalyzedCommit]))).digest('hex') };
-}
-function failure(code) { return Object.assign(new Error('运行迁移未完成，原数据与升级备份已保留。'), { code, status: 409 }); }
-module.exports = { importLegacyState };

package/_site/_test/data-dir-migration-test.js

@@ -1,77 +0,0 @@
-const assert = require('assert');
-const fs = require('fs');
-const os = require('os');
-const path = require('path');
-const dataDir = require('../lib/data-dir');
-const { LEGACY_ASSETS } = require('../lib/legacy-data-manifest');
-
-function temp(name) { return fs.mkdtempSync(path.join(os.tmpdir(), `pk-data-dir-${name}-`)); }
-function clean(dir) { fs.rmSync(dir, { recursive: true, force: true }); }
-function write(file, value = '{}') { fs.mkdirSync(path.dirname(file), { recursive: true }); fs.writeFileSync(file, value); }
-
-(() => {
-  // Resolution must be diagnostic-safe: resolving never creates the candidate.
-  const missing = path.join(temp('resolve'), 'not-created');
-  try {
-    assert.equal(dataDir.resolveDataDirPath({ dataDir: missing }), path.resolve(missing));
-    assert.equal(fs.existsSync(missing), false);
-    dataDir.ensureDataDir(missing);
-    assert.equal(fs.existsSync(missing), true);
-  } finally { clean(path.dirname(missing)); }
-
-  const legacy = temp('legacy');
-  const target = temp('target');
-  const saved = process.env.KB_DATA_DIR;
-  try {
-    write(path.join(legacy, 'projects.json'), JSON.stringify({ old: { repoPath: 'C:/legacy' } }));
-    write(path.join(legacy, 'ai-profiles.json'), JSON.stringify({ profiles: [{ id: 'primary', apiKey: 'test-secret' }] }));
-    write(path.join(legacy, 'knowledge-store.json'), JSON.stringify({ rootPath: 'C:/knowledge' }));
-    write(path.join(legacy, 'embedding-config.json'), JSON.stringify({ modelId: 'model', localModelPath: 'C:/models', localFilesOnly: true }));
-    write(path.join(legacy, 'knowledge-scopes.json'), JSON.stringify({ scopes: ['p'] }));
-    write(path.join(legacy, 'models', 'nested', 'model.onnx'), 'model-bytes');
-    // An empty target registry is non-authoritative and must not suppress legacy data.
-    write(path.join(target, 'projects.json'), '{}');
-    process.env.KB_DATA_DIR = target;
-    dataDir._resetCache();
-    const result = dataDir.migrateFromLegacy({ legacyRoot: legacy });
-    assert.equal(result.ok, true);
-    assert.equal(result.migrated, true);
-    assert.equal(JSON.parse(fs.readFileSync(path.join(target, 'projects.json'))).old.repoPath, 'C:/legacy');
-    assert.equal(JSON.parse(fs.readFileSync(path.join(target, 'ai-profiles.json'))).profiles.length, 1);
-    assert.equal(JSON.parse(fs.readFileSync(path.join(target, 'embedding-config.json'))).modelId, 'model');
-    assert.equal(fs.readFileSync(path.join(target, 'models', 'nested', 'model.onnx'), 'utf8'), 'model-bytes');
-    assert(LEGACY_ASSETS.some(asset => asset.source === 'embedding-config.json'));
-    assert(LEGACY_ASSETS.some(asset => asset.source === 'models'));
-  } finally { process.env.KB_DATA_DIR = saved; dataDir._resetCache(); clean(legacy); clean(target); }
-
-  const source = temp('conflict-source');
-  const destination = temp('conflict-destination');
-  try {
-    write(path.join(source, 'projects.json'), JSON.stringify({ old: { repoPath: 'C:/old' } }));
-    write(path.join(destination, 'projects.json'), JSON.stringify({ newer: { repoPath: 'C:/new' } }));
-    process.env.KB_DATA_DIR = destination;
-    dataDir._resetCache();
-    const result = dataDir.migrateFromLegacy({ legacyRoot: source });
-    assert.equal(result.ok, false);
-    assert.equal(result.requiresManualRecovery, true);
-    assert.equal(JSON.parse(fs.readFileSync(path.join(destination, 'projects.json'))).newer.repoPath, 'C:/new');
-  } finally { process.env.KB_DATA_DIR = saved; dataDir._resetCache(); clean(source); clean(destination); }
-
-  // The installed package can contain empty scaffolding directories (for
-  // example projects/) while the user data directory contains real projects.
-  // Empty package scaffolding is not a legacy source and must not block startup.
-  const packageRoot = temp('empty-package-root');
-  const userData = temp('existing-user-data');
-  try {
-    fs.mkdirSync(path.join(packageRoot, 'projects'), { recursive: true });
-    write(path.join(userData, 'projects', 'project-real', 'config.json'), JSON.stringify({ id: 'project-real' }));
-    process.env.KB_DATA_DIR = userData;
-    dataDir._resetCache();
-    const result = dataDir.migrateFromLegacy({ legacyRoot: packageRoot });
-    assert.equal(result.ok, true, 'empty package scaffolding must not be a migration conflict');
-    assert.equal(result.migrated, false);
-    assert.equal(result.reason, 'no legacy assets found');
-    assert.equal(fs.existsSync(path.join(userData, 'projects', 'project-real', 'config.json')), true);
-  } finally { process.env.KB_DATA_DIR = saved; dataDir._resetCache(); clean(packageRoot); clean(userData); }
-  console.log('data-dir-migration-test PASS');
-})();

package/_site/_test/knowledge-migration-test.js

@@ -1,75 +0,0 @@
-const assert = require('assert');
-const fs = require('fs');
-const os = require('os');
-const path = require('path');
-const { StorageLayout } = require('../lib/storage-layout');
-const { SettingsStore } = require('../lib/settings-store');
-const { ProjectStore } = require('../lib/project-store');
-const { MigrationService } = require('../lib/migration-service');
-const { KnowledgeDatabase } = require('../lib/knowledge-db');
-const { EMBEDDING_DIMENSIONS } = require('../lib/knowledge-schema');
-
-(async () => {
-  const dataDir = fs.mkdtempSync(path.join(os.tmpdir(), 'knowledge-migration-v2-'));
-  const oldKnowledgeRoot = path.join(dataDir, 'old-knowledge');
-  const fixedKnowledgePath = path.join(oldKnowledgeRoot, 'api-fixed');
-  const legacyIndex = path.join(dataDir, 'knowledge.lancedb');
-  fs.mkdirSync(fixedKnowledgePath, { recursive: true });
-  fs.writeFileSync(path.join(fixedKnowledgePath, 'GOAL.md'), '# API goal\n\nAuthoritative Markdown remains external.\n', 'utf8');
-  fs.writeFileSync(path.join(dataDir, 'projects.json'), JSON.stringify({
-    api: {
-      displayName: 'API', localPath: dataDir, gitPath: dataDir, kbPath: fixedKnowledgePath,
-      trackingStartCommit: 'track-before', lastAnalyzedCommit: 'commit-before', enabled: true,
-    },
-  }, null, 2));
-  fs.writeFileSync(path.join(dataDir, 'knowledge-store.json'), JSON.stringify({ rootPath: oldKnowledgeRoot, configured: true }));
-  fs.writeFileSync(path.join(dataDir, 'ai-profiles.json'), JSON.stringify({ schema: 'ai-profiles/v1', profiles: [{ id: 'primary', apiKey: 'migration-secret-value' }] }));
-  fs.writeFileSync(path.join(dataDir, 'logging.json'), JSON.stringify({ levels: ['debug', 'info', 'error'], retentionDays: 0, maxTotalSizeMB: 128 }));
-  fs.writeFileSync(path.join(dataDir, '.hook-trigger-errors.log'), '2026-01-01 legacy hook error\n', 'utf8');
-
-  const vector = new Array(EMBEDDING_DIMENSIONS).fill(0);
-  vector[9] = 1;
-  const oldDatabase = new KnowledgeDatabase({ dbPath: legacyIndex });
-  await oldDatabase.replaceEntry('project:api', 'GOAL.md', [{ chunkOrder: 0, title: 'Legacy index', chunkText: 'A migrated derived row.', vector }]);
-  await oldDatabase.close();
-  const oldIndexRows = await (async () => {
-    const db = new KnowledgeDatabase({ dbPath: legacyIndex });
-    try { return await db.count(); } finally { await db.close(); }
-  })();
-
-  const layout = new StorageLayout({ dataDir });
-  const migration = new MigrationService({
-    layout,
-    legacyDataDir: dataDir,
-    indexValidator: async candidate => {
-      const db = new KnowledgeDatabase({ dbPath: candidate });
-      try { await db.open(); return { ok: (await db.count()) === oldIndexRows }; }
-      finally { await db.close(); }
-    },
-  });
-  const result = await migration.migrateIfNeeded({ migrationRunId: 'knowledge-index-v2' });
-  assert(result.ok && result.completed && result.migrated, JSON.stringify(result));
-  const projectId = result.projectMap.api;
-  const projectStore = new ProjectStore({ layout });
-  const config = projectStore.readConfig(projectId);
-  const state = projectStore.readState(projectId);
-  assert.strictEqual(config.knowledgePath, fixedKnowledgePath, 'legacy kbPath must be preserved exactly');
-  assert.strictEqual(state.trackingStartCommit, 'track-before');
-  assert.strictEqual(state.lastAnalyzedCommit, 'commit-before');
-  assert.strictEqual(new SettingsStore({ layout }).read().ai.profiles[0].apiKey, 'migration-secret-value');
-  const migratedDatabase = new KnowledgeDatabase({ dbPath: layout.getIndexPath() });
-  assert.strictEqual(await migratedDatabase.count(), 1, 'the validated legacy index should be copied to the one internal index path');
-  await migratedDatabase.close();
-  assert(fs.existsSync(legacyIndex), 'legacy index source must remain for rollback');
-  assert(fs.existsSync(path.join(result.recoveryDir, 'backup', 'knowledge.lancedb')), 'recovery must retain an index backup');
-  assert(fs.existsSync(path.join(dataDir, '.hook-trigger-errors.log')), 'legacy hook logs must remain at the source');
-  assert(fs.existsSync(path.join(result.recoveryDir, 'backup', '.hook-trigger-errors.log')));
-
-  const settings = new SettingsStore({ layout });
-  await settings.updatePatch({ knowledge: { rootPath: path.join(dataDir, 'new-knowledge-root') } });
-  assert.strictEqual(projectStore.readConfig(projectId).knowledgePath, fixedKnowledgePath, 'changing the global root must not move an imported project');
-  assert.strictEqual(layout.getIndexPath(), path.join(dataDir, 'index', 'knowledge.lancedb'), 'global root changes must not move the derived index');
-  const second = await migration.migrateIfNeeded();
-  assert.strictEqual(second.migrated, false);
-  console.log('knowledge-migration-test: PASS');
-})().catch(error => { console.error(error); process.exitCode = 1; });

package/_site/_test/legacy-forward-compat-test.js

@@ -1,257 +0,0 @@
-// _site/_test/legacy-forward-compat-test.js
-//
-// T08: v4.1.22 -> main forward-compatibility migration. Builds a realistic
-// two-project legacy fixture with team binding + legacy hook + tracking
-// state, runs MigrationService, and asserts every required field is
-// preserved or deterministically derived. Also runs migrateManagedHooks
-// to confirm the T03 hook state machine is the post-migration reality.
-
-const assert = require('assert');
-const fs = require('fs');
-const os = require('os');
-const path = require('path');
-const { spawnSync } = require('child_process');
-
-const { StorageLayout } = require('../lib/storage-layout');
-const { MigrationService } = require('../lib/migration-service');
-const { ProjectStore } = require('../lib/project-store');
-const { ProjectRegistryStore } = require('../lib/project-registry-store');
-const { Logger } = require('../lib/structured-logger');
-const { migrateManagedHooks } = require('../lib/server-app');
-const { LEGACY_HOOK_MARKER, readHookStatus } = require('../lib/hook-manager');
-
-const ROOT = path.resolve(__dirname, '..', '..');
-const TRIGGER = path.join(ROOT, '_site', 'scripts', 'hook-trigger.js');
-
-function git(repo, args) {
-  const result = spawnSync('git', ['-C', repo, ...args], {
-    encoding: 'utf8', windowsHide: true,
-    env: { ...process.env, GIT_TERMINAL_PROMPT: '0' },
-  });
-  if (result.status !== 0) throw new Error(result.stderr || `git ${args.join(' ')} failed: ${result.status}`);
-  return String(result.stdout || '').trim();
-}
-
-function fixture({ withTeamBinding, withLegacyHook, knowledgeLanguage, aiProfileId, enabled, repoPath: customRepoPath } = {}) {
-  const dataDir = fs.mkdtempSync(path.join(os.tmpdir(), 'pk-legacy-forward-compat-'));
-  const repoPath = customRepoPath || path.join(dataDir, 'repos', 'legacy-team');
-  fs.mkdirSync(repoPath, { recursive: true });
-  git(repoPath, ['init', '-q', '-b', 'main']);
-  git(repoPath, ['config', 'user.email', 'legacy-fc@example.local']);
-  git(repoPath, ['config', 'user.name', 'Legacy FC']);
-  fs.writeFileSync(path.join(repoPath, 'README.md'), '# legacy\n');
-  git(repoPath, ['add', 'README.md']);
-  git(repoPath, ['commit', '-q', '-m', 'initial']);
-  const initialSha = git(repoPath, ['rev-parse', 'HEAD']);
-
-  if (withLegacyHook) {
-    const gitDir = git(repoPath, ['rev-parse', '--path-format=absolute', '--git-dir']);
-    const hooksDir = path.join(path.resolve(gitDir), 'hooks');
-    fs.mkdirSync(hooksDir, { recursive: true });
-    fs.writeFileSync(path.join(hooksDir, 'post-commit'), (
-      `#!/bin/sh\n${LEGACY_HOOK_MARKER} — auto-installed by KB manager (legacy)\n` +
-      `node 'C:/legacy/site/_site/scripts/hook-trigger.js' \\\n` +
-      `  --kb-root 'C:/legacy/site' --repo "${repoPath.replace(/\\/g, '/')}" >/dev/null 2>&1 || true\n` +
-      `exit 0\n`
-    ), { mode: 0o755 });
-  }
-
-  // Knowledge path
-  const kbPath = path.join(dataDir, 'knowledge', 'legacy-team');
-  fs.mkdirSync(kbPath, { recursive: true });
-
-  // Team binding
-  const teamBinding = withTeamBinding ? {
-    teamKbId: 'team-store/team-a',
-    provider: 'github',
-  } : null;
-
-  const projectEntry = {
-    schema: 'kb-project/v1',
-    displayName: 'Legacy Team',
-    localPath: repoPath,
-    gitPath: repoPath,
-    kbPath,
-    trackingStartCommit: initialSha,
-    lastAnalyzedCommit: initialSha,
-    enabled: enabled !== false,
-    aiProfileId: aiProfileId !== undefined ? aiProfileId : 'primary',
-    knowledgeLanguage: knowledgeLanguage || 'zh-CN',
-    teamBinding,
-  };
-
-  fs.writeFileSync(path.join(dataDir, 'projects.json'), JSON.stringify({
-    'legacy-team': projectEntry,
-  }, null, 2));
-  fs.writeFileSync(path.join(dataDir, 'knowledge-store.json'), JSON.stringify({
-    schema: 'knowledge-store/v1',
-    rootPath: path.join(dataDir, 'knowledge'),
-    configured: true,
-  }));
-  fs.writeFileSync(path.join(dataDir, 'ai-profiles.json'), JSON.stringify({
-    schema: 'ai-profiles/v1',
-    profiles: [{ id: 'primary', name: 'Primary', enabled: true, vendor: 'anthropic', model: 'claude-sonnet' }],
-    defaultProfileId: 'primary',
-  }));
-  return { dataDir, repoPath, kbPath, initialSha };
-}
-
-async function run() {
-  // Case 1: deterministic projectId + repoPath + knowledgePath + tracking
-  {
-    const { dataDir, repoPath, kbPath, initialSha } = fixture();
-    const layout = new StorageLayout({ dataDir });
-    const migration = new MigrationService({ layout, legacyDataDir: dataDir });
-    const result = await migration.migrateIfNeeded({ migrationRunId: 'fc-det' });
-    assert.strictEqual(result.ok, true);
-    const projectId = result.projectMap['legacy-team'];
-    assert(projectId, 'deterministic projectId must be produced');
-    const config = JSON.parse(fs.readFileSync(layout.getProjectConfigPath(projectId), 'utf8'));
-    const state = JSON.parse(fs.readFileSync(layout.getProjectStatePath(projectId), 'utf8'));
-    assert.strictEqual(config.repoPath, path.resolve(repoPath), 'repoPath must be preserved (not data-dir fallback)');
-    assert.strictEqual(config.knowledgePath, path.resolve(kbPath), 'knowledgePath must be preserved');
-    assert.strictEqual(config.enabled, true, 'enabled must be preserved');
-    assert.strictEqual(state.trackingStartCommit, initialSha, 'trackingStartCommit must be preserved');
-    assert.strictEqual(state.lastAnalyzedCommit, initialSha, 'lastAnalyzedCommit must be preserved');
-    // Idempotence: second migration must not re-migrate
-    const second = await migration.migrateIfNeeded();
-    assert.strictEqual(second.completed, true);
-    assert.strictEqual(second.migrated, false);
-    fs.rmSync(dataDir, { recursive: true, force: true });
-  }
-
-  // Case 2: knowledgeLanguage + aiProfileId + teamBinding preservation
-  {
-    const { dataDir, repoPath, kbPath } = fixture({
-      withTeamBinding: true, knowledgeLanguage: 'en-US', aiProfileId: 'primary',
-    });
-    const layout = new StorageLayout({ dataDir });
-    const migration = new MigrationService({ layout, legacyDataDir: dataDir });
-    const result = await migration.migrateIfNeeded({ migrationRunId: 'fc-team' });
-    assert.strictEqual(result.ok, true);
-    const projectId = result.projectMap['legacy-team'];
-    const config = JSON.parse(fs.readFileSync(layout.getProjectConfigPath(projectId), 'utf8'));
-    assert.strictEqual(config.knowledgeLanguage, 'en-US', 'knowledgeLanguage must be preserved');
-    assert.strictEqual(config.aiProfileId, 'primary', 'aiProfileId must be preserved');
-    assert(config.teamBinding && config.teamBinding.teamKbId === 'team-store/team-a', 'teamBinding must be preserved');
-    assert.strictEqual(config.teamBinding.provider, 'github');
-    fs.rmSync(dataDir, { recursive: true, force: true });
-  }
-
-  // Case 3: AI profile semantics via T01 — stale project aiProfileId
-  // falls back to default or first-usable. Here legacy has aiProfileId='stale'
-  // but the global default is 'primary'; the resolver must surface 'primary'
-  // when CommitReconciler runs. (The migration itself preserves the stale
-  // id; the resolver is what fixes it at runtime.)
-  {
-    const { dataDir, repoPath } = fixture({ aiProfileId: 'stale-deleted-profile' });
-    const layout = new StorageLayout({ dataDir });
-    const migration = new MigrationService({ layout, legacyDataDir: dataDir });
-    const result = await migration.migrateIfNeeded({ migrationRunId: 'fc-stale-profile' });
-    const projectId = result.projectMap['legacy-team'];
-    const config = JSON.parse(fs.readFileSync(layout.getProjectConfigPath(projectId), 'utf8'));
-    assert.strictEqual(config.aiProfileId, 'stale-deleted-profile', 'migration preserves whatever was in the legacy record; resolver handles fallback at runtime');
-    const { resolveEffectiveAiProfile } = require('../lib/ai-profile-resolver');
-    const settings = JSON.parse(fs.readFileSync(layout.getSettingsPath(), 'utf8'));
-    const resolved = resolveEffectiveAiProfile(settings, config);
-    assert.strictEqual(resolved.profileId, 'primary', 'T01 resolver must fall back to default when project id is stale');
-    assert.strictEqual(resolved.source, 'default');
-    fs.rmSync(dataDir, { recursive: true, force: true });
-  }
-
-  // Case 4: hook migration via T03 — legacy v1 hook present, must be replaced
-  // and project state must report verified v2 after migrateManagedHooks.
-  {
-    const { dataDir, repoPath } = fixture({ withLegacyHook: true });
-    const layout = new StorageLayout({ dataDir });
-    const migration = new MigrationService({ layout, legacyDataDir: dataDir });
-    const result = await migration.migrateIfNeeded({ migrationRunId: 'fc-hook' });
-    const projectId = result.projectMap['legacy-team'];
-    const projectStore = new ProjectStore({ layout });
-    const registryStore = new ProjectRegistryStore({ layout });
-    await registryStore.initialize();
-    const logger = new Logger({ layout, settingsProvider: () => ({ levels: [] }), context: { component: 'fc' } });
-    const runtime = { registryStore, projectStore, logger, layout, analysisOwner: 'legacy', bridgeAdapter: { hookBinding: () => ({ dataDir: layout.getDataDir() }) } };
-    const hooks = await migrateManagedHooks(runtime);
-    const entry = hooks.find(item => item.projectId === projectId);
-    assert(entry, 'migrateManagedHooks must process the migrated project');
-    assert.strictEqual(entry.status, 'verified');
-    assert.strictEqual(entry.reason, 'v1-migrated');
-    const status = readHookStatus({ repoPath, projectId });
-    assert.strictEqual(status.kbManaged, true);
-    assert.strictEqual(status.managedVersion, 2);
-    const finalState = projectStore.readState(projectId);
-    assert.strictEqual(finalState.hook.migrationVersion, 2);
-    await logger.close();
-    fs.rmSync(dataDir, { recursive: true, force: true });
-  }
-
-  // Case 5: disabled=false preservation
-  {
-    const { dataDir } = fixture({ enabled: false });
-    const layout = new StorageLayout({ dataDir });
-    const migration = new MigrationService({ layout, legacyDataDir: dataDir });
-    const result = await migration.migrateIfNeeded({ migrationRunId: 'fc-disabled' });
-    const projectId = result.projectMap['legacy-team'];
-    const config = JSON.parse(fs.readFileSync(layout.getProjectConfigPath(projectId), 'utf8'));
-    assert.strictEqual(config.enabled, false, 'enabled=false must be preserved');
-    fs.rmSync(dataDir, { recursive: true, force: true });
-  }
-
-  // Case 6: repoPath MUST NOT be replaced with a data-dir fallback when a
-  // valid legacy repoPath exists. (RC-style protection: a buggy migration
-  // would substitute knowledgeDir/projects/<id> for repoPath.)
-  {
-    const dataDir = fs.mkdtempSync(path.join(os.tmpdir(), 'pk-legacy-no-repo-fallback-'));
-    const repoPath = path.join(dataDir, 'real', 'project');
-    fs.mkdirSync(repoPath, { recursive: true });
-    git(repoPath, ['init', '-q', '-b', 'main']);
-    git(repoPath, ['config', 'user.email', 'legacy-fc@example.local']);
-    git(repoPath, ['config', 'user.name', 'Legacy FC']);
-    fs.writeFileSync(path.join(repoPath, 'README.md'), '# legacy\n');
-    git(repoPath, ['add', 'README.md']);
-    git(repoPath, ['commit', '-q', '-m', 'initial']);
-    const initialSha = git(repoPath, ['rev-parse', 'HEAD']);
-    const kbPath = path.join(dataDir, 'knowledge', 'legacy-team');
-    fs.mkdirSync(kbPath, { recursive: true });
-    fs.writeFileSync(path.join(dataDir, 'projects.json'), JSON.stringify({
-      'legacy-team': {
-        schema: 'kb-project/v1',
-        displayName: 'Legacy Team',
-        localPath: repoPath,
-        gitPath: repoPath,
-        kbPath,
-        trackingStartCommit: initialSha,
-        lastAnalyzedCommit: initialSha,
-        enabled: true,
-        aiProfileId: 'primary',
-        knowledgeLanguage: 'zh-CN',
-      },
-    }, null, 2));
-    fs.writeFileSync(path.join(dataDir, 'knowledge-store.json'), JSON.stringify({
-      schema: 'knowledge-store/v1',
-      rootPath: path.join(dataDir, 'knowledge'),
-      configured: true,
-    }));
-    fs.writeFileSync(path.join(dataDir, 'ai-profiles.json'), JSON.stringify({
-      schema: 'ai-profiles/v1',
-      profiles: [{ id: 'primary', name: 'Primary', enabled: true, vendor: 'anthropic', model: 'claude-sonnet' }],
-      defaultProfileId: 'primary',
-    }));
-    const layout = new StorageLayout({ dataDir });
-    const migration = new MigrationService({ layout, legacyDataDir: dataDir });
-    const result = await migration.migrateIfNeeded({ migrationRunId: 'fc-no-fallback' });
-    assert(result.projectMap && result.projectMap['legacy-team'], 'migration must produce projectMap');
-    const projectId = result.projectMap['legacy-team'];
-    const config = JSON.parse(fs.readFileSync(layout.getProjectConfigPath(projectId), 'utf8'));
-    assert.strictEqual(config.repoPath, path.resolve(repoPath), 'repoPath must NOT be silently rewritten to a data-dir fallback');
-    fs.rmSync(dataDir, { recursive: true, force: true });
-  }
-
-  console.log('legacy-forward-compat-test PASS');
-}
-
-run().catch(error => {
-  console.error(error.stack || error.message);
-  process.exit(1);
-});