@sanqianx/project-knowledge 4.6.1

package/_site/_test/task15-20-ui-flow-test.js

@@ -0,0 +1,148 @@
+const assert = require('assert');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { spawnServer } = require('./helpers/spawn-server');
+const { findChrome } = require('./helpers/find-chrome');
+const { launchCdpBrowser, requestJson, waitFor } = require('./helpers/cdp-browser');
+const { createLoggingUiFixture } = require('./helpers/logging-ui-fixture');
+
+const ROOT = path.resolve(__dirname, '..', '..');
+const sitePort = 8200 + (process.pid % 250);
+const profileDir = path.join(os.tmpdir(), 'pk-ui-flow-profile-' + process.pid);
+const artifactDir = path.join(ROOT, '.agent-state', 'ui-v13');
+
+async function capture(browser, name) {
+  const filePath = path.join(artifactDir, name + '.png');
+  await browser.screenshot(filePath);
+  assert(fs.statSync(filePath).size > 10000, `screenshot ${name} must contain rendered UI`);
+}
+
+(async () => {
+  const fixture = await createLoggingUiFixture({ totalLogs: 240 });
+  const server = spawnServer({ root: ROOT, port: sitePort, dataDir: fixture.dataDir, tag: 'ui-flow-v13', stdio: 'ignore' });
+  let browser;
+  try {
+    await waitFor(() => requestJson(`http://127.0.0.1:${sitePort}/api/health`).then(body => body.ok), 'flow server', 20000);
+    browser = await launchCdpBrowser({ chrome: findChrome(), profileDir, url: `http://127.0.0.1:${sitePort}/`, width: 1366, height: 768 });
+    await waitFor(() => browser.evaluate('window.__PK_APP__ && window.__PK_APP__.getState().projects === 1'), 'full shell', 20000);
+
+    await browser.setViewport(1920, 1080);
+    await capture(browser, '01-main-shell-1920-light');
+    // T2: 聊天由内嵌终端提供 —— 壳断言嵌入视图与 iframe 挂载
+    assert.strictEqual(await browser.evaluate("document.getElementById('view-terminal').classList.contains('active')"), true);
+    assert.strictEqual(await browser.evaluate("document.getElementById('fr-5760').src.includes('/agent-terminal/')"), true);
+    await capture(browser, '02-terminal-embed-1920-light');
+
+    await browser.evaluate("document.querySelector('[data-go=\"import\"]').click()");
+    assert.strictEqual(await browser.evaluate("document.getElementById('import-path').required"), true);
+    assert.strictEqual(await browser.evaluate("document.querySelectorAll('#import-knowledge-path').length"), 1, 'Import takes an explicit knowledge address (T3.2)');
+    await capture(browser, '03-import-1920-light');
+
+    // 开发对话已迁移到 ai-coding-event-bridge 模块：设置抽屉只有日志一节
+    await browser.evaluate("window.__PK_APP__.openSettings()");
+    await waitFor(() => browser.evaluate("document.getElementById('settings-logs').classList.contains('active')"), 'logs settings');
+    assert.strictEqual(await browser.evaluate("document.querySelectorAll('[data-settings]').length"), 1, 'settings drawer must only expose logs (conversation moved to event-bridge module)');
+    await capture(browser, '04-settings-logs-1920-light');
+
+    await browser.setViewport(1366, 768);
+    await browser.evaluate("window.__PK_APP__.showSettings('logs')");
+    // 等 DOM 实际渲染出全部行（loadLogs 先清空再异步渲染，只看内存状态会撞上清空间隙）
+    await waitFor(() => browser.evaluate('window.__PK_APP__.getState().logCount >= 240 && document.querySelectorAll(".record-row").length >= 240'), '200+ log rows', 20000);
+    const auditLogs = () => browser.evaluate(`(() => {
+      const rows = [...document.querySelectorAll('.record-row')];
+      const drawer = document.getElementById('settings-drawer');
+      const list = document.getElementById('record-list');
+      const card = document.querySelector('.logs-card').getBoundingClientRect();
+      const content = document.querySelector('.settings-content').getBoundingClientRect();
+      const overlaps = rows.filter(row => {
+        const body = row.querySelector('.record-main').getBoundingClientRect();
+        const time = row.querySelector('.record-time').getBoundingClientRect();
+        return body.right + 8 > time.left;
+      }).length;
+      const scrollables = [...drawer.querySelectorAll('*')].filter(node => {
+        const style = getComputedStyle(node);
+        return /(auto|scroll)/.test(style.overflowY) && node.scrollHeight > node.clientHeight + 1;
+      }).map(node => node.id || node.className);
+      const colorParts = level => {
+        const row = document.querySelector('.record-entry[data-level=' + level + '] .record-row');
+        return row ? [row, row.querySelector('.record-title'), row.querySelector('.record-meta'), row.querySelector('.record-time')].map(node => getComputedStyle(node).color) : [];
+      };
+      return {
+        rows: rows.length,
+        overlaps,
+        scrollables,
+        maxHeight: getComputedStyle(list).maxHeight,
+        listOverflow: getComputedStyle(list).overflowY,
+        cardBottomGap: Math.round(content.bottom - card.bottom),
+        warnColors: colorParts('warn'),
+        errorColors: colorParts('error'),
+        severityMarks: document.querySelectorAll('.record-entry svg, .record-entry img, .record-entry .dot, .record-entry .severity').length,
+        pageOverflow: document.body.scrollWidth > document.documentElement.clientWidth + 1,
+        recordHeight: document.querySelector('.record-shell').getBoundingClientRect().height,
+      };
+    })()`);
+    const desktopLogs = await auditLogs();
+    assert(desktopLogs.rows >= 240);
+    assert.strictEqual(desktopLogs.overlaps, 0, 'message/meta must never overlap the fixed time column');
+    assert.deepStrictEqual(desktopLogs.scrollables, ['record-list'], 'record-list must be the only vertical scroller in the active logs drawer');
+    assert(desktopLogs.maxHeight === 'none');
+    assert.strictEqual(desktopLogs.listOverflow, 'auto');
+    assert(desktopLogs.cardBottomGap <= 23, 'logs card must reach the settings content bottom');
+    assert(desktopLogs.warnColors.length === 4 && new Set(desktopLogs.warnColors).size === 1, 'warn message/meta/time must share whole-row color');
+    assert(desktopLogs.errorColors.length === 4 && new Set(desktopLogs.errorColors).size === 1, 'error message/meta/time must share whole-row color');
+    assert.strictEqual(desktopLogs.severityMarks, 0);
+    assert.strictEqual(desktopLogs.pageOverflow, false);
+
+    await browser.evaluate("document.querySelector('.record-entry[data-level=error] .record-row').click()");
+    assert.strictEqual(await browser.evaluate("document.querySelector('.record-entry[data-level=error]').classList.contains('open')"), true);
+    await capture(browser, '07-logs-1366x768-expanded-light');
+    await browser.evaluate("document.getElementById('record-list').scrollTop = 0");
+    await browser.evaluate("fetch('/api/health?ui-sse=' + Date.now()).then(response => response.json())");
+    await waitFor(() => browser.evaluate('window.__PK_APP__.getState().newLogs > 0'), 'new-record banner', 20000);
+    assert.strictEqual(await browser.evaluate("document.getElementById('new-records').hidden"), false);
+    assert.strictEqual(await browser.evaluate("document.getElementById('record-list').scrollTop"), 0, 'SSE append must not steal a scrolled-up position');
+    await capture(browser, '08-logs-scrolled-new-banner-light');
+    await browser.evaluate("document.getElementById('new-records').click()");
+    await waitFor(() => browser.evaluate("window.__PK_APP__.getState().newLogs === 0 && document.getElementById('record-list').scrollHeight - document.getElementById('record-list').scrollTop - document.getElementById('record-list').clientHeight < 2"), 'return to log bottom');
+
+    await browser.setViewport(1920, 1080);
+    const tallLogs = await auditLogs();
+    assert(tallLogs.recordHeight > desktopLogs.recordHeight + 200, 'record shell must grow with viewport height');
+    await browser.evaluate("document.getElementById('theme-button').click()");
+    assert.strictEqual(await browser.evaluate('document.documentElement.dataset.theme'), 'dark');
+    await capture(browser, '09-logs-1920x1080-dark');
+
+    await browser.setViewport(820, 900);
+    const narrowLogs = await auditLogs();
+    assert.strictEqual(narrowLogs.overlaps, 0);
+    assert.strictEqual(narrowLogs.pageOverflow, false);
+    await capture(browser, '10-logs-820x900-dark');
+
+    await browser.setViewport(390, 844);
+    const mobileLogs = await auditLogs();
+    assert.strictEqual(mobileLogs.overlaps, 0);
+    assert.strictEqual(mobileLogs.pageOverflow, false);
+    assert.strictEqual(await browser.evaluate("getComputedStyle(document.querySelector('.settings-nav')).flexDirection"), 'row');
+    await capture(browser, '11-mobile-logs-390x844-dark');
+
+    await browser.evaluate(`(() => {
+      window.__PK_APP__.showSettings('logs');
+      const card = document.querySelector('#project-list .project-card');
+      card.dispatchEvent(new MouseEvent('contextmenu', { bubbles: true, cancelable: true, clientX: 100, clientY: 300 }));
+    })()`);
+    await waitFor(() => browser.evaluate("document.getElementById('context-menu').classList.contains('show')"), 'mobile context menu');
+    await browser.evaluate("document.getElementById('remove-project').click()");
+    await waitFor(() => browser.evaluate("document.getElementById('delete-dialog').open"), 'project delete modal');
+    await capture(browser, '13-mobile-delete-modal-dark');
+    assert.strictEqual(browser.exceptions.length, 0, 'browser runtime exceptions: ' + JSON.stringify(browser.exceptions));
+    console.log('task15-20 UI flow test PASS');
+  } finally {
+    if (browser) await browser.close();
+    await server.cleanup();
+    fixture.cleanup();
+  }
+})().catch(error => {
+  console.error(error.stack || error.message);
+  process.exitCode = 1;
+});

package/_site/_test/team-knowledge-store-sparse-checkout-test.js

@@ -0,0 +1,196 @@
+// Tests for sparse-checkout automation in github-team-store.js.
+// Style mirrors team-knowledge-store-test.js (IIFE + assert()).
+//
+// Three scenarios:
+//   1. New sparse clone — checkoutStore({ subdir, partialClone }) clones with
+//      --filter=blob:none --sparse --no-checkout, applies cone, and materializes
+//      only the requested subdirectory.
+//   2. Re-clone / switch — calling checkoutStore twice on the same local path
+//      re-applies sparse-checkout cone (idempotent).
+//   3. Git version fallback — _setGitVersionForTests forces a low version; the
+//      partial-clone branch must fall back to a full clone and return warning.
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { execFileSync } = require('child_process');
+
+const githubTeamStore = require('../lib/github-team-store');
+const gitRunner = require('../lib/git-runner');
+
+function assert(cond, msg) {
+  if (!cond) throw new Error(msg);
+}
+
+function git(cwd, args) {
+  return execFileSync('git', args, { cwd, stdio: ['ignore', 'pipe', 'pipe'] }).toString('utf-8').trim();
+}
+
+function initBareRemote(cwd) {
+  fs.mkdirSync(cwd, { recursive: true });
+  git(cwd, ['init', '--bare']);
+}
+
+function seedRemoteWith(cwd, files) {
+  const work = fs.mkdtempSync(path.join(os.tmpdir(), `kb-sparse-seed-${process.pid}-`));
+  git(work, ['init']);
+  git(work, ['config', 'user.name', 'Test User']);
+  git(work, ['config', 'user.email', 'test@example.com']);
+  for (const [relPath, content] of Object.entries(files)) {
+    const abs = path.join(work, relPath);
+    fs.mkdirSync(path.dirname(abs), { recursive: true });
+    fs.writeFileSync(abs, content);
+  }
+  git(work, ['add', '-A']);
+  git(work, ['commit', '-m', 'seed']);
+  git(work, ['branch', '-M', 'main']);
+  const head = git(work, ['rev-parse', 'HEAD']);
+  git(cwd, ['symbolic-ref', 'HEAD', 'refs/heads/main']);
+  const pushTarget = `file://${path.resolve(cwd)}`;
+  git(work, ['remote', 'add', 'origin', pushTarget]);
+  git(work, ['push', 'origin', 'main']);
+  return { work, head };
+}
+
+async function run() {
+  const tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), `kb-team-sparse-${process.pid}-`));
+  const TEAM_REMOTE_SPARSE = path.join(tmpRoot, 'remote-sparse.git');
+  const LOCAL_CLONE = path.join(tmpRoot, 'local-clone');
+  const remoteUrl = `file://${TEAM_REMOTE_SPARSE.replace(/\\/g, '/')}`;
+
+  let scenariosPassed = 0;
+  let scenariosTotal = 0;
+
+  // ------------------------------------------------------------------
+  // Scenario 1: New sparse clone
+  // ------------------------------------------------------------------
+  {
+    scenariosTotal++;
+    fs.rmSync(TEAM_REMOTE_SPARSE, { recursive: true, force: true });
+    fs.rmSync(LOCAL_CLONE, { recursive: true, force: true });
+    initBareRemote(TEAM_REMOTE_SPARSE);
+    seedRemoteWith(TEAM_REMOTE_SPARSE, {
+      'acc/README.md': '# acc\n',
+      'other/README.md': '# other\n',
+      'docs/notes.md': 'docs\n',
+    });
+
+    const result = await githubTeamStore.checkoutStore({
+      cloneUrl: remoteUrl,
+      branch: 'main',
+      localPath: LOCAL_CLONE,
+      subdir: 'acc',
+      partialClone: true,
+    });
+
+    assert(result.ok, `[scenario 1] checkoutStore should succeed: ${result.error || ''}`);
+    assert(result.action === 'cloned-partial', `[scenario 1] expected action='cloned-partial' but got '${result.action}'`);
+    assert(result.sparseCheckedOut === true, '[scenario 1] sparseCheckedOut should be true');
+    assert(fs.existsSync(path.join(LOCAL_CLONE, 'acc', 'README.md')), '[scenario 1] acc/README.md should exist');
+    assert(!fs.existsSync(path.join(LOCAL_CLONE, 'other', 'README.md')), '[scenario 1] other/README.md should NOT exist (cone excluded)');
+    assert(!fs.existsSync(path.join(LOCAL_CLONE, 'docs', 'notes.md')), '[scenario 1] docs/notes.md should NOT exist (cone excluded)');
+    const sparseFile = path.join(LOCAL_CLONE, '.git', 'info', 'sparse-checkout');
+    assert(fs.existsSync(sparseFile), '[scenario 1] .git/info/sparse-checkout should be present');
+    scenariosPassed++;
+    console.log('[scenario 1: NEW sparse clone] OK');
+  }
+
+  // ------------------------------------------------------------------
+  // Scenario 2: Re-clone / add cone
+  // ------------------------------------------------------------------
+  {
+    scenariosTotal++;
+    fs.rmSync(TEAM_REMOTE_SPARSE, { recursive: true, force: true });
+    fs.rmSync(LOCAL_CLONE, { recursive: true, force: true });
+    initBareRemote(TEAM_REMOTE_SPARSE);
+    seedRemoteWith(TEAM_REMOTE_SPARSE, {
+      'acc/README.md': '# acc\n',
+      'other/README.md': '# other\n',
+    });
+    // First clone with subdir='acc'
+    const first = await githubTeamStore.checkoutStore({
+      cloneUrl: remoteUrl,
+      branch: 'main',
+      localPath: LOCAL_CLONE,
+      subdir: 'acc',
+      partialClone: true,
+    });
+    assert(first.ok && first.action === 'cloned-partial', `[scenario 2] first clone should be partial`);
+    assert(fs.existsSync(path.join(LOCAL_CLONE, 'acc', 'README.md')), '[scenario 2] acc/README.md should exist after first clone');
+
+    // Add a new subdir to remote
+    const work = fs.mkdtempSync(path.join(os.tmpdir(), `kb-sparse-switch-${process.pid}-`));
+    fs.rmSync(work, { recursive: true, force: true });
+    fs.mkdirSync(work, { recursive: true });
+    git(work, ['clone', `file://${TEAM_REMOTE_SPARSE}`, '.']);
+    git(work, ['config', 'user.name', 'Test User']);
+    git(work, ['config', 'user.email', 'test@example.com']);
+    fs.mkdirSync(path.join(work, 'acc2'), { recursive: true });
+    fs.writeFileSync(path.join(work, 'acc2', 'README.md'), '# acc2\n');
+    git(work, ['add', '-A']);
+    git(work, ['commit', '-m', 'add acc2']);
+    git(work, ['push']);
+
+    // Re-sync with subdir='acc2' should expand the cone, not remove acc.
+    const second = await githubTeamStore.checkoutStore({
+      cloneUrl: remoteUrl,
+      branch: 'main',
+      localPath: LOCAL_CLONE,
+      subdir: 'acc2',
+      partialClone: true,
+    });
+    assert(second.ok, `[scenario 2] second checkout should succeed: ${second.error || ''}`);
+    assert(second.action === 'pulled-partial', `[scenario 2] expected action='pulled-partial' but got '${second.action}'`);
+    assert(fs.existsSync(path.join(LOCAL_CLONE, 'acc2', 'README.md')), '[scenario 2] acc2/README.md should exist after adding cone');
+    assert(fs.existsSync(path.join(LOCAL_CLONE, 'acc', 'README.md')), '[scenario 2] acc/README.md should still exist after adding acc2');
+    scenariosPassed++;
+    console.log('[scenario 2: cone expand] OK');
+  }
+
+  // ------------------------------------------------------------------
+  // Scenario 3: Git version fallback
+  // ------------------------------------------------------------------
+  {
+    scenariosTotal++;
+    fs.rmSync(TEAM_REMOTE_SPARSE, { recursive: true, force: true });
+    fs.rmSync(LOCAL_CLONE, { recursive: true, force: true });
+    initBareRemote(TEAM_REMOTE_SPARSE);
+    seedRemoteWith(TEAM_REMOTE_SPARSE, {
+      'acc/README.md': '# acc\n',
+      'other/README.md': '# other\n',
+    });
+
+    // Force the cached version to be < 2.25
+    gitRunner._setGitVersionForTests({ ok: true, major: 2, minor: 24, raw: 'git version 2.24.0' });
+    try {
+      const result = await githubTeamStore.checkoutStore({
+        cloneUrl: remoteUrl,
+        branch: 'main',
+        localPath: LOCAL_CLONE,
+        subdir: 'acc',
+        partialClone: true,
+      });
+      assert(result.ok, `[scenario 3] checkoutStore should fall back to full clone: ${result.error || ''}`);
+      assert(result.action === 'cloned-fallback', `[scenario 3] expected action='cloned-fallback' but got '${result.action}'`);
+      assert(typeof result.warning === 'string' && /2\.25/.test(result.warning), `[scenario 3] warning should mention 2.25: ${result.warning || ''}`);
+      // Full clone means both subdirs ARE present.
+      assert(fs.existsSync(path.join(LOCAL_CLONE, 'acc', 'README.md')), '[scenario 3] acc/README.md should exist (full clone)');
+      assert(fs.existsSync(path.join(LOCAL_CLONE, 'other', 'README.md')), '[scenario 3] other/README.md should exist (full clone)');
+      scenariosPassed++;
+      console.log('[scenario 3: Git < 2.25 fallback] OK');
+    } finally {
+      gitRunner._setGitVersionForTests(null);
+    }
+  }
+
+  console.log(`\nsummary: ${scenariosPassed}/${scenariosTotal} scenarios passed`);
+  if (scenariosPassed !== scenariosTotal) {
+    process.exitCode = 1;
+  }
+}
+
+run().catch(err => {
+  console.error('test failed:', err.message);
+  console.error(err.stack);
+  process.exitCode = 1;
+});

package/_site/_test/team-knowledge-store-test.js

@@ -0,0 +1,131 @@
+const assert = require('assert');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { execFileSync } = require('child_process');
+const { spawnServer } = require('./helpers/spawn-server');
+const githubTeamStore = require('../lib/github-team-store');
+
+const ROOT = path.resolve(__dirname, '..', '..');
+const PORT = Number(process.env.KB_TEAM_KNOWLEDGE_PORT || 7837);
+const BASE_URL = `http://127.0.0.1:${PORT}`;
+const TEMP = fs.mkdtempSync(path.join(os.tmpdir(), `kb-team-v2-${process.pid}-`));
+const DATA_DIR = path.join(TEMP, 'data');
+const SOURCE_ONE = path.join(TEMP, 'source-one');
+const SOURCE_TWO = path.join(TEMP, 'source-two');
+const SOURCE_BAD = path.join(TEMP, 'source-bad');
+const TEAM_STORE = path.join(TEMP, 'team-store');
+const TEAM_REMOTE = path.join(TEMP, 'team-remote');
+const TEAM_CLONE = path.join(TEMP, 'team-clone');
+
+function git(cwd, args) {
+  return execFileSync('git', args, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }).trim();
+}
+
+function initializeRepo(cwd, title) {
+  fs.mkdirSync(cwd, { recursive: true });
+  git(cwd, ['init', '--initial-branch=main']);
+  git(cwd, ['config', 'user.name', 'Team Test']);
+  git(cwd, ['config', 'user.email', 'team@example.test']);
+  fs.writeFileSync(path.join(cwd, 'README.md'), `# ${title}\n`, 'utf8');
+  git(cwd, ['add', '.']);
+  git(cwd, ['commit', '-m', 'baseline']);
+}
+
+async function waitForServer() {
+  for (let attempt = 0; attempt < 100; attempt += 1) {
+    try { if ((await fetch(`${BASE_URL}/api/health`)).ok) return; } catch {}
+    await new Promise(resolve => setTimeout(resolve, 100));
+  }
+  throw new Error('server did not start');
+}
+
+async function json(method, route, body) {
+  const response = await fetch(`${BASE_URL}${route}`, {
+    method,
+    headers: body ? { 'Content-Type': 'application/json' } : undefined,
+    body: body ? JSON.stringify(body) : undefined,
+  });
+  const text = await response.text();
+  return { response, body: text ? JSON.parse(text) : {} };
+}
+
+(async () => {
+  let spawned;
+  try {
+    initializeRepo(SOURCE_ONE, 'Source one');
+    initializeRepo(SOURCE_TWO, 'Source two');
+    initializeRepo(SOURCE_BAD, 'Source bad');
+    initializeRepo(TEAM_STORE, 'Team store');
+    fs.mkdirSync(path.join(TEAM_STORE, 'acc'), { recursive: true });
+    fs.writeFileSync(path.join(TEAM_STORE, 'acc', 'README.md'), '# ACC shared knowledge\n', 'utf8');
+    git(TEAM_STORE, ['add', '.']);
+    git(TEAM_STORE, ['commit', '-m', 'add team knowledge']);
+    git(TEAM_STORE, ['remote', 'add', 'origin', TEAM_STORE]);
+
+    initializeRepo(TEAM_REMOTE, 'Remote team store');
+    fs.mkdirSync(path.join(TEAM_REMOTE, 'acc'), { recursive: true });
+    fs.writeFileSync(path.join(TEAM_REMOTE, 'acc', 'README.md'), '# ACC from remote\n', 'utf8');
+    git(TEAM_REMOTE, ['add', '.']);
+    git(TEAM_REMOTE, ['commit', '-m', 'add remote knowledge']);
+
+    const providerConfigPath = path.join(TEMP, 'providers.json');
+    fs.writeFileSync(providerConfigPath, `\uFEFF${JSON.stringify({ gitea: { webBaseUrl: 'https://gitea.example.test', oauthClientId: 'client', oauthClientSecret: 'secret' } })}`, 'utf8');
+    const providerFile = githubTeamStore.readProviderFileConfig(providerConfigPath);
+    const publicProviders = githubTeamStore.providerPublicConfig(githubTeamStore.defaultConfig(), {}, providerFile);
+    assert.strictEqual(publicProviders.gitea.configured, true);
+    assert.strictEqual(publicProviders.gitea.oauthClientSecret, undefined);
+    assert.strictEqual(publicProviders.gitea.oauthClientSecretConfigured, true);
+    assert.strictEqual(githubTeamStore.proxyUrlForTarget('http://127.0.0.1:3000/api/v1/user', { KB_GIT_PROXY: 'http://127.0.0.1:7890' }), '');
+
+    const scanned = await githubTeamStore.scanLocalStore({ localPath: TEAM_STORE });
+    assert(scanned.ok && scanned.store.knowledgeBases.some(item => item.path === 'acc'), JSON.stringify(scanned));
+    const checkedOut = await githubTeamStore.checkoutStore({ cloneUrl: TEAM_REMOTE, branch: 'main', localPath: TEAM_CLONE });
+    assert(checkedOut.ok, JSON.stringify(checkedOut));
+    assert.match(fs.readFileSync(path.join(TEAM_CLONE, 'acc', 'README.md'), 'utf8'), /from remote/);
+
+    spawned = spawnServer({ root: ROOT, port: PORT, dataDir: DATA_DIR, tag: 'team-kb-v2' });
+    let output = '';
+    spawned.child.stdout.on('data', chunk => { output += chunk; });
+    spawned.child.stderr.on('data', chunk => { output += chunk; });
+    await waitForServer();
+    let result = await json('PATCH', '/api/settings', { knowledge: { rootPath: path.join(TEMP, 'personal-knowledge') } });
+    assert(result.response.ok, JSON.stringify(result.body));
+
+    result = await json('POST', '/api/projects/import', {
+      projectId: 'team-project-one', localPath: SOURCE_ONE,
+      teamKnowledgeBase: {
+        storeLocalPath: TEAM_STORE, storeRemoteUrl: 'https://github.com/org/knowledge.git',
+        storeFullName: 'org/knowledge', storeId: 'team-store', kbId: 'kb-acc', kbSlug: 'acc', kbSubdir: 'acc', displayName: 'ACC',
+      },
+    });
+    assert.strictEqual(result.response.status, 201, `${JSON.stringify(result.body)}\n${output}`);
+    assert.strictEqual(path.resolve(result.body.config.knowledgePath), path.resolve(TEAM_STORE, 'acc'));
+    assert.strictEqual(result.body.config.teamBinding.provider, 'github');
+    assert.strictEqual(result.body.config.teamBinding.kbId, 'kb-acc');
+    assert.strictEqual(result.body.config.teamBinding.kbSubdir, 'acc');
+    const registryText = fs.readFileSync(path.join(DATA_DIR, 'projects.json'), 'utf8');
+    assert(!registryText.includes(TEAM_STORE), 'minimal v2 registry must not contain the external team path');
+
+    result = await json('POST', '/api/projects/import', {
+      projectId: 'team-project-bad', localPath: SOURCE_BAD,
+      teamKnowledgeBase: { storeLocalPath: TEAM_STORE, kbSubdir: '../escape' },
+    });
+    assert.strictEqual(result.response.status, 403, 'team binding traversal must be rejected');
+
+    result = await json('POST', '/api/projects/import', {
+      projectId: 'team-project-two', localPath: SOURCE_TWO,
+      teamKnowledgeBase: { storeLocalPath: TEAM_CLONE, storeRemoteUrl: TEAM_REMOTE, storeId: 'clone', kbId: 'kb-acc', kbSubdir: 'acc' },
+    });
+    assert.strictEqual(result.response.status, 201, JSON.stringify(result.body));
+    assert.strictEqual(path.resolve(result.body.config.knowledgePath), path.resolve(TEAM_CLONE, 'acc'));
+
+    result = await json('DELETE', '/api/projects/team-project-one', { deleteKnowledge: true, confirmationToken: 'team-project-one' });
+    assert(result.response.ok, JSON.stringify(result.body));
+    assert.strictEqual(result.body.removedKnowledge, false, 'team knowledge is externally owned');
+    assert(fs.existsSync(path.join(TEAM_STORE, 'acc', 'README.md')), 'team knowledge must survive project deletion');
+    console.log('team knowledge store test passed');
+  } finally {
+    if (spawned) spawned.child.kill();
+  }
+})().catch(error => { console.error(error); process.exitCode = 1; });

package/_site/_test/tracking-start-test.js

@@ -0,0 +1,143 @@
+// Run: node _site/_test/tracking-start-test.js
+
+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 { ProjectRegistryStore } = require('../lib/project-registry-store');
+const { ProjectStore } = require('../lib/project-store');
+const { ProjectLifecycleService } = require('../lib/project-lifecycle-service');
+const { CommitReconciler } = require('../lib/commit-reconciler');
+
+const temp = fs.mkdtempSync(path.join(os.tmpdir(), `kb-tracking-start-${process.pid}-`));
+const layout = new StorageLayout({ dataDir: path.join(temp, 'data') });
+const registry = new ProjectRegistryStore({ layout });
+const projects = new ProjectStore({ layout });
+const knowledgeRoot = path.join(temp, 'knowledge');
+
+function git(repo, args) {
+  const result = spawnSync('git', ['-C', repo, ...args], { encoding: 'utf8', windowsHide: true });
+  if (result.status !== 0) throw new Error(result.stderr || `git ${args.join(' ')} failed`);
+  return String(result.stdout || '').trim();
+}
+
+function repo(name, withCommit) {
+  const target = path.join(temp, name);
+  fs.mkdirSync(target, { recursive: true });
+  git(target, ['init', '--initial-branch=main']);
+  git(target, ['config', 'user.email', 'tracking@example.test']);
+  git(target, ['config', 'user.name', 'Tracking Test']);
+  if (withCommit) commit(target, 'imported');
+  return target;
+}
+
+function commit(target, name) {
+  fs.writeFileSync(path.join(target, `${name}.txt`), `${name}\n`, 'utf8');
+  git(target, ['add', `${name}.txt`]);
+  git(target, ['commit', '-m', name]);
+  return git(target, ['rev-parse', 'HEAD']);
+}
+
+(async () => {
+  fs.mkdirSync(knowledgeRoot, { recursive: true });
+  await registry.initialize();
+  const installed = [];
+  const lifecycle = new ProjectLifecycleService({
+    layout,
+    registryStore: registry,
+    projectStore: projects,
+    settingsStore: { read: () => ({ knowledge: { rootPath: knowledgeRoot }, ai: { schema: 'ai-profiles/v1', profiles: [{ id: 'test-profile', enabled: true, vendor: 'anthropic', model: 'm' }], defaultProfileId: null } }) },
+    triggerScriptPath: path.join(temp, 'hook-trigger.js'),
+    hookManager: {
+      installHook: options => { installed.push(options.projectId); return { ok: true, managedVersion: 2 }; },
+      uninstallHook: () => ({ ok: true }),
+    },
+  });
+
+  const existingRepo = repo('existing-repo', true);
+  const importedHead = git(existingRepo, ['rev-parse', 'HEAD']);
+  const imported = await lifecycle.importProject({ localPath: existingRepo, projectId: 'project-existing', aiProfileId: 'test-profile' });
+  assert.strictEqual(imported.state.trackingStartCommit, importedHead);
+  assert.strictEqual(imported.state.lastAnalyzedCommit, null);
+  assert.strictEqual(imported.state.trackingMode, 'normal');
+  assert.strictEqual(installed.length, 1, 'import should install Hook but not analyze');
+
+  let processorCalls = 0;
+  const processor = {
+    processClaim: async input => {
+      processorCalls += 1;
+      await projects.updateState(input.projectId, state => {
+        state.lastAnalyzedCommit = input.claim.commitSha;
+        state.analysis.activeClaim = null;
+        state.analysis.status = 'state.advanced';
+        state.index.dirty = true;
+        state.index.generation += 1;
+      });
+      return { stateAdvanced: true };
+    },
+  };
+  const reconciler = new CommitReconciler({
+    layout,
+    registryStore: registry,
+    projectStore: projects,
+    settingsStore: { read: () => ({ knowledge: { rootPath: knowledgeRoot }, ai: { schema: 'ai-profiles/v1', profiles: [{ id: 'test-profile', enabled: true, vendor: 'anthropic', model: 'm' }], defaultProfileId: null } }) },
+    claimProcessor: processor,
+  });
+  await assert.rejects(reconciler.reconcile('project-existing', 'startup'), error => error.code === 'INVALID_TRIGGER');
+  assert.strictEqual(processorCalls, 0, 'startup after import must not analyze pre-import history');
+  const nextCommit = commit(existingRepo, 'after-import');
+  const laterCommit = commit(existingRepo, 'after-import-later');
+  await reconciler.processCommitEvent({ projectId: 'project-existing', commitSha: nextCommit, branch: 'main' });
+  assert.strictEqual(projects.readState('project-existing').lastAnalyzedCommit, nextCommit);
+  assert.strictEqual(processorCalls, 1);
+  await reconciler.processCommitEvent({ projectId: 'project-existing', commitSha: laterCommit, branch: 'main' });
+  assert.strictEqual(projects.readState('project-existing').lastAnalyzedCommit, laterCommit, 'an event SHA remains valid even after HEAD advances');
+  assert.strictEqual(processorCalls, 2);
+
+  const terminalFailedCommit = 'a'.repeat(40);
+  await projects.updateState('project-existing', state => {
+    state.analysis.activeClaim = {
+      schema: 'commit-claim/v1', projectId: 'project-existing', commitSha: terminalFailedCommit, parents: [], requirementIds: [], requirementBinding: 'unavailable',
+      promptTemplateVersion: 'v1', promptHash: 'prompt', patchHash: 'patch', evidenceHash: 'evidence', evidenceManifestHash: 'manifest', retrievalManifestHash: 'retrieval', knowledgePath: knowledgeRoot,
+      runId: 'failed-run', operationId: 'failed-operation', phase: 'failed', attempt: 1, fingerprint: 'failed-fingerprint', error: { code: 'EPERM', retryable: false },
+    };
+    state.analysis.status = 'failed';
+  });
+  const explicitAfterFailure = commit(existingRepo, 'after-terminal-failure');
+  await reconciler.processCommitEvent({ projectId: 'project-existing', commitSha: explicitAfterFailure, branch: 'main' });
+  assert.strictEqual(projects.readState('project-existing').lastAnalyzedCommit, explicitAfterFailure, 'only the new explicit Hook SHA may proceed after a terminal failure');
+  assert.strictEqual(processorCalls, 3, 'terminal failed claims must not retry their old SHA');
+
+  const retryableFailedCommit = 'b'.repeat(40);
+  await projects.updateState('project-existing', state => {
+    state.analysis.activeClaim = {
+      schema: 'commit-claim/v1', projectId: 'project-existing', commitSha: retryableFailedCommit, parents: [], requirementIds: [], requirementBinding: 'unavailable',
+      promptTemplateVersion: 'v1', promptHash: 'prompt', patchHash: 'patch', evidenceHash: 'evidence', evidenceManifestHash: 'manifest', retrievalManifestHash: 'retrieval', knowledgePath: knowledgeRoot,
+      runId: 'retryable-run', operationId: 'retryable-operation', phase: 'failed', attempt: 1, fingerprint: 'retryable-fingerprint', error: { code: 'EAGAIN', retryable: true },
+    };
+    state.analysis.status = 'failed';
+  });
+  const blockedByRetryable = commit(existingRepo, 'after-retryable-failure');
+  const blockedResult = await reconciler.processCommitEvent({ projectId: 'project-existing', commitSha: blockedByRetryable, branch: 'main' });
+  assert.strictEqual(blockedResult.status, 'failed');
+  assert.strictEqual(processorCalls, 3, 'retryable claims must remain blocked instead of being silently superseded');
+  assert.strictEqual(projects.readState('project-existing').analysis.activeClaim.commitSha, retryableFailedCommit);
+
+  const emptyRepo = repo('empty-repo', false);
+  const emptyImported = await lifecycle.importProject({ localPath: emptyRepo, projectId: 'project-empty', aiProfileId: 'test-profile' });
+  assert.strictEqual(emptyImported.state.trackingMode, 'empty-repo');
+  assert.strictEqual(emptyImported.state.trackingStartCommit, null);
+  const firstCommit = commit(emptyRepo, 'first');
+  await reconciler.processCommitEvent({ projectId: 'project-empty', commitSha: firstCommit, branch: 'main' });
+  assert.strictEqual(projects.readState('project-empty').lastAnalyzedCommit, firstCommit, 'first commit after empty import must be analyzed');
+  assert.strictEqual(processorCalls, 4);
+
+  console.log('tracking-start-test PASS');
+})().catch(error => {
+  console.error(error.stack || error.message);
+  process.exitCode = 1;
+}).finally(() => {
+  fs.rmSync(temp, { recursive: true, force: true });
+});