@sanqianx/project-knowledge 4.7.0 → 4.8.0

package/_site/_test/project-layout-v2-migration-test.js

@@ -1,127 +1,127 @@
-const assert = require('assert');
-const fs = require('fs');
-const os = require('os');
-const path = require('path');
-const { StorageLayout } = require('../lib/storage-layout');
-const { MigrationService } = require('../lib/migration-service');
-
-function fixture() {
-  const dataDir = fs.mkdtempSync(path.join(os.tmpdir(), 'pk-layout-v2-migration-'));
-  const oldRoot = path.join(dataDir, 'old-knowledge');
-  const differentRoot = path.join(dataDir, 'different-current-root');
-  fs.mkdirSync(oldRoot, { recursive: true });
-  const exactKbPath = path.join(oldRoot, 'legacy-a-fixed');
-  fs.mkdirSync(exactKbPath, { recursive: true });
-  fs.writeFileSync(path.join(exactKbPath, 'README.md'), '# existing knowledge\n', 'utf8');
-  fs.writeFileSync(path.join(dataDir, 'projects.json'), JSON.stringify({
-    legacyA: {
-      displayName: 'Legacy A',
-      localPath: path.join(dataDir, 'repo-a'),
-      gitPath: path.join(dataDir, 'repo-a'),
-      kbPath: exactKbPath,
-      trackingStartCommit: 'track-a',
-      lastAnalyzedCommit: 'last-a',
-      enabled: true,
-      aiProfileId: 'primary',
-    },
-    legacyB: {
-      displayName: 'Legacy B',
-      localPath: path.join(dataDir, 'repo-b'),
-      trackingStartCommit: 'track-b',
-      enabled: true,
-    },
-  }, null, 2));
-  fs.writeFileSync(path.join(dataDir, 'knowledge-store.json'), JSON.stringify({ rootPath: differentRoot, configured: true }));
-  fs.writeFileSync(path.join(dataDir, 'ai-profiles.json'), JSON.stringify({ schema: 'ai-profiles/v1', profiles: [{ id: 'primary', apiKey: 'exact-secret-value' }] }));
-  fs.writeFileSync(path.join(dataDir, 'embedding-config.json'), JSON.stringify({ modelId: 'model-a' }));
-  fs.writeFileSync(path.join(dataDir, 'logging.json'), JSON.stringify({ levels: ['debug', 'info', 'error'], retentionDays: 0, maxTotalSizeMB: 512 }));
-  fs.writeFileSync(path.join(dataDir, 'claude-prompts.json'), JSON.stringify({ hookPromptTemplate: 'legacy override' }));
-  fs.writeFileSync(path.join(dataDir, '.hook-trigger-errors.log'), '2026-01-01 old hook error\n');
-  return { dataDir, exactKbPath, differentRoot };
-}
-
-(async () => {
-  {
-    const { dataDir, exactKbPath, differentRoot } = fixture();
-    const layout = new StorageLayout({ dataDir });
-    const migration = new MigrationService({ layout, legacyDataDir: dataDir });
-    const result = await migration.migrateIfNeeded({ migrationRunId: 'layout-v2-success' });
-    assert.strictEqual(result.ok, true);
-    assert.strictEqual(result.completed, true);
-    assert(fs.existsSync(layout.getMigrationCompletionPath()));
-    const registry = JSON.parse(fs.readFileSync(layout.getProjectRegistryPath(), 'utf8'));
-    assert.strictEqual(registry.schema, 'project-registry/v2');
-    assert.strictEqual(registry.projectOrder.length, 2);
-    const idA = result.projectMap.legacyA;
-    const idB = result.projectMap.legacyB;
-    const configA = JSON.parse(fs.readFileSync(layout.getProjectConfigPath(idA), 'utf8'));
-    const configB = JSON.parse(fs.readFileSync(layout.getProjectConfigPath(idB), 'utf8'));
-    const stateA = JSON.parse(fs.readFileSync(layout.getProjectStatePath(idA), 'utf8'));
-    assert.strictEqual(configA.knowledgePath, exactKbPath, 'old kbPath must remain exact');
-    assert.strictEqual(configB.knowledgePath, path.join(differentRoot, 'legacyB'));
-    assert.strictEqual(stateA.trackingStartCommit, 'track-a');
-    assert.strictEqual(stateA.lastAnalyzedCommit, 'last-a');
-    const settings = JSON.parse(fs.readFileSync(layout.getSettingsPath(), 'utf8'));
-    assert.strictEqual(settings.ai.profiles[0].apiKey, 'exact-secret-value');
-    assert.strictEqual(Object.prototype.hasOwnProperty.call(settings.logging, 'retentionDays'), false);
-    assert.strictEqual(settings.legacyExtensions.logging.retentionDays, 0, 'legacy logging settings remain preserved as read-only migration evidence');
-    assert(fs.existsSync(path.join(result.recoveryDir, 'backup', 'projects.json')));
-    assert(fs.existsSync(path.join(dataDir, '.hook-trigger-errors.log')), 'legacy hook log must remain');
-    const second = await migration.migrateIfNeeded();
-    assert.strictEqual(second.completed, true);
-    assert.strictEqual(second.migrated, false);
-  }
-
-  for (const stage of ['backup', 'staging', 'validation', 'activation', 'open-verification']) {
-    const { dataDir } = fixture();
-    const originalProjects = fs.readFileSync(path.join(dataDir, 'projects.json'), 'utf8');
-    const layout = new StorageLayout({ dataDir });
-    const migration = new MigrationService({ layout, legacyDataDir: dataDir });
-    const result = await migration.migrateIfNeeded({ migrationRunId: `fault-${stage}`, faultAt: stage });
-    assert.strictEqual(result.ok, false, `${stage} should fail`);
-    assert.strictEqual(result.useLegacy, true);
-    assert.strictEqual(fs.existsSync(layout.getMigrationCompletionPath()), false, `${stage} must not write completion`);
-    assert.strictEqual(fs.readFileSync(path.join(dataDir, 'projects.json'), 'utf8'), originalProjects, `${stage} must preserve/restore legacy registry`);
-    const journal = JSON.parse(fs.readFileSync(path.join(result.recoveryDir, 'journal.json'), 'utf8'));
-    assert.strictEqual(journal.phase, 'failed');
-    assert.strictEqual(journal.rollback.ok, true, `${stage} rollback must complete`);
-    assert.strictEqual(fs.existsSync(layout.getSettingsPath()), false, `${stage} must remove newly activated settings`);
-    assert.strictEqual(fs.existsSync(path.join(dataDir, 'projects')), false, `${stage} must remove newly activated project metadata`);
-    if (['activation', 'open-verification'].includes(stage)) {
-      const retry = await migration.migrateIfNeeded({ migrationRunId: `retry-${stage}` });
-      assert.strictEqual(retry.ok, true, `${stage} must be safely retryable after rollback`);
-      assert.strictEqual(retry.completed, true);
-    }
-  }
-
-  {
-    const dataDir = fs.mkdtempSync(path.join(os.tmpdir(), 'pk-layout-v2-fresh-'));
-    const layout = new StorageLayout({ dataDir });
-    const result = await new MigrationService({ layout }).migrateIfNeeded();
-    assert.strictEqual(result.reason, 'fresh-install');
-    assert.strictEqual(fs.existsSync(layout.getRecoveryPath()), false, 'fresh install must not create optional recovery dir');
-  }
-
-  {
-    // Regression: legacy files carrying a UTF-8 BOM (common from PowerShell
-    // tooling) must migrate cleanly instead of failing as corrupt sources.
-    const dataDir = fs.mkdtempSync(path.join(os.tmpdir(), 'pk-layout-v2-bom-'));
-    const layout = new StorageLayout({ dataDir });
-    const bom = Buffer.concat([Buffer.from([0xef, 0xbb, 0xbf]), Buffer.from(JSON.stringify({
-      legacyA: { displayName: 'BOM A', localPath: path.join(dataDir, 'repo-a'), trackingStartCommit: 'track-a', enabled: true }
-    }), 'utf8')]);
-    fs.writeFileSync(path.join(dataDir, 'projects.json'), bom);
-    fs.writeFileSync(path.join(dataDir, 'team-git-providers.json'), Buffer.concat([Buffer.from([0xef, 0xbb, 0xbf]), Buffer.from('{}', 'utf8')]));
-    const result = await new MigrationService({ layout, legacyDataDir: dataDir }).migrateIfNeeded();
-    assert.strictEqual(result.ok, true, 'BOM-prefixed legacy sources must migrate');
-    assert.strictEqual(result.migrated, true);
-    const registry = JSON.parse(fs.readFileSync(layout.getProjectRegistryPath(), 'utf8'));
-    assert.strictEqual(registry.schema, 'project-registry/v2');
-    assert.strictEqual(Object.keys(registry.projects).length, 1);
-  }
-
-  console.log('project-layout-v2-migration-test PASS');
-})().catch(error => {
-  console.error(error.stack || error.message);
-  process.exitCode = 1;
-});
+const assert = require('assert');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { StorageLayout } = require('../lib/storage-layout');
+const { MigrationService } = require('../lib/migration-service');
+
+function fixture() {
+  const dataDir = fs.mkdtempSync(path.join(os.tmpdir(), 'pk-layout-v2-migration-'));
+  const oldRoot = path.join(dataDir, 'old-knowledge');
+  const differentRoot = path.join(dataDir, 'different-current-root');
+  fs.mkdirSync(oldRoot, { recursive: true });
+  const exactKbPath = path.join(oldRoot, 'legacy-a-fixed');
+  fs.mkdirSync(exactKbPath, { recursive: true });
+  fs.writeFileSync(path.join(exactKbPath, 'README.md'), '# existing knowledge\n', 'utf8');
+  fs.writeFileSync(path.join(dataDir, 'projects.json'), JSON.stringify({
+    legacyA: {
+      displayName: 'Legacy A',
+      localPath: path.join(dataDir, 'repo-a'),
+      gitPath: path.join(dataDir, 'repo-a'),
+      kbPath: exactKbPath,
+      trackingStartCommit: 'track-a',
+      lastAnalyzedCommit: 'last-a',
+      enabled: true,
+      aiProfileId: 'primary',
+    },
+    legacyB: {
+      displayName: 'Legacy B',
+      localPath: path.join(dataDir, 'repo-b'),
+      trackingStartCommit: 'track-b',
+      enabled: true,
+    },
+  }, null, 2));
+  fs.writeFileSync(path.join(dataDir, 'knowledge-store.json'), JSON.stringify({ rootPath: differentRoot, configured: true }));
+  fs.writeFileSync(path.join(dataDir, 'ai-profiles.json'), JSON.stringify({ schema: 'ai-profiles/v1', profiles: [{ id: 'primary', apiKey: 'exact-secret-value' }] }));
+  fs.writeFileSync(path.join(dataDir, 'embedding-config.json'), JSON.stringify({ modelId: 'model-a' }));
+  fs.writeFileSync(path.join(dataDir, 'logging.json'), JSON.stringify({ levels: ['debug', 'info', 'error'], retentionDays: 0, maxTotalSizeMB: 512 }));
+  fs.writeFileSync(path.join(dataDir, 'claude-prompts.json'), JSON.stringify({ hookPromptTemplate: 'legacy override' }));
+  fs.writeFileSync(path.join(dataDir, '.hook-trigger-errors.log'), '2026-01-01 old hook error\n');
+  return { dataDir, exactKbPath, differentRoot };
+}
+
+(async () => {
+  {
+    const { dataDir, exactKbPath, differentRoot } = fixture();
+    const layout = new StorageLayout({ dataDir });
+    const migration = new MigrationService({ layout, legacyDataDir: dataDir });
+    const result = await migration.migrateIfNeeded({ migrationRunId: 'layout-v2-success' });
+    assert.strictEqual(result.ok, true);
+    assert.strictEqual(result.completed, true);
+    assert(fs.existsSync(layout.getMigrationCompletionPath()));
+    const registry = JSON.parse(fs.readFileSync(layout.getProjectRegistryPath(), 'utf8'));
+    assert.strictEqual(registry.schema, 'project-registry/v2');
+    assert.strictEqual(registry.projectOrder.length, 2);
+    const idA = result.projectMap.legacyA;
+    const idB = result.projectMap.legacyB;
+    const configA = JSON.parse(fs.readFileSync(layout.getProjectConfigPath(idA), 'utf8'));
+    const configB = JSON.parse(fs.readFileSync(layout.getProjectConfigPath(idB), 'utf8'));
+    const stateA = JSON.parse(fs.readFileSync(layout.getProjectStatePath(idA), 'utf8'));
+    assert.strictEqual(configA.knowledgePath, exactKbPath, 'old kbPath must remain exact');
+    assert.strictEqual(configB.knowledgePath, path.join(differentRoot, 'legacyB'));
+    assert.strictEqual(stateA.trackingStartCommit, 'track-a');
+    assert.strictEqual(stateA.lastAnalyzedCommit, 'last-a');
+    const settings = JSON.parse(fs.readFileSync(layout.getSettingsPath(), 'utf8'));
+    assert.strictEqual(settings.ai.profiles[0].apiKey, 'exact-secret-value');
+    assert.strictEqual(Object.prototype.hasOwnProperty.call(settings.logging, 'retentionDays'), false);
+    assert.strictEqual(settings.legacyExtensions.logging.retentionDays, 0, 'legacy logging settings remain preserved as read-only migration evidence');
+    assert(fs.existsSync(path.join(result.recoveryDir, 'backup', 'projects.json')));
+    assert(fs.existsSync(path.join(dataDir, '.hook-trigger-errors.log')), 'legacy hook log must remain');
+    const second = await migration.migrateIfNeeded();
+    assert.strictEqual(second.completed, true);
+    assert.strictEqual(second.migrated, false);
+  }
+
+  for (const stage of ['backup', 'staging', 'validation', 'activation', 'open-verification']) {
+    const { dataDir } = fixture();
+    const originalProjects = fs.readFileSync(path.join(dataDir, 'projects.json'), 'utf8');
+    const layout = new StorageLayout({ dataDir });
+    const migration = new MigrationService({ layout, legacyDataDir: dataDir });
+    const result = await migration.migrateIfNeeded({ migrationRunId: `fault-${stage}`, faultAt: stage });
+    assert.strictEqual(result.ok, false, `${stage} should fail`);
+    assert.strictEqual(result.useLegacy, true);
+    assert.strictEqual(fs.existsSync(layout.getMigrationCompletionPath()), false, `${stage} must not write completion`);
+    assert.strictEqual(fs.readFileSync(path.join(dataDir, 'projects.json'), 'utf8'), originalProjects, `${stage} must preserve/restore legacy registry`);
+    const journal = JSON.parse(fs.readFileSync(path.join(result.recoveryDir, 'journal.json'), 'utf8'));
+    assert.strictEqual(journal.phase, 'failed');
+    assert.strictEqual(journal.rollback.ok, true, `${stage} rollback must complete`);
+    assert.strictEqual(fs.existsSync(layout.getSettingsPath()), false, `${stage} must remove newly activated settings`);
+    assert.strictEqual(fs.existsSync(path.join(dataDir, 'projects')), false, `${stage} must remove newly activated project metadata`);
+    if (['activation', 'open-verification'].includes(stage)) {
+      const retry = await migration.migrateIfNeeded({ migrationRunId: `retry-${stage}` });
+      assert.strictEqual(retry.ok, true, `${stage} must be safely retryable after rollback`);
+      assert.strictEqual(retry.completed, true);
+    }
+  }
+
+  {
+    const dataDir = fs.mkdtempSync(path.join(os.tmpdir(), 'pk-layout-v2-fresh-'));
+    const layout = new StorageLayout({ dataDir });
+    const result = await new MigrationService({ layout }).migrateIfNeeded();
+    assert.strictEqual(result.reason, 'fresh-install');
+    assert.strictEqual(fs.existsSync(layout.getRecoveryPath()), false, 'fresh install must not create optional recovery dir');
+  }
+
+  {
+    // Regression: legacy files carrying a UTF-8 BOM (common from PowerShell
+    // tooling) must migrate cleanly instead of failing as corrupt sources.
+    const dataDir = fs.mkdtempSync(path.join(os.tmpdir(), 'pk-layout-v2-bom-'));
+    const layout = new StorageLayout({ dataDir });
+    const bom = Buffer.concat([Buffer.from([0xef, 0xbb, 0xbf]), Buffer.from(JSON.stringify({
+      legacyA: { displayName: 'BOM A', localPath: path.join(dataDir, 'repo-a'), trackingStartCommit: 'track-a', enabled: true }
+    }), 'utf8')]);
+    fs.writeFileSync(path.join(dataDir, 'projects.json'), bom);
+    fs.writeFileSync(path.join(dataDir, 'team-git-providers.json'), Buffer.concat([Buffer.from([0xef, 0xbb, 0xbf]), Buffer.from('{}', 'utf8')]));
+    const result = await new MigrationService({ layout, legacyDataDir: dataDir }).migrateIfNeeded();
+    assert.strictEqual(result.ok, true, 'BOM-prefixed legacy sources must migrate');
+    assert.strictEqual(result.migrated, true);
+    const registry = JSON.parse(fs.readFileSync(layout.getProjectRegistryPath(), 'utf8'));
+    assert.strictEqual(registry.schema, 'project-registry/v2');
+    assert.strictEqual(Object.keys(registry.projects).length, 1);
+  }
+
+  console.log('project-layout-v2-migration-test PASS');
+})().catch(error => {
+  console.error(error.stack || error.message);
+  process.exitCode = 1;
+});

package/_site/_test/project-lifecycle-transaction-test.js

@@ -1,106 +1,106 @@
-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 { SettingsStore } = require('../lib/settings-store');
-const { ProjectRegistryStore } = require('../lib/project-registry-store');
-const { ProjectStore } = require('../lib/project-store');
-const { ProjectLifecycleService } = require('../lib/project-lifecycle-service');
-const realHookManager = 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`);
-  return String(result.stdout || '').trim();
-}
-
-function createRepo(root, name, withCommit = true) {
-  const repo = path.join(root, name);
-  fs.mkdirSync(repo, { recursive: true });
-  git(repo, ['init', '--initial-branch=main']);
-  git(repo, ['config', 'user.email', 'life@example.invalid']);
-  git(repo, ['config', 'user.name', 'Lifecycle Test']);
-  if (withCommit) {
-    fs.writeFileSync(path.join(repo, 'README.md'), `# ${name}\n`);
-    git(repo, ['add', 'README.md']);
-    git(repo, ['commit', '-m', 'initial']);
-  }
-  return repo;
-}
-
-(async () => {
-  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'pk-lifecycle-'));
-  const dataDir = path.join(root, 'data');
-  const knowledgeRoot = path.join(root, 'knowledge');
-  const layout = new StorageLayout({ dataDir });
-  const settings = new SettingsStore({ layout });
-  const registry = new ProjectRegistryStore({ layout });
-  const projects = new ProjectStore({ layout });
-  await settings.initialize({ knowledge: { rootPath: knowledgeRoot } });
-  await registry.initialize();
-  const lifecycle = new ProjectLifecycleService({
-    layout,
-    settingsStore: settings,
-    registryStore: registry,
-    projectStore: projects,
-    triggerScriptPath: TRIGGER,
-    bridgeAdapter: { async getHighWatermark() { return { status: 'captured', cursor: 73 }; } },
-  });
-
-  const repo = createRepo(root, 'repo-a');
-  const claude = path.join(repo, 'CLAUDE.md');
-  fs.writeFileSync(claude, '# user only\n');
-  const imported = await lifecycle.importProject({ localPath: repo, projectId: 'project-life-a', storageName: 'repo-a-stable' });
-  assert.strictEqual(imported.ok, true);
-  assert.strictEqual(imported.config.aiProfileId, null, 'import must not require an AI profile');
-  assert.strictEqual(imported.state.trackingStartCommit, git(repo, ['rev-parse', 'HEAD']));
-  assert.strictEqual(imported.state.conversationBaselineCursor, 73, 'import must freeze the current Bridge cursor as its conversation baseline');
-  assert.deepStrictEqual(fs.readdirSync(imported.config.knowledgePath), [], 'import must not create TODO knowledge files');
-  assert.strictEqual(fs.readFileSync(claude, 'utf8'), '# user only\n');
-  assert.strictEqual(realHookManager.readHookStatus({ repoPath: repo, projectId: imported.projectId }).installed, true);
-  await assert.rejects(lifecycle.importProject({ localPath: repo }), /already imported/);
-
-  const conflictRepo = createRepo(root, 'repo-conflict');
-  const conflictPath = path.join(knowledgeRoot, 'conflict-stable');
-  fs.mkdirSync(conflictPath, { recursive: true });
-  fs.writeFileSync(path.join(conflictPath, 'user.md'), 'do not overwrite');
-  await assert.rejects(lifecycle.importProject({ localPath: conflictRepo, projectId: 'project-conflict', storageName: 'conflict-stable' }), error => error.code === 'MIGRATION_TARGET_CONFLICT');
-  assert(!registry.listIds().includes('project-conflict'));
-  assert.strictEqual(fs.readFileSync(path.join(conflictPath, 'user.md'), 'utf8'), 'do not overwrite');
-
-  const failingRepo = createRepo(root, 'repo-failing');
-  const failingHooks = { ...realHookManager, installHook() { throw new Error('injected Hook failure'); } };
-  const failingLifecycle = new ProjectLifecycleService({ layout, settingsStore: settings, registryStore: registry, projectStore: projects, triggerScriptPath: TRIGGER, hookManager: failingHooks });
-  await assert.rejects(failingLifecycle.importProject({ localPath: failingRepo, projectId: 'project-failing', storageName: 'failing-stable' }));
-  assert(!registry.listIds().includes('project-failing'));
-  assert(!fs.existsSync(layout.getProjectMetadataDir('project-failing')));
-  assert(!fs.existsSync(path.join(knowledgeRoot, 'failing-stable')));
-
-  const emptyRepo = createRepo(root, 'repo-empty', false);
-  const empty = await lifecycle.importProject({ localPath: emptyRepo, projectId: 'project-empty', storageName: 'empty-stable' });
-  assert.strictEqual(empty.state.trackingMode, 'empty-repo');
-  assert.strictEqual(empty.state.trackingStartCommit, null);
-
-  const failingDelete = new ProjectLifecycleService({
-    layout, settingsStore: settings, registryStore: registry, projectStore: projects, triggerScriptPath: TRIGGER,
-    hookManager: { ...realHookManager, uninstallHook() { throw new Error('injected uninstall failure'); } },
-  });
-  await assert.rejects(failingDelete.deleteProject(imported.projectId));
-  assert(registry.listIds().includes(imported.projectId), 'Hook uninstall failure must preserve registration');
-
-  const knowledgePath = imported.config.knowledgePath;
-  const deleted = await lifecycle.deleteProject(imported.projectId);
-  assert.strictEqual(deleted.removedKnowledge, false);
-  assert(fs.existsSync(knowledgePath), 'default delete must preserve external knowledge directory');
-  assert(!registry.listIds().includes(imported.projectId));
-
-  console.log('project-lifecycle-transaction-test PASS');
-})().catch(error => {
-  console.error(error.stack || error.message);
-  process.exitCode = 1;
-});
+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 { SettingsStore } = require('../lib/settings-store');
+const { ProjectRegistryStore } = require('../lib/project-registry-store');
+const { ProjectStore } = require('../lib/project-store');
+const { ProjectLifecycleService } = require('../lib/project-lifecycle-service');
+const realHookManager = 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`);
+  return String(result.stdout || '').trim();
+}
+
+function createRepo(root, name, withCommit = true) {
+  const repo = path.join(root, name);
+  fs.mkdirSync(repo, { recursive: true });
+  git(repo, ['init', '--initial-branch=main']);
+  git(repo, ['config', 'user.email', 'life@example.invalid']);
+  git(repo, ['config', 'user.name', 'Lifecycle Test']);
+  if (withCommit) {
+    fs.writeFileSync(path.join(repo, 'README.md'), `# ${name}\n`);
+    git(repo, ['add', 'README.md']);
+    git(repo, ['commit', '-m', 'initial']);
+  }
+  return repo;
+}
+
+(async () => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'pk-lifecycle-'));
+  const dataDir = path.join(root, 'data');
+  const knowledgeRoot = path.join(root, 'knowledge');
+  const layout = new StorageLayout({ dataDir });
+  const settings = new SettingsStore({ layout });
+  const registry = new ProjectRegistryStore({ layout });
+  const projects = new ProjectStore({ layout });
+  await settings.initialize({ knowledge: { rootPath: knowledgeRoot } });
+  await registry.initialize();
+  const lifecycle = new ProjectLifecycleService({
+    layout,
+    settingsStore: settings,
+    registryStore: registry,
+    projectStore: projects,
+    triggerScriptPath: TRIGGER,
+    bridgeAdapter: { async getHighWatermark() { return { status: 'captured', cursor: 73 }; } },
+  });
+
+  const repo = createRepo(root, 'repo-a');
+  const claude = path.join(repo, 'CLAUDE.md');
+  fs.writeFileSync(claude, '# user only\n');
+  const imported = await lifecycle.importProject({ localPath: repo, projectId: 'project-life-a', storageName: 'repo-a-stable' });
+  assert.strictEqual(imported.ok, true);
+  assert.strictEqual(imported.config.aiProfileId, null, 'import must not require an AI profile');
+  assert.strictEqual(imported.state.trackingStartCommit, git(repo, ['rev-parse', 'HEAD']));
+  assert.strictEqual(imported.state.conversationBaselineCursor, 73, 'import must freeze the current Bridge cursor as its conversation baseline');
+  assert.deepStrictEqual(fs.readdirSync(imported.config.knowledgePath), [], 'import must not create TODO knowledge files');
+  assert.strictEqual(fs.readFileSync(claude, 'utf8'), '# user only\n');
+  assert.strictEqual(realHookManager.readHookStatus({ repoPath: repo, projectId: imported.projectId }).installed, true);
+  await assert.rejects(lifecycle.importProject({ localPath: repo }), /already imported/);
+
+  const conflictRepo = createRepo(root, 'repo-conflict');
+  const conflictPath = path.join(knowledgeRoot, 'conflict-stable');
+  fs.mkdirSync(conflictPath, { recursive: true });
+  fs.writeFileSync(path.join(conflictPath, 'user.md'), 'do not overwrite');
+  await assert.rejects(lifecycle.importProject({ localPath: conflictRepo, projectId: 'project-conflict', storageName: 'conflict-stable' }), error => error.code === 'MIGRATION_TARGET_CONFLICT');
+  assert(!registry.listIds().includes('project-conflict'));
+  assert.strictEqual(fs.readFileSync(path.join(conflictPath, 'user.md'), 'utf8'), 'do not overwrite');
+
+  const failingRepo = createRepo(root, 'repo-failing');
+  const failingHooks = { ...realHookManager, installHook() { throw new Error('injected Hook failure'); } };
+  const failingLifecycle = new ProjectLifecycleService({ layout, settingsStore: settings, registryStore: registry, projectStore: projects, triggerScriptPath: TRIGGER, hookManager: failingHooks });
+  await assert.rejects(failingLifecycle.importProject({ localPath: failingRepo, projectId: 'project-failing', storageName: 'failing-stable' }));
+  assert(!registry.listIds().includes('project-failing'));
+  assert(!fs.existsSync(layout.getProjectMetadataDir('project-failing')));
+  assert(!fs.existsSync(path.join(knowledgeRoot, 'failing-stable')));
+
+  const emptyRepo = createRepo(root, 'repo-empty', false);
+  const empty = await lifecycle.importProject({ localPath: emptyRepo, projectId: 'project-empty', storageName: 'empty-stable' });
+  assert.strictEqual(empty.state.trackingMode, 'empty-repo');
+  assert.strictEqual(empty.state.trackingStartCommit, null);
+
+  const failingDelete = new ProjectLifecycleService({
+    layout, settingsStore: settings, registryStore: registry, projectStore: projects, triggerScriptPath: TRIGGER,
+    hookManager: { ...realHookManager, uninstallHook() { throw new Error('injected uninstall failure'); } },
+  });
+  await assert.rejects(failingDelete.deleteProject(imported.projectId));
+  assert(registry.listIds().includes(imported.projectId), 'Hook uninstall failure must preserve registration');
+
+  const knowledgePath = imported.config.knowledgePath;
+  const deleted = await lifecycle.deleteProject(imported.projectId);
+  assert.strictEqual(deleted.removedKnowledge, false);
+  assert(fs.existsSync(knowledgePath), 'default delete must preserve external knowledge directory');
+  assert(!registry.listIds().includes(imported.projectId));
+
+  console.log('project-lifecycle-transaction-test PASS');
+})().catch(error => {
+  console.error(error.stack || error.message);
+  process.exitCode = 1;
+});