@sanqianx/project-knowledge 4.6.1 → 4.8.0

package/_site/_test/p0-e2e-gate-test.js

@@ -1,347 +1,347 @@
-// _site/_test/p0-e2e-gate-test.js
-//
-// T09: P0 E2E gate. Four scenarios in one sequential run:
-//
-//   A. Fresh project: import -> hook -> commit -> reconciler -> Markdown
-//                     -> analyzed pointer advances.
-//   B. v4.1.22 legacy project: migrate (no re-import) -> hook -> commit
-//                              -> reconciler -> Markdown -> advances.
-//   C. Backend offline: stop -> commit -> restart -> startup recon
-//                       catches up.
-//   D. No conversation captured: commit with no Bridge cursor advance
-//                                still analyzes from Git evidence.
-
-const assert = require('assert');
-const fs = require('fs');
-const os = require('os');
-const path = require('path');
-const { spawnSync } = require('child_process');
-const { spawnServer } = require('./helpers/spawn-server');
-const { StorageLayout } = require('../lib/storage-layout');
-const { MigrationService } = require('../lib/migration-service');
-const { LEGACY_HOOK_MARKER } = require('../lib/hook-manager');
-
-const ROOT = path.resolve(__dirname, '..', '..');
-const BASE_PORT = 7970 + (process.pid % 200);
-
-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 makeRepo() {
-  const repo = fs.mkdtempSync(path.join(os.tmpdir(), 'pk-p0e2e-repo-' + process.pid + '-'));
-  git(repo, ['init', '-q', '-b', 'main']);
-  git(repo, ['config', 'user.email', 'p0e2e@example.local']);
-  git(repo, ['config', 'user.name', 'P0 E2E']);
-  fs.writeFileSync(path.join(repo, 'README.md'), '# p0\n');
-  git(repo, ['add', 'README.md']);
-  git(repo, ['commit', '-q', '-m', 'baseline']);
-  return repo;
-}
-
-async function serverFetch(server, url, init, timeoutMs = 15000) {
-  const controller = new AbortController();
-  const timer = setTimeout(() => controller.abort(), timeoutMs);
-  try {
-    const response = await fetch(url, { ...init, signal: controller.signal });
-    const text = await response.text();
-    return { status: response.status, body: text ? JSON.parse(text) : {} };
-  } finally {
-    clearTimeout(timer);
-  }
-}
-
-async function waitForState(server, projectId, predicate, label, timeoutMs = 60000) {
-  const deadline = Date.now() + timeoutMs;
-  let last;
-  while (Date.now() < deadline) {
-    try {
-      const r = await serverFetch(server, `${server.base}/api/projects/${projectId}`, undefined);
-      if (r.status === 200) {
-        last = r.body.project.state;
-        if (predicate(last)) return last;
-      }
-    } catch {}
-    await new Promise(resolve => setTimeout(resolve, 200));
-  }
-  throw new Error(`${label} timed out; last=${JSON.stringify(last)}`);
-}
-
-async function waitForHealth(server) {
-  for (let attempt = 0; attempt < 100; attempt += 1) {
-    try { const r = await serverFetch(server, `${server.base}/api/health`, undefined); if (r.body.ok) return; } catch {}
-    await new Promise(resolve => setTimeout(resolve, 100));
-  }
-  throw new Error('server did not start');
-}
-
-async function configureServer(server, dataDir) {
-  await serverFetch(server, `${server.base}/api/settings`, {
-    method: 'PATCH', headers: { 'content-type': 'application/json' },
-    body: JSON.stringify({ knowledge: { rootPath: path.join(dataDir, 'knowledge') } }),
-  });
-  await serverFetch(server, `${server.base}/api/ai-profiles`, {
-    method: 'PUT', headers: { 'content-type': 'application/json' },
-    body: JSON.stringify({
-      schema: 'ai-profiles/v1', defaultProfileId: 'fake',
-      profiles: [{ id: 'fake', name: 'Fake', enabled: true, vendor: 'anthropic', model: 'fake', apiKeyUpdate: { mode: 'replace', value: 'k' } }],
-    }),
-  });
-}
-
-async function killServer(server) {
-  if (!server || !server.child) return;
-  server.child.kill();
-  await new Promise(resolve => server.child.once('exit', resolve));
-}
-
-(async () => {
-  const dataDir = fs.mkdtempSync(path.join(os.tmpdir(), 'pk-p0e2e-data-' + process.pid + '-'));
-  const freshRepo = makeRepo();
-  const legacyRepo = makeRepo();
-  // Add a legacy v1 hook to legacyRepo so the migration path includes T03 case 2.
-  {
-    const gitDir = git(legacyRepo, ['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} — legacy\n` +
-      `node 'C:/legacy/_site/scripts/hook-trigger.js' >/dev/null 2>&1 || true\n` +
-      `exit 0\n`
-    ), { mode: 0o755 });
-  }
-  const legacyKbPath = path.join(dataDir, 'knowledge', 'legacy');
-  fs.mkdirSync(legacyKbPath, { recursive: true });
-  fs.writeFileSync(path.join(dataDir, 'projects.json'), JSON.stringify({
-    'legacy': {
-      schema: 'kb-project/v1',
-      displayName: 'Legacy',
-      localPath: legacyRepo,
-      gitPath: legacyRepo,
-      kbPath: legacyKbPath,
-      trackingStartCommit: git(legacyRepo, ['rev-parse', 'HEAD']),
-      lastAnalyzedCommit: git(legacyRepo, ['rev-parse', 'HEAD']),
-      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',
-  }));
-
-  // Scenario A — fresh project
-  const serverA = spawnServer({
-    root: ROOT, port: BASE_PORT, dataDir, tag: 'p0e2e-a',
-    extraEnv: { KB_AUTOMATION_FAKE_CLAUDE: '1', KB_EMBEDDING_FAKE: '1' },
-  });
-  serverA.base = `http://127.0.0.1:${BASE_PORT}`;
-  try {
-    await waitForHealth(serverA);
-    await configureServer(serverA, dataDir);
-    const importR = await serverFetch(serverA, `${serverA.base}/api/projects/import`, {
-      method: 'POST', headers: { 'content-type': 'application/json' },
-      body: JSON.stringify({ localPath: freshRepo, aiProfileId: 'fake', knowledgeLanguage: 'zh-CN' }),
-    });
-    assert.strictEqual(importR.status, 201, JSON.stringify(importR.body));
-    const projectA = importR.body.projectId;
-    const configA = importR.body.config;
-    // Verify hook installed
-    const hookPath = path.join(freshRepo, '.git', 'hooks', 'post-commit');
-    assert(fs.existsSync(hookPath), 'post-commit hook must be installed after import');
-    const hookBody = fs.readFileSync(hookPath, 'utf8');
-    assert(hookBody.includes('PROJECT-KNOWLEDGE-HOOK'), 'hook body must carry the v2 marker');
-    assert(hookBody.includes(projectA), 'hook body must reference the projectId');
-    assert(hookBody.includes('ELECTRON_RUN_AS_NODE=1'), 'T02 contract: hook body must prefix ELECTRON_RUN_AS_NODE=1');
-    // Commit a change
-    fs.writeFileSync(path.join(freshRepo, 'feature-a.txt'), 'feature a\n');
-    git(freshRepo, ['add', 'feature-a.txt']);
-    git(freshRepo, ['commit', '-q', '-m', 'scenario-a: feature a']);
-    const headA = git(freshRepo, ['rev-parse', 'HEAD']);
-    // Wait for reconciliation. If the live hook didn't fire (common in
-    // headless test environments), retry by POSTing the hook event
-    // ourselves — this is the same code path the hook runs.
-    let stateA = null;
-    for (let attempt = 0; attempt < 30; attempt += 1) {
-      try {
-        const r = await serverFetch(serverA, `${serverA.base}/api/projects/${projectA}`, undefined);
-        if (r.status === 200 && r.body.project.state.lastAnalyzedCommit === headA) {
-          stateA = r.body.project.state;
-          break;
-        }
-      } catch {}
-      await new Promise(resolve => setTimeout(resolve, 200));
-    }
-    if (!stateA) {
-      // Retry path: explicitly invoke /api/hooks/post-commit. The reconciler
-      // will run and advance lastAnalyzedCommit.
-      await serverFetch(serverA, `${serverA.base}/api/hooks/post-commit`, {
-        method: 'POST', headers: { 'content-type': 'application/json' },
-        body: JSON.stringify({
-          schema: 'hook-event/v2', projectId: projectA, repoRoot: freshRepo,
-          head: headA, branch: 'main', operationId: `op-scenario-a-${Date.now()}`,
-        }),
-      });
-      stateA = await waitForState(serverA, projectA, s => s.lastAnalyzedCommit === headA, 'scenario A reconciliation');
-    }
-    // Give the trailing reconcile work a chance to settle so the post-
-    // fix runSweep does not overwrite analysis.status with 'idle' between
-    // waitForState returning and the assertion reading the state.
-    await new Promise(resolve => setTimeout(resolve, 500));
-    const finalStateA = await (await serverFetch(serverA, `${serverA.base}/api/projects/${projectA}`, undefined)).body;
-    stateA = finalStateA.project.state;
-    assert.strictEqual(stateA.analysis.activeClaim, null, 'analysis.activeClaim must be null after promotion');
-    assert.strictEqual(stateA.analysis.status, 'state.advanced', 'analysis.status must be state.advanced');
-    assert.strictEqual(stateA.trackingStartCommit, stateA.lastAnalyzedCommit === headA ? stateA.trackingStartCommit : null);
-    // Verify Markdown knowledge
-    const mdPath = path.join(configA.knowledgePath, 'changes', `${headA.slice(0, 12)}.md`);
-    assert(fs.existsSync(mdPath), `knowledge Markdown must exist at ${mdPath}`);
-  } finally {
-    await killServer(serverA);
-  }
-
-  // Scenario B — v4.1.22 legacy project (migrate, no re-import)
-  // We restart with the SAME dataDir so the migration service picks up the
-  // legacy projects.json. The server's startup will run MigrationService +
-  // migrateManagedHooks.
-  const serverB = spawnServer({
-    root: ROOT, port: BASE_PORT, dataDir, tag: 'p0e2e-b',
-    extraEnv: { KB_AUTOMATION_FAKE_CLAUDE: '1', KB_EMBEDDING_FAKE: '1' },
-  });
-  serverB.base = `http://127.0.0.1:${BASE_PORT}`;
-  try {
-    await waitForHealth(serverB);
-    await configureServer(serverB, dataDir);
-    const stateList = await serverFetch(serverB, `${serverB.base}/api/state`, undefined);
-    assert.strictEqual(stateList.status, 200);
-    const legacyProject = stateList.body.projects.find(p => p.config.displayName === 'Legacy');
-    assert(legacyProject, 'migrated Legacy project must appear in /api/state without a re-import call');
-    const projectB = legacyProject.projectId;
-    // Verify hook was migrated from v1 to v2
-    const hookPath = path.join(legacyRepo, '.git', 'hooks', 'post-commit');
-    const hookBody = fs.readFileSync(hookPath, 'utf8');
-    assert(hookBody.includes('PROJECT-KNOWLEDGE-HOOK'), 'migrated hook must carry v2 marker');
-    assert(!hookBody.includes(LEGACY_HOOK_MARKER), 'migrated hook must NOT carry the legacy v1 marker');
-    assert(hookBody.includes('ELECTRON_RUN_AS_NODE=1'), 'T02 contract applies to migrated hooks too');
-    // Commit a change
-    fs.writeFileSync(path.join(legacyRepo, 'feature-b.txt'), 'feature b\n');
-    git(legacyRepo, ['add', 'feature-b.txt']);
-    git(legacyRepo, ['commit', '-q', '-m', 'scenario-b: feature b']);
-    const headB = git(legacyRepo, ['rev-parse', 'HEAD']);
-    let stateB = null;
-    for (let attempt = 0; attempt < 30; attempt += 1) {
-      try {
-        const r = await serverFetch(serverB, `${serverB.base}/api/projects/${projectB}`, undefined);
-        if (r.status === 200 && r.body.project.state.lastAnalyzedCommit === headB) {
-          stateB = r.body.project.state;
-          break;
-        }
-      } catch {}
-      await new Promise(resolve => setTimeout(resolve, 200));
-    }
-    if (!stateB) {
-      await serverFetch(serverB, `${serverB.base}/api/hooks/post-commit`, {
-        method: 'POST', headers: { 'content-type': 'application/json' },
-        body: JSON.stringify({
-          schema: 'hook-event/v2', projectId: projectB, repoRoot: legacyRepo,
-          head: headB, branch: 'main', operationId: `op-scenario-b-${Date.now()}`,
-        }),
-      });
-      stateB = await waitForState(serverB, projectB, s => s.lastAnalyzedCommit === headB, 'scenario B reconciliation');
-    }
-    assert.strictEqual(stateB.analysis.activeClaim, null);
-    const mdPath = path.join(legacyProject.config.knowledgePath, 'changes', `${headB.slice(0, 12)}.md`);
-    assert(fs.existsSync(mdPath), `knowledge Markdown must exist at ${mdPath}`);
-  } finally {
-    await killServer(serverB);
-  }
-
-  // Scenario C — backend offline, then restart. Restart must preserve facts
-  // but must not infer this missed commit for knowledge analysis.
-  fs.writeFileSync(path.join(legacyRepo, 'feature-c.txt'), 'feature c (offline)\n');
-  git(legacyRepo, ['add', 'feature-c.txt']);
-  git(legacyRepo, ['commit', '-q', '-m', 'scenario-c: offline commit']);
-  const headC = git(legacyRepo, ['rev-parse', 'HEAD']);
-  const serverC = spawnServer({
-    root: ROOT, port: BASE_PORT, dataDir, tag: 'p0e2e-c',
-    extraEnv: { KB_AUTOMATION_FAKE_CLAUDE: '1', KB_EMBEDDING_FAKE: '1' },
-  });
-  serverC.base = `http://127.0.0.1:${BASE_PORT}`;
-  try {
-    await waitForHealth(serverC);
-    const projectIdC = (await serverFetch(serverC, `${serverC.base}/api/state`, undefined))
-      .body.projects.find(p => p.config.displayName === 'Legacy').projectId;
-    await new Promise(resolve => setTimeout(resolve, 500));
-    const stateC = (await serverFetch(serverC, `${serverC.base}/api/projects/${projectIdC}`, undefined)).body.project.state;
-    assert.notStrictEqual(stateC.lastAnalyzedCommit, headC, 'startup must not analyze an offline commit');
-    const legacyKbC = (await serverFetch(serverC, `${serverC.base}/api/state`, undefined))
-      .body.projects.find(p => p.config.displayName === 'Legacy').config.knowledgePath;
-    assert.strictEqual(fs.existsSync(path.join(legacyKbC, 'changes', `${headC.slice(0, 12)}.md`)), false);
-  } finally {
-    await killServer(serverC);
-  }
-
-  // Scenario D — no conversation captured. With KB_AUTOMATION_FAKE_CLAUDE
-  // the analyzer uses the fake result path that does not depend on the
-  // Bridge cursor advancing; we verify the same flow still produces a
-  // Markdown file from Git evidence alone.
-  fs.writeFileSync(path.join(legacyRepo, 'feature-d.txt'), 'feature d (no conversation)\n');
-  git(legacyRepo, ['add', 'feature-d.txt']);
-  git(legacyRepo, ['commit', '-q', '-m', 'scenario-d: no conversation']);
-  const headD = git(legacyRepo, ['rev-parse', 'HEAD']);
-  const serverD = spawnServer({
-    root: ROOT, port: BASE_PORT, dataDir, tag: 'p0e2e-d',
-    extraEnv: { KB_AUTOMATION_FAKE_CLAUDE: '1', KB_EMBEDDING_FAKE: '1' },
-  });
-  serverD.base = `http://127.0.0.1:${BASE_PORT}`;
-  try {
-    await waitForHealth(serverD);
-    const projectId = (await serverFetch(serverD, `${serverD.base}/api/state`, undefined))
-      .body.projects.find(p => p.config.displayName === 'Legacy').projectId;
-    let stateD = null;
-    for (let attempt = 0; attempt < 30; attempt += 1) {
-      try {
-        const r = await serverFetch(serverD, `${serverD.base}/api/projects/${projectId}`, undefined);
-        if (r.status === 200 && r.body.project.state.lastAnalyzedCommit === headD) {
-          stateD = r.body.project.state;
-          break;
-        }
-      } catch {}
-      await new Promise(resolve => setTimeout(resolve, 200));
-    }
-    if (!stateD) {
-      await serverFetch(serverD, `${serverD.base}/api/hooks/post-commit`, {
-        method: 'POST', headers: { 'content-type': 'application/json' },
-        body: JSON.stringify({
-          schema: 'hook-event/v2', projectId, repoRoot: legacyRepo,
-          head: headD, branch: 'main', operationId: `op-scenario-d-${Date.now()}`,
-        }),
-      });
-      stateD = await waitForState(serverD, projectId, s => s.lastAnalyzedCommit === headD, 'scenario D reconciliation without conversation');
-    }
-    const legacyKb = (await serverFetch(serverD, `${serverD.base}/api/state`, undefined))
-      .body.projects.find(p => p.config.displayName === 'Legacy').config.knowledgePath;
-    const mdPath = path.join(legacyKb, 'changes', `${headD.slice(0, 12)}.md`);
-    assert(fs.existsSync(mdPath), `scenario D must still produce Markdown at ${mdPath}`);
-  } finally {
-    await killServer(serverD);
-    fs.rmSync(dataDir, { recursive: true, force: true });
-    fs.rmSync(freshRepo, { recursive: true, force: true });
-    fs.rmSync(legacyRepo, { recursive: true, force: true });
-  }
-  console.log('p0-e2e-gate-test PASS');
-})().catch(error => {
-  console.error(error.stack || error.message);
-  process.exit(1);
-});
+// _site/_test/p0-e2e-gate-test.js
+//
+// T09: P0 E2E gate. Four scenarios in one sequential run:
+//
+//   A. Fresh project: import -> hook -> commit -> reconciler -> Markdown
+//                     -> analyzed pointer advances.
+//   B. v4.1.22 legacy project: migrate (no re-import) -> hook -> commit
+//                              -> reconciler -> Markdown -> advances.
+//   C. Backend offline: stop -> commit -> restart -> startup recon
+//                       catches up.
+//   D. No conversation captured: commit with no Bridge cursor advance
+//                                still analyzes from Git evidence.
+
+const assert = require('assert');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { spawnSync } = require('child_process');
+const { spawnServer } = require('./helpers/spawn-server');
+const { StorageLayout } = require('../lib/storage-layout');
+const { MigrationService } = require('../lib/migration-service');
+const { LEGACY_HOOK_MARKER } = require('../lib/hook-manager');
+
+const ROOT = path.resolve(__dirname, '..', '..');
+const BASE_PORT = 7970 + (process.pid % 200);
+
+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 makeRepo() {
+  const repo = fs.mkdtempSync(path.join(os.tmpdir(), 'pk-p0e2e-repo-' + process.pid + '-'));
+  git(repo, ['init', '-q', '-b', 'main']);
+  git(repo, ['config', 'user.email', 'p0e2e@example.local']);
+  git(repo, ['config', 'user.name', 'P0 E2E']);
+  fs.writeFileSync(path.join(repo, 'README.md'), '# p0\n');
+  git(repo, ['add', 'README.md']);
+  git(repo, ['commit', '-q', '-m', 'baseline']);
+  return repo;
+}
+
+async function serverFetch(server, url, init, timeoutMs = 15000) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const response = await fetch(url, { ...init, signal: controller.signal });
+    const text = await response.text();
+    return { status: response.status, body: text ? JSON.parse(text) : {} };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+async function waitForState(server, projectId, predicate, label, timeoutMs = 60000) {
+  const deadline = Date.now() + timeoutMs;
+  let last;
+  while (Date.now() < deadline) {
+    try {
+      const r = await serverFetch(server, `${server.base}/api/projects/${projectId}`, undefined);
+      if (r.status === 200) {
+        last = r.body.project.state;
+        if (predicate(last)) return last;
+      }
+    } catch {}
+    await new Promise(resolve => setTimeout(resolve, 200));
+  }
+  throw new Error(`${label} timed out; last=${JSON.stringify(last)}`);
+}
+
+async function waitForHealth(server) {
+  for (let attempt = 0; attempt < 100; attempt += 1) {
+    try { const r = await serverFetch(server, `${server.base}/api/health`, undefined); if (r.body.ok) return; } catch {}
+    await new Promise(resolve => setTimeout(resolve, 100));
+  }
+  throw new Error('server did not start');
+}
+
+async function configureServer(server, dataDir) {
+  await serverFetch(server, `${server.base}/api/settings`, {
+    method: 'PATCH', headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({ knowledge: { rootPath: path.join(dataDir, 'knowledge') } }),
+  });
+  await serverFetch(server, `${server.base}/api/ai-profiles`, {
+    method: 'PUT', headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({
+      schema: 'ai-profiles/v1', defaultProfileId: 'fake',
+      profiles: [{ id: 'fake', name: 'Fake', enabled: true, vendor: 'anthropic', model: 'fake', apiKeyUpdate: { mode: 'replace', value: 'k' } }],
+    }),
+  });
+}
+
+async function killServer(server) {
+  if (!server || !server.child) return;
+  server.child.kill();
+  await new Promise(resolve => server.child.once('exit', resolve));
+}
+
+(async () => {
+  const dataDir = fs.mkdtempSync(path.join(os.tmpdir(), 'pk-p0e2e-data-' + process.pid + '-'));
+  const freshRepo = makeRepo();
+  const legacyRepo = makeRepo();
+  // Add a legacy v1 hook to legacyRepo so the migration path includes T03 case 2.
+  {
+    const gitDir = git(legacyRepo, ['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} — legacy\n` +
+      `node 'C:/legacy/_site/scripts/hook-trigger.js' >/dev/null 2>&1 || true\n` +
+      `exit 0\n`
+    ), { mode: 0o755 });
+  }
+  const legacyKbPath = path.join(dataDir, 'knowledge', 'legacy');
+  fs.mkdirSync(legacyKbPath, { recursive: true });
+  fs.writeFileSync(path.join(dataDir, 'projects.json'), JSON.stringify({
+    'legacy': {
+      schema: 'kb-project/v1',
+      displayName: 'Legacy',
+      localPath: legacyRepo,
+      gitPath: legacyRepo,
+      kbPath: legacyKbPath,
+      trackingStartCommit: git(legacyRepo, ['rev-parse', 'HEAD']),
+      lastAnalyzedCommit: git(legacyRepo, ['rev-parse', 'HEAD']),
+      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',
+  }));
+
+  // Scenario A — fresh project
+  const serverA = spawnServer({
+    root: ROOT, port: BASE_PORT, dataDir, tag: 'p0e2e-a',
+    extraEnv: { KB_AUTOMATION_FAKE_CLAUDE: '1', KB_EMBEDDING_FAKE: '1' },
+  });
+  serverA.base = `http://127.0.0.1:${BASE_PORT}`;
+  try {
+    await waitForHealth(serverA);
+    await configureServer(serverA, dataDir);
+    const importR = await serverFetch(serverA, `${serverA.base}/api/projects/import`, {
+      method: 'POST', headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ localPath: freshRepo, aiProfileId: 'fake', knowledgeLanguage: 'zh-CN' }),
+    });
+    assert.strictEqual(importR.status, 201, JSON.stringify(importR.body));
+    const projectA = importR.body.projectId;
+    const configA = importR.body.config;
+    // Verify hook installed
+    const hookPath = path.join(freshRepo, '.git', 'hooks', 'post-commit');
+    assert(fs.existsSync(hookPath), 'post-commit hook must be installed after import');
+    const hookBody = fs.readFileSync(hookPath, 'utf8');
+    assert(hookBody.includes('PROJECT-KNOWLEDGE-HOOK'), 'hook body must carry the v2 marker');
+    assert(hookBody.includes(projectA), 'hook body must reference the projectId');
+    assert(hookBody.includes('ELECTRON_RUN_AS_NODE=1'), 'T02 contract: hook body must prefix ELECTRON_RUN_AS_NODE=1');
+    // Commit a change
+    fs.writeFileSync(path.join(freshRepo, 'feature-a.txt'), 'feature a\n');
+    git(freshRepo, ['add', 'feature-a.txt']);
+    git(freshRepo, ['commit', '-q', '-m', 'scenario-a: feature a']);
+    const headA = git(freshRepo, ['rev-parse', 'HEAD']);
+    // Wait for reconciliation. If the live hook didn't fire (common in
+    // headless test environments), retry by POSTing the hook event
+    // ourselves — this is the same code path the hook runs.
+    let stateA = null;
+    for (let attempt = 0; attempt < 30; attempt += 1) {
+      try {
+        const r = await serverFetch(serverA, `${serverA.base}/api/projects/${projectA}`, undefined);
+        if (r.status === 200 && r.body.project.state.lastAnalyzedCommit === headA) {
+          stateA = r.body.project.state;
+          break;
+        }
+      } catch {}
+      await new Promise(resolve => setTimeout(resolve, 200));
+    }
+    if (!stateA) {
+      // Retry path: explicitly invoke /api/hooks/post-commit. The reconciler
+      // will run and advance lastAnalyzedCommit.
+      await serverFetch(serverA, `${serverA.base}/api/hooks/post-commit`, {
+        method: 'POST', headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({
+          schema: 'hook-event/v2', projectId: projectA, repoRoot: freshRepo,
+          head: headA, branch: 'main', operationId: `op-scenario-a-${Date.now()}`,
+        }),
+      });
+      stateA = await waitForState(serverA, projectA, s => s.lastAnalyzedCommit === headA, 'scenario A reconciliation');
+    }
+    // Give the trailing reconcile work a chance to settle so the post-
+    // fix runSweep does not overwrite analysis.status with 'idle' between
+    // waitForState returning and the assertion reading the state.
+    await new Promise(resolve => setTimeout(resolve, 500));
+    const finalStateA = await (await serverFetch(serverA, `${serverA.base}/api/projects/${projectA}`, undefined)).body;
+    stateA = finalStateA.project.state;
+    assert.strictEqual(stateA.analysis.activeClaim, null, 'analysis.activeClaim must be null after promotion');
+    assert.strictEqual(stateA.analysis.status, 'state.advanced', 'analysis.status must be state.advanced');
+    assert.strictEqual(stateA.trackingStartCommit, stateA.lastAnalyzedCommit === headA ? stateA.trackingStartCommit : null);
+    // Verify Markdown knowledge
+    const mdPath = path.join(configA.knowledgePath, 'changes', `${headA.slice(0, 12)}.md`);
+    assert(fs.existsSync(mdPath), `knowledge Markdown must exist at ${mdPath}`);
+  } finally {
+    await killServer(serverA);
+  }
+
+  // Scenario B — v4.1.22 legacy project (migrate, no re-import)
+  // We restart with the SAME dataDir so the migration service picks up the
+  // legacy projects.json. The server's startup will run MigrationService +
+  // migrateManagedHooks.
+  const serverB = spawnServer({
+    root: ROOT, port: BASE_PORT, dataDir, tag: 'p0e2e-b',
+    extraEnv: { KB_AUTOMATION_FAKE_CLAUDE: '1', KB_EMBEDDING_FAKE: '1' },
+  });
+  serverB.base = `http://127.0.0.1:${BASE_PORT}`;
+  try {
+    await waitForHealth(serverB);
+    await configureServer(serverB, dataDir);
+    const stateList = await serverFetch(serverB, `${serverB.base}/api/state`, undefined);
+    assert.strictEqual(stateList.status, 200);
+    const legacyProject = stateList.body.projects.find(p => p.config.displayName === 'Legacy');
+    assert(legacyProject, 'migrated Legacy project must appear in /api/state without a re-import call');
+    const projectB = legacyProject.projectId;
+    // Verify hook was migrated from v1 to v2
+    const hookPath = path.join(legacyRepo, '.git', 'hooks', 'post-commit');
+    const hookBody = fs.readFileSync(hookPath, 'utf8');
+    assert(hookBody.includes('PROJECT-KNOWLEDGE-HOOK'), 'migrated hook must carry v2 marker');
+    assert(!hookBody.includes(LEGACY_HOOK_MARKER), 'migrated hook must NOT carry the legacy v1 marker');
+    assert(hookBody.includes('ELECTRON_RUN_AS_NODE=1'), 'T02 contract applies to migrated hooks too');
+    // Commit a change
+    fs.writeFileSync(path.join(legacyRepo, 'feature-b.txt'), 'feature b\n');
+    git(legacyRepo, ['add', 'feature-b.txt']);
+    git(legacyRepo, ['commit', '-q', '-m', 'scenario-b: feature b']);
+    const headB = git(legacyRepo, ['rev-parse', 'HEAD']);
+    let stateB = null;
+    for (let attempt = 0; attempt < 30; attempt += 1) {
+      try {
+        const r = await serverFetch(serverB, `${serverB.base}/api/projects/${projectB}`, undefined);
+        if (r.status === 200 && r.body.project.state.lastAnalyzedCommit === headB) {
+          stateB = r.body.project.state;
+          break;
+        }
+      } catch {}
+      await new Promise(resolve => setTimeout(resolve, 200));
+    }
+    if (!stateB) {
+      await serverFetch(serverB, `${serverB.base}/api/hooks/post-commit`, {
+        method: 'POST', headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({
+          schema: 'hook-event/v2', projectId: projectB, repoRoot: legacyRepo,
+          head: headB, branch: 'main', operationId: `op-scenario-b-${Date.now()}`,
+        }),
+      });
+      stateB = await waitForState(serverB, projectB, s => s.lastAnalyzedCommit === headB, 'scenario B reconciliation');
+    }
+    assert.strictEqual(stateB.analysis.activeClaim, null);
+    const mdPath = path.join(legacyProject.config.knowledgePath, 'changes', `${headB.slice(0, 12)}.md`);
+    assert(fs.existsSync(mdPath), `knowledge Markdown must exist at ${mdPath}`);
+  } finally {
+    await killServer(serverB);
+  }
+
+  // Scenario C — backend offline, then restart. Restart must preserve facts
+  // but must not infer this missed commit for knowledge analysis.
+  fs.writeFileSync(path.join(legacyRepo, 'feature-c.txt'), 'feature c (offline)\n');
+  git(legacyRepo, ['add', 'feature-c.txt']);
+  git(legacyRepo, ['commit', '-q', '-m', 'scenario-c: offline commit']);
+  const headC = git(legacyRepo, ['rev-parse', 'HEAD']);
+  const serverC = spawnServer({
+    root: ROOT, port: BASE_PORT, dataDir, tag: 'p0e2e-c',
+    extraEnv: { KB_AUTOMATION_FAKE_CLAUDE: '1', KB_EMBEDDING_FAKE: '1' },
+  });
+  serverC.base = `http://127.0.0.1:${BASE_PORT}`;
+  try {
+    await waitForHealth(serverC);
+    const projectIdC = (await serverFetch(serverC, `${serverC.base}/api/state`, undefined))
+      .body.projects.find(p => p.config.displayName === 'Legacy').projectId;
+    await new Promise(resolve => setTimeout(resolve, 500));
+    const stateC = (await serverFetch(serverC, `${serverC.base}/api/projects/${projectIdC}`, undefined)).body.project.state;
+    assert.notStrictEqual(stateC.lastAnalyzedCommit, headC, 'startup must not analyze an offline commit');
+    const legacyKbC = (await serverFetch(serverC, `${serverC.base}/api/state`, undefined))
+      .body.projects.find(p => p.config.displayName === 'Legacy').config.knowledgePath;
+    assert.strictEqual(fs.existsSync(path.join(legacyKbC, 'changes', `${headC.slice(0, 12)}.md`)), false);
+  } finally {
+    await killServer(serverC);
+  }
+
+  // Scenario D — no conversation captured. With KB_AUTOMATION_FAKE_CLAUDE
+  // the analyzer uses the fake result path that does not depend on the
+  // Bridge cursor advancing; we verify the same flow still produces a
+  // Markdown file from Git evidence alone.
+  fs.writeFileSync(path.join(legacyRepo, 'feature-d.txt'), 'feature d (no conversation)\n');
+  git(legacyRepo, ['add', 'feature-d.txt']);
+  git(legacyRepo, ['commit', '-q', '-m', 'scenario-d: no conversation']);
+  const headD = git(legacyRepo, ['rev-parse', 'HEAD']);
+  const serverD = spawnServer({
+    root: ROOT, port: BASE_PORT, dataDir, tag: 'p0e2e-d',
+    extraEnv: { KB_AUTOMATION_FAKE_CLAUDE: '1', KB_EMBEDDING_FAKE: '1' },
+  });
+  serverD.base = `http://127.0.0.1:${BASE_PORT}`;
+  try {
+    await waitForHealth(serverD);
+    const projectId = (await serverFetch(serverD, `${serverD.base}/api/state`, undefined))
+      .body.projects.find(p => p.config.displayName === 'Legacy').projectId;
+    let stateD = null;
+    for (let attempt = 0; attempt < 30; attempt += 1) {
+      try {
+        const r = await serverFetch(serverD, `${serverD.base}/api/projects/${projectId}`, undefined);
+        if (r.status === 200 && r.body.project.state.lastAnalyzedCommit === headD) {
+          stateD = r.body.project.state;
+          break;
+        }
+      } catch {}
+      await new Promise(resolve => setTimeout(resolve, 200));
+    }
+    if (!stateD) {
+      await serverFetch(serverD, `${serverD.base}/api/hooks/post-commit`, {
+        method: 'POST', headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({
+          schema: 'hook-event/v2', projectId, repoRoot: legacyRepo,
+          head: headD, branch: 'main', operationId: `op-scenario-d-${Date.now()}`,
+        }),
+      });
+      stateD = await waitForState(serverD, projectId, s => s.lastAnalyzedCommit === headD, 'scenario D reconciliation without conversation');
+    }
+    const legacyKb = (await serverFetch(serverD, `${serverD.base}/api/state`, undefined))
+      .body.projects.find(p => p.config.displayName === 'Legacy').config.knowledgePath;
+    const mdPath = path.join(legacyKb, 'changes', `${headD.slice(0, 12)}.md`);
+    assert(fs.existsSync(mdPath), `scenario D must still produce Markdown at ${mdPath}`);
+  } finally {
+    await killServer(serverD);
+    fs.rmSync(dataDir, { recursive: true, force: true });
+    fs.rmSync(freshRepo, { recursive: true, force: true });
+    fs.rmSync(legacyRepo, { recursive: true, force: true });
+  }
+  console.log('p0-e2e-gate-test PASS');
+})().catch(error => {
+  console.error(error.stack || error.message);
+  process.exit(1);
+});