project-knowledge 0.1.0

package/_site/_test/pr-consumer-contract-test.js

@@ -0,0 +1,236 @@
+// TASK-011: PR consumer contract test
+// Run: node _site/_test/pr-consumer-contract-test.js
+const fs = require('fs');
+const path = require('path');
+const { spawn } = require('child_process');
+const { validateKb, buildPrContextPack, MANIFEST_SCHEMA } = require('../lib/kb-validator');
+
+const ROOT = path.resolve(__dirname, '..', '..');
+const SERVER = path.join(ROOT, '_site', 'server.js');
+const PROJECTS_JSON = path.join(ROOT, 'projects.json');
+const PORT = process.env.KB_PR_TEST_PORT || '7801';
+const BASE_URL = `http://127.0.0.1:${PORT}`;
+const TEMP_SLUG = 'task-011-temp';
+
+const FIX_HEALTHY = path.join(__dirname, 'fixtures', 'pr-context', 'healthy');
+const FIX_NO_GOAL = path.join(__dirname, 'fixtures', 'pr-context', 'missing-goal');
+const FIX_LEAK    = path.join(__dirname, 'fixtures', 'pr-context', 'draft-leak');
+
+function assert(cond, msg) { if (!cond) throw new Error(msg); }
+
+async function waitForServer() {
+  const deadline = Date.now() + 15000;
+  let lastError;
+  while (Date.now() < deadline) {
+    try {
+      const res = await fetch(`${BASE_URL}/api/state`);
+      if (res.ok) return;
+      lastError = new Error(`HTTP ${res.status}`);
+    } catch (e) { lastError = e; }
+    await new Promise(r => setTimeout(r, 250));
+  }
+  throw lastError || new Error('server did not start');
+}
+
+async function json(method, url, body) {
+  const res = await fetch(`${BASE_URL}${url}`, {
+    method,
+    headers: body ? { 'Content-Type': 'application/json' } : undefined,
+    body: body ? JSON.stringify(body) : undefined,
+  });
+  const text = await res.text();
+  let data = {};
+  if (text) { try { data = JSON.parse(text); } catch { data = { raw: text }; } }
+  return { res, data };
+}
+
+async function cleanup() {
+  const base = path.join(ROOT, 'projects', TEMP_SLUG);
+  fs.rmSync(base, { recursive: true, force: true });
+  const cur = JSON.parse(fs.readFileSync(PROJECTS_JSON, 'utf-8'));
+  if (cur[TEMP_SLUG]) {
+    delete cur[TEMP_SLUG];
+    fs.writeFileSync(PROJECTS_JSON, JSON.stringify(cur, null, 2) + '\n', 'utf-8');
+  }
+}
+
+function copyDir(src, dest) {
+  fs.rmSync(dest, { recursive: true, force: true });
+  fs.mkdirSync(dest, { recursive: true });
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    const s = path.join(src, entry.name);
+    const d = path.join(dest, entry.name);
+    if (entry.isDirectory()) copyDir(s, d);
+    else fs.copyFileSync(s, d);
+  }
+}
+
+(async () => {
+  // --- Fixture sanity ---
+  for (const f of [FIX_HEALTHY, FIX_NO_GOAL, FIX_LEAK]) {
+    assert(fs.existsSync(f), `fixture missing: ${f}`);
+    assert(fs.existsSync(path.join(f, 'kb-manifest.json')), `manifest missing in ${f}`);
+  }
+
+  // 1. MANIFEST_SCHEMA constant
+  assert(MANIFEST_SCHEMA === 'kb-manifest/v1', 'MANIFEST_SCHEMA should be kb-manifest/v1');
+
+  // 2. validateKb(healthy) — should pass
+  let r = validateKb(FIX_HEALTHY);
+  assert(r.ok, `healthy fixture should validate: ${JSON.stringify(r.errors)}`);
+  assert(r.info.goalStatus === 'accepted', `healthy goalStatus should be accepted, got ${r.info.goalStatus}`);
+  assert(r.info.analysisStatus === 'present', 'healthy analysisStatus should be present');
+  assert(r.info.trustedKnowledgeEntries >= 5, 'healthy should have multiple trusted entries');
+  assert(r.info.aiSubdirsPresent.length >= 3, 'healthy should have all _ai/ subdirs');
+  assert(r.manifest && r.manifest.schema === MANIFEST_SCHEMA, 'manifest should round-trip');
+  assert(Array.isArray(r.errors) && r.errors.length === 0, 'no errors');
+  // Healthy fixture may emit a warning if `README.md` is missing from the
+  // trusted list, but we DO list it, so no warnings expected.
+  assert(!r.warnings || r.warnings.length === 0, `healthy should have no warnings; got ${JSON.stringify(r.warnings)}`);
+
+  // 3. validateKb(missing-goal) — should pass with goalStatus not-created
+  r = validateKb(FIX_NO_GOAL);
+  assert(r.ok, `missing-goal should validate: ${JSON.stringify(r.errors)}`);
+  assert(r.info.goalStatus === 'not-created', `missing-goal should report goalStatus not-created, got ${r.info.goalStatus}`);
+  assert(r.info.analysisStatus === 'present', 'missing-goal analysisStatus should be present');
+
+  // 4. validateKb(draft-leak) — must fail because a path under _ai/ is in trustedKnowledge
+  r = validateKb(FIX_LEAK);
+  assert(!r.ok, 'draft-leak must fail validation');
+  assert(r.errors.some(e => /trustedKnowledge entry is inside _ai/.test(e)),
+    `draft-leak should report a draft-leak error; got ${JSON.stringify(r.errors)}`);
+
+  // 5. buildPrContextPack(healthy) — returns a pr-context-pack/v1 with goal+analysis+indexes
+  let pack = buildPrContextPack(FIX_HEALTHY);
+  assert(pack.ok, 'healthy pack should be ok');
+  assert(pack.pack.schema === 'pr-context-pack/v1', 'pack schema is v1');
+  assert(pack.pack.project === 'healthy', 'pack carries project name');
+  assert(pack.pack.goal && pack.pack.goal.path === 'project-goal.md', 'pack has goal with path');
+  assert(pack.pack.goal.content && pack.pack.goal.content.length > 0, 'pack goal has content');
+  assert(pack.pack.analysis && pack.pack.analysis.path === 'project-analysis.md', 'pack has analysis');
+  assert(pack.pack.indexes && pack.pack.indexes.features, 'pack has features index');
+  assert(pack.pack.indexes.modules, 'pack has modules index');
+  assert(Array.isArray(pack.pack.trustedKnowledge), 'pack has trustedKnowledge array');
+  // The pack MUST NOT include anything from _ai/
+  const asString = JSON.stringify(pack.pack);
+  assert(!/_ai\//.test(asString), 'pack must not include anything from _ai/');
+  // README.md and framework.md should be in trustedKnowledge
+  const paths = pack.pack.trustedKnowledge.map(t => t.path);
+  assert(paths.includes('README.md'), 'trustedKnowledge should include README.md');
+
+  // 6. buildPrContextPack(missing-goal) — goal field is null
+  pack = buildPrContextPack(FIX_NO_GOAL);
+  assert(pack.ok, 'missing-goal pack should be ok');
+  assert(pack.pack.goal === null, 'missing-goal pack.goal should be null');
+
+  // 7. buildPrContextPack(draft-leak) — refuses
+  pack = buildPrContextPack(FIX_LEAK);
+  assert(!pack.ok, 'draft-leak pack should refuse');
+
+  // 8. validateKb on a non-existent path
+  r = validateKb(path.join(__dirname, '__no_such_dir__'));
+  assert(!r.ok, 'non-existent kbPath should fail');
+  assert(r.status === 400, 'non-existent path should be 400');
+
+  // 9. validateKb on a path that's not a directory
+  r = validateKb(__filename);
+  assert(!r.ok, 'file path should fail');
+  assert(r.status === 400, 'file path should be 400');
+
+  // 10. validateKb on a directory with no manifest
+  const noManifest = fs.mkdtempSync(path.join(require('os').tmpdir(), 'kb-no-manifest-'));
+  r = validateKb(noManifest);
+  assert(!r.ok && r.status === 422, 'no-manifest should 422');
+  fs.rmSync(noManifest, { recursive: true, force: true });
+
+  // 11. validateKb on a directory with malformed manifest
+  const badManifest = fs.mkdtempSync(path.join(require('os').tmpdir(), 'kb-bad-manifest-'));
+  fs.writeFileSync(path.join(badManifest, 'kb-manifest.json'), '{not valid json');
+  r = validateKb(badManifest);
+  assert(!r.ok && r.status === 422, 'bad manifest should 422');
+  fs.rmSync(badManifest, { recursive: true, force: true });
+
+  // 12. validateKb rejects a manifest with a missing goal file
+  const missingGoalFile = fs.mkdtempSync(path.join(require('os').tmpdir(), 'kb-missing-goal-'));
+  fs.writeFileSync(path.join(missingGoalFile, 'kb-manifest.json'), JSON.stringify({
+    schema: 'kb-manifest/v1',
+    project: 'x', kbRoot: 'x',
+    goal: { path: 'project-goal.md', status: 'accepted', updatedAt: '2026-06-11' },
+    analysis: { path: null, lastAnalyzedCommit: null, updatedAt: null },
+    trustedKnowledge: ['README.md'],
+    draftAreas: ['_ai/drafts/'],
+  }));
+  r = validateKb(missingGoalFile);
+  assert(!r.ok, 'missing goal file should fail');
+  assert(r.errors.some(e => /manifest.goal.path.*does not exist/.test(e)),
+    `expected a missing-goal error; got ${JSON.stringify(r.errors)}`);
+  fs.rmSync(missingGoalFile, { recursive: true, force: true });
+
+  // ----- Server tests -----
+  const child = spawn(process.execPath, [SERVER], {
+    cwd: ROOT,
+    env: { ...process.env, KB_SITE_PORT: PORT, KB_SITE_HOST: '127.0.0.1' },
+    stdio: ['ignore', 'pipe', 'pipe'],
+    windowsHide: true,
+  });
+  let serverOutput = '';
+  child.stdout.on('data', d => { serverOutput += d.toString(); });
+  child.stderr.on('data', d => { serverOutput += d.toString(); });
+
+  try {
+    await cleanup();
+    await waitForServer();
+
+    // 13. Copy the healthy fixture into a real project and validate via the API
+    const projKb = path.join(ROOT, 'projects', TEMP_SLUG);
+    copyDir(FIX_HEALTHY, projKb);
+
+    r = await json('PUT', '/api/projects', {
+      slug: TEMP_SLUG,
+      config: { displayName: 'TASK-011', localPath: 'D:\\__not_used__', gitPath: 'D:\\__not_used__', kbPath: projKb },
+    });
+    assert(r.res.ok, 'upsert should succeed');
+
+    r = await json('POST', `/api/projects/${TEMP_SLUG}/validate-kb`, {});
+    assert(r.res.ok, `validate-kb should succeed: ${JSON.stringify(r.data)}`);
+    assert(r.data.ok, `result should be ok: ${JSON.stringify(r.data)}`);
+    assert(r.data.info.goalStatus === 'accepted', 'api-reported goalStatus accepted');
+
+    r = await json('GET', `/api/projects/${TEMP_SLUG}/pr-context`);
+    assert(r.res.ok, 'pr-context should succeed');
+    assert(r.data.ok, 'pr-context result ok');
+    assert(r.data.pack.schema === 'pr-context-pack/v1', 'pack schema v1');
+    assert(r.data.pack.goal && r.data.pack.goal.content.length > 0, 'pack goal content present');
+
+    // 14. Draft-leak via API: the API must refuse
+    const leakSlug = TEMP_SLUG + '-leak';
+    const leakKb = path.join(ROOT, 'projects', leakSlug);
+    copyDir(FIX_LEAK, leakKb);
+    r = await json('PUT', '/api/projects', {
+      slug: leakSlug,
+      config: { displayName: 'TASK-011 leak', localPath: 'D:\\__not_used__', gitPath: 'D:\\__not_used__', kbPath: leakKb },
+    });
+    assert(r.res.ok, 'upsert leak should succeed');
+
+    r = await json('POST', `/api/projects/${leakSlug}/validate-kb`, {});
+    assert(!r.res.ok && r.res.status === 422, 'leak validate should 422');
+    assert(r.data.errors && r.data.errors.length > 0, 'errors should be reported');
+
+    r = await json('GET', `/api/projects/${leakSlug}/pr-context`);
+    assert(!r.res.ok && r.res.status === 422, 'leak pr-context should 422');
+
+    // 15. Bad slug
+    r = await json('POST', '/api/projects/-bad-/validate-kb', {});
+    assert(!r.res.ok && r.res.status === 400, 'bad slug should 400');
+
+    console.log('TASK-011 PR consumer contract test passed');
+  } catch (e) {
+    console.error('TASK-011 PR consumer contract test failed:', e.message);
+    if (serverOutput) console.error(serverOutput);
+    process.exitCode = 1;
+  } finally {
+    await cleanup().catch(() => {});
+    try { fs.rmSync(path.join(ROOT, 'projects', TEMP_SLUG + '-leak'), { recursive: true, force: true }); } catch {}
+    child.kill();
+  }
+})();

package/_site/_test/run-all-tests.js

@@ -0,0 +1,135 @@
+// _site/_test/run-all-tests.js
+//
+// Single-command regression suite runner. Iterates the canonical test files
+// under _site/_test/ (everything matching *-test.js) and runs each one in a
+// separate child process, capturing exit code, duration, and the last few
+// lines of output. Writes a Markdown report to TEST-REPORT.md.
+//
+// Usage:
+//   node _site/_test/run-all-tests.js                  # run all *-test.js
+//   node _site/_test/run-all-tests.js --no-report      # do not write report
+//   node _site/_test/run-all-tests.js --include-ui     # also run ui-test.js
+//                                                      # (requires Playwright)
+//
+// Exit code is 0 only if every test passes.
+
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+const ROOT = path.resolve(__dirname, '..', '..');
+const TEST_DIR = __dirname;
+const REPORT_PATH = path.join(TEST_DIR, 'TEST-REPORT.md');
+
+const args = process.argv.slice(2);
+const WRITE_REPORT = !args.includes('--no-report');
+const INCLUDE_UI = args.includes('--include-ui');
+
+function listTestFiles() {
+  return fs.readdirSync(TEST_DIR)
+    .filter(file => file.endsWith('-test.js'))
+    // Skip legacy ui-test.js by default. ui-smoke-test.js uses local Chrome via
+    // CDP and is safe to run as part of the regression suite.
+    .filter(file => INCLUDE_UI || file !== 'ui-test.js')
+    .filter(file => file !== 'run-all-tests.js')
+    .sort();
+}
+
+function tail(text, lines = 12) {
+  const arr = String(text || '').split(/\r?\n/).filter(Boolean);
+  return arr.slice(-lines).join('\n');
+}
+
+function runOne(file) {
+  const start = Date.now();
+  const result = spawnSync(process.execPath, [path.join(TEST_DIR, file)], {
+    cwd: ROOT,
+    encoding: 'utf-8',
+    timeout: 300_000,
+    env: { ...process.env, FORCE_COLOR: '0' },
+  });
+  return {
+    file,
+    passed: result.status === 0,
+    exitCode: result.status,
+    durationMs: Date.now() - start,
+    stdout: result.stdout || '',
+    stderr: result.stderr || '',
+    outputTail: tail(result.stdout || result.stderr),
+  };
+}
+
+(async () => {
+  const files = listTestFiles();
+  console.log(`Running ${files.length} test file(s)...\n`);
+
+  const results = [];
+  let totalDuration = 0;
+  for (const file of files) {
+    process.stdout.write(`> ${file} ... `);
+    const result = runOne(file);
+    totalDuration += result.durationMs;
+    results.push(result);
+
+    if (result.passed) {
+      console.log(`PASS (${result.durationMs}ms)`);
+    } else {
+      console.log(`FAIL (exit ${result.exitCode}, ${result.durationMs}ms)`);
+      if (result.outputTail) {
+        console.log('--- tail ---');
+        console.log(result.outputTail);
+        console.log('--- end tail ---');
+      }
+    }
+  }
+
+  const passed = results.filter(result => result.passed).length;
+  const failed = results.length - passed;
+  console.log('\n=========================================');
+  console.log(`Regression suite: ${passed} passed, ${failed} failed (${totalDuration}ms total)`);
+  console.log('=========================================\n');
+
+  if (WRITE_REPORT) {
+    const lines = [];
+    lines.push('# KB Management Site Regression Test Report');
+    lines.push('');
+    lines.push(`**Generated**: ${new Date().toISOString()}`);
+    lines.push(`**Node**: ${process.version}`);
+    lines.push('**Runner**: node _site/_test/run-all-tests.js');
+    lines.push('');
+    lines.push('## Summary');
+    lines.push('');
+    lines.push('| # | File | Status | Exit | Duration |');
+    lines.push('|--:|------|:------:|-----:|---------:|');
+    results.forEach((result, index) => {
+      const status = result.passed ? 'PASS' : 'FAIL';
+      lines.push(`| ${index + 1} | \`${result.file}\` | ${status} | ${result.exitCode} | ${result.durationMs}ms |`);
+    });
+    lines.push('');
+    lines.push(`**Total**: ${results.length} | **Passed**: ${passed} | **Failed**: ${failed} | **Time**: ${totalDuration}ms`);
+    lines.push('');
+
+    const failures = results.filter(result => !result.passed);
+    if (failures.length) {
+      lines.push('## Failures');
+      lines.push('');
+      for (const result of failures) {
+        lines.push(`### ${result.file}`);
+        lines.push('');
+        lines.push('```');
+        lines.push(result.outputTail);
+        lines.push('```');
+        lines.push('');
+      }
+    }
+
+    try {
+      fs.writeFileSync(REPORT_PATH, lines.join('\n'), 'utf-8');
+      console.log(`Report written to: ${REPORT_PATH}`);
+    } catch (e) {
+      console.error(`Failed to write report: ${e.message}`);
+    }
+  }
+
+  process.exit(failed > 0 ? 1 : 0);
+})();

package/_site/_test/scanner-test.js

@@ -0,0 +1,206 @@
+// TASK-004: Analysis state and scanner test
+// Run: node _site/_test/scanner-test.js
+const fs = require('fs');
+const path = require('path');
+const { spawn } = require('child_process');
+const { makeRepo, git } = require('./fixtures/make-git-repos');
+
+const ROOT = path.resolve(__dirname, '..', '..');
+const SERVER = path.join(ROOT, '_site', 'server.js');
+const PROJECTS_JSON = path.join(ROOT, 'projects.json');
+const PORT = process.env.KB_SCAN_TEST_PORT || '7794';
+const BASE_URL = `http://127.0.0.1:${PORT}`;
+const TEMP_SLUG = 'task-004-temp';
+
+function assert(cond, msg) { if (!cond) throw new Error(msg); }
+
+async function waitForServer() {
+  const deadline = Date.now() + 15000;
+  let lastError;
+  while (Date.now() < deadline) {
+    try {
+      const res = await fetch(`${BASE_URL}/api/state`);
+      if (res.ok) return;
+      lastError = new Error(`HTTP ${res.status}`);
+    } catch (e) { lastError = e; }
+    await new Promise(r => setTimeout(r, 250));
+  }
+  throw lastError || new Error('server did not start');
+}
+
+async function json(method, url, body) {
+  const res = await fetch(`${BASE_URL}${url}`, {
+    method,
+    headers: body ? { 'Content-Type': 'application/json' } : undefined,
+    body: body ? JSON.stringify(body) : undefined,
+  });
+  const text = await res.text();
+  let data = {};
+  if (text) { try { data = JSON.parse(text); } catch { data = { raw: text }; } }
+  return { res, data };
+}
+
+async function cleanup() {
+  const base = path.join(ROOT, 'projects', TEMP_SLUG);
+  fs.rmSync(base, { recursive: true, force: true });
+  const cur = JSON.parse(fs.readFileSync(PROJECTS_JSON, 'utf-8'));
+  if (cur[TEMP_SLUG]) {
+    delete cur[TEMP_SLUG];
+    fs.writeFileSync(PROJECTS_JSON, JSON.stringify(cur, null, 2) + '\n', 'utf-8');
+  }
+}
+
+async function upsert(slug, extra = {}) {
+  const r = await json('PUT', '/api/projects', {
+    slug,
+    config: { displayName: slug, ...extra },
+  });
+  assert(r.res.ok, 'upsert failed');
+  return r.data;
+}
+
+async function getProject(slug) {
+  const r = await json('GET', '/api/projects');
+  return r.data[slug];
+}
+
+(async () => {
+  assert(fs.existsSync(SERVER), 'server.js missing');
+  JSON.parse(fs.readFileSync(PROJECTS_JSON, 'utf-8'));
+
+  const child = spawn(process.execPath, [SERVER], {
+    cwd: ROOT,
+    env: { ...process.env, KB_SITE_PORT: PORT, KB_SITE_HOST: '127.0.0.1' },
+    stdio: ['ignore', 'pipe', 'pipe'],
+    windowsHide: true,
+  });
+  let serverOutput = '';
+  child.stdout.on('data', d => { serverOutput += d.toString(); });
+  child.stderr.on('data', d => { serverOutput += d.toString(); });
+
+  const fixtures = [];
+  try {
+    await cleanup();
+    await waitForServer();
+
+    // 1. Empty repo: pending=0, mode=initial
+    const empty = makeRepo({ kind: 'empty' });
+    fixtures.push(empty);
+    await upsert(TEMP_SLUG, { localPath: empty.path, gitPath: empty.path });
+
+    let r = await json('POST', `/api/projects/${TEMP_SLUG}/scan`);
+    assert(r.res.ok, 'scan should succeed');
+    assert(r.data.repoStatus === 'empty', `empty repo scan should report empty, got ${r.data.repoStatus}`);
+    assert(r.data.pendingCount === 0, `empty repo should have 0 pending, got ${r.data.pendingCount}`);
+
+    let cfg = await getProject(TEMP_SLUG);
+    assert(cfg.lastSeenCommit === null || cfg.lastSeenCommit === cfg.headCommit, 'lastSeenCommit should be null/head for empty');
+    assert(cfg.lastAnalyzedCommit === null, 'lastAnalyzedCommit must NOT be updated by scan');
+
+    // 2. Multi-commit repo: first scan → initial mode, all commits
+    const multi = makeRepo({ kind: 'multi-commit' });
+    fixtures.push(multi);
+    await upsert(TEMP_SLUG, { localPath: multi.path, gitPath: multi.path });
+
+    r = await json('POST', `/api/projects/${TEMP_SLUG}/scan`);
+    assert(r.res.ok, 'scan should succeed');
+    assert(r.data.mode === 'initial', `first scan should be initial mode, got ${r.data.mode}`);
+    assert(r.data.pendingCount === multi.commits.length, `pendingCount should be ${multi.commits.length}, got ${r.data.pendingCount}`);
+    assert(r.data.headCommit === multi.headCommit, 'headCommit should match fixture');
+
+    cfg = await getProject(TEMP_SLUG);
+    assert(cfg.lastSeenCommit === multi.headCommit, 'lastSeenCommit should equal head');
+    assert(cfg.lastAnalyzedCommit === null, 'lastAnalyzedCommit must NOT be updated by scan');
+
+    // 3. Add new commits → second scan should detect 2 new pending
+    const fs2 = require('fs');
+    fs2.writeFileSync(path.join(multi.path, 'src', 'c.ts'), 'export const c = 3;\n');
+    git(multi.path, 'add .');
+    git(multi.path, 'commit -q -m "feat: add c module"');
+    fs2.writeFileSync(path.join(multi.path, 'src', 'd.ts'), 'export const d = 4;\n');
+    git(multi.path, 'add .');
+    git(multi.path, 'commit -q -m "fix: add d module"');
+    const newHead = git(multi.path, 'rev-parse HEAD');
+
+    // Set lastAnalyzedCommit to the previous head (simulating a prior apply)
+    // We need to write to projects.json directly so the next scan uses incremental mode.
+    const cur = JSON.parse(fs.readFileSync(PROJECTS_JSON, 'utf-8'));
+    cur[TEMP_SLUG].lastAnalyzedCommit = multi.headCommit;
+    fs.writeFileSync(PROJECTS_JSON, JSON.stringify(cur, null, 2) + '\n', 'utf-8');
+
+    r = await json('POST', `/api/projects/${TEMP_SLUG}/scan`);
+    assert(r.res.ok, 'scan should succeed');
+    assert(r.data.mode === 'incremental', `second scan with lastAnalyzedCommit should be incremental, got ${r.data.mode}`);
+    assert(r.data.pendingCount === 2, `expected 2 new pending, got ${r.data.pendingCount}`);
+    assert(r.data.headCommit === newHead, 'headCommit should be updated to new HEAD');
+    assert(r.data.commits[0].subject.includes('fix: add d module'), 'commits should be ordered');
+
+    cfg = await getProject(TEMP_SLUG);
+    assert(cfg.lastSeenCommit === newHead, 'lastSeenCommit should equal new HEAD');
+    assert(cfg.lastAnalyzedCommit === multi.headCommit, 'lastAnalyzedCommit must NOT be updated by scan');
+
+    // 4. No new commits since lastAnalyzedCommit → 0 pending.
+    // (The scanner uses lastAnalyzedCommit as the range start, not lastSeenCommit.
+    //  This is by design: "pending" means "awaiting apply", not "new since last scan".)
+    r = await json('POST', `/api/projects/${TEMP_SLUG}/scan`);
+    assert(r.res.ok, 'scan should succeed');
+    assert(r.data.pendingCount === 2, 'pendingCount is anchored to lastAnalyzedCommit, so it stays at 2');
+    assert(r.data.mode === 'incremental', 'should still be incremental mode');
+
+    // 5. Bad slug returns 400
+    r = await json('POST', '/api/projects/INVALID../scan');
+    assert(!r.res.ok && r.res.status === 400, 'bad slug should 400');
+
+    // 6. GET /scan is read-only
+    r = await json('GET', `/api/projects/${TEMP_SLUG}/scan`);
+    assert(r.res.ok, 'GET scan should succeed');
+    assert(r.data.mode === 'incremental', 'GET scan should compute pending');
+
+    cfg = await getProject(TEMP_SLUG);
+    const beforeHead = cfg.lastSeenCommit;
+    const beforeAnalyzed = cfg.lastAnalyzedCommit;
+    r = await json('GET', `/api/projects/${TEMP_SLUG}/scan`);
+    cfg = await getProject(TEMP_SLUG);
+    assert(cfg.lastSeenCommit === beforeHead, 'GET scan must not write');
+    assert(cfg.lastAnalyzedCommit === beforeAnalyzed, 'GET scan must not change lastAnalyzedCommit');
+
+    // 7. Missing lastAnalyzedCommit uses initial mode
+    const cur2 = JSON.parse(fs.readFileSync(PROJECTS_JSON, 'utf-8'));
+    cur2[TEMP_SLUG].lastAnalyzedCommit = null;
+    fs.writeFileSync(PROJECTS_JSON, JSON.stringify(cur2, null, 2) + '\n', 'utf-8');
+
+    r = await json('POST', `/api/projects/${TEMP_SLUG}/scan`);
+    assert(r.data.mode === 'initial', 'cleared lastAnalyzedCommit should switch back to initial mode');
+    assert(r.data.pendingCount > 0, 'initial mode should report all commits');
+
+    // 8. /api/scan-all scans every enabled project
+    const enabledFixture = makeRepo({ kind: 'one-commit' });
+    fixtures.push(enabledFixture);
+    await json('PUT', '/api/projects', {
+      slug: 'task-004-scan-all',
+      config: { displayName: 'scan-all', localPath: enabledFixture.path, gitPath: enabledFixture.path },
+    });
+    r = await json('POST', '/api/scan-all');
+    assert(r.res.ok, 'scan-all should succeed');
+    const allEntry = r.data.results.find(x => x.slug === 'task-004-scan-all');
+    assert(allEntry && allEntry.ok, 'scan-all should include the new project');
+
+    // cleanup extra
+    const cur3 = JSON.parse(fs.readFileSync(PROJECTS_JSON, 'utf-8'));
+    delete cur3['task-004-scan-all'];
+    fs.writeFileSync(PROJECTS_JSON, JSON.stringify(cur3, null, 2) + '\n', 'utf-8');
+    fs.rmSync(path.join(ROOT, 'projects', 'task-004-scan-all'), { recursive: true, force: true });
+
+    console.log('TASK-004 scanner test passed');
+  } catch (e) {
+    console.error('TASK-004 scanner test failed:', e.message);
+    if (serverOutput) console.error(serverOutput);
+    process.exitCode = 1;
+  } finally {
+    for (const f of fixtures) {
+      try { f.cleanup(); } catch {}
+    }
+    await cleanup().catch(() => {});
+    child.kill();
+  }
+})();