project-knowledge 0.1.0 → 1.0.0

package/_site/lib/context-pack-builder.js

@@ -10,6 +10,8 @@ const fs = require('fs');
 const path = require('path');
 const crypto = require('crypto');
 const { execGit } = require('./git-runner');
+const aiWorkspace = require('./ai-workspace');
+const { isV3Kb } = require('./kb-v3');
 
 const MAX_FILE_BYTES = 200 * 1024;     // Skip files larger than 200 KB
 const MAX_EXCERPT_BYTES = 8 * 1024;    // Excerpt limited to 8 KB
@@ -121,9 +123,8 @@ function findRelatedDocs(projectRoot, changedFiles) {
   // that intersect the changed files is "related". If frontmatter does not exist
   // (legacy docs), fall back to filename match.
   const out = new Set();
-  const featuresDir = path.join(projectRoot, 'features');
-  const modulesDir = path.join(projectRoot, 'modules');
-  for (const dir of [featuresDir, modulesDir]) {
+  const dirs = [path.join(projectRoot, 'features'), path.join(projectRoot, 'modules'), path.join(projectRoot, 'changes')];
+  for (const dir of dirs) {
     if (!fs.existsSync(dir)) continue;
     let entries;
     try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { continue; }
@@ -187,13 +188,17 @@ async function buildContextPack({ project, runId, trigger, commits = [], options
     seenAbs.add(abs);
   }
 
-  // 1. project-goal.md (highest-priority context)
-  if (fs.existsSync(path.join(projectRoot, 'project-goal.md'))) {
+  // 1. project goal (highest-priority context)
+  if (fs.existsSync(path.join(projectRoot, 'GOAL.md'))) {
+    addEntry('GOAL.md', 'goal', 'highest-priority human-controlled truth');
+  } else if (fs.existsSync(path.join(projectRoot, 'project-goal.md'))) {
     addEntry('project-goal.md', 'goal', 'highest-priority human-controlled truth');
   }
 
-  // 2. project-analysis.md
-  if (fs.existsSync(path.join(projectRoot, 'project-analysis.md'))) {
+  // 2. architecture / project analysis
+  if (fs.existsSync(path.join(projectRoot, 'ARCHITECTURE.md'))) {
+    addEntry('ARCHITECTURE.md', 'analysis', 'current architecture and project description');
+  } else if (fs.existsSync(path.join(projectRoot, 'project-analysis.md'))) {
     addEntry('project-analysis.md', 'analysis', 'current AI-generated description');
   }
 
@@ -258,6 +263,10 @@ async function buildContextPack({ project, runId, trigger, commits = [], options
     createdAt: new Date().toISOString(),
     trigger: trigger || 'initial',
     gitPath,
+    kbPath: projectRoot,
+    sourceBranch: project.currentBranch || null,
+    sourceDefaultBranch: project.defaultBranch || null,
+    sourceRemote: project.remoteUrl || null,
     range,
     diffStat,
     commitCount: commits.length,
@@ -271,10 +280,9 @@ async function buildContextPack({ project, runId, trigger, commits = [], options
   };
 
   // 8. Write to disk
-  const outDir = path.join(projectRoot, '_ai', 'context-packs', pack.runId);
-  if (!isSafePath(projectRoot, path.relative(projectRoot, outDir))) {
-    throw new Error('unsafe output path');
-  }
+  const outDir = (project.kbSchemaVersion === 'v3' || isV3Kb(projectRoot))
+    ? aiWorkspace.contextPackDir(slug, pack.runId)
+    : path.join(projectRoot, '_ai', 'context-packs', pack.runId);
   fs.mkdirSync(outDir, { recursive: true });
   fs.writeFileSync(path.join(outDir, 'context-pack.json'), JSON.stringify(pack, null, 2), 'utf-8');
 

package/_site/lib/draft-apply.js

@@ -14,6 +14,9 @@
 
 const fs = require('fs');
 const path = require('path');
+const aiWorkspace = require('./ai-workspace');
+const { isV3Kb, applyPolicyForPath } = require('./kb-v3');
+const { regenerateIndexes } = require('./index-builder');
 
 const TRUSTED_GOAL_REL = 'project-goal.md';
 
@@ -42,8 +45,32 @@ function isSafeApplyPath(kbPath, rel) {
   return true;
 }
 
+function parseFrontmatter(text) {
+  const match = /^---\r?\n([\s\S]*?)\r?\n---\r?\n/.exec(String(text || ''));
+  if (!match) return { meta: {}, body: String(text || '') };
+  const meta = {};
+  for (const line of match[1].split(/\r?\n/)) {
+    const m = /^([A-Za-z0-9_-]+):\s*(.*)$/.exec(line.trim());
+    if (m) meta[m[1]] = m[2].trim();
+  }
+  return { meta, body: String(text || '').slice(match[0].length) };
+}
+
+function withStampedFrontmatter(content, stamp) {
+  const parsed = parseFrontmatter(content);
+  const meta = { ...parsed.meta };
+  for (const [key, value] of Object.entries(stamp || {})) {
+    if (value != null && value !== '') meta[key] = value;
+  }
+  const lines = ['---'];
+  for (const [key, value] of Object.entries(meta)) lines.push(`${key}: ${String(value).replace(/\r?\n/g, ' ')}`);
+  lines.push('---', '');
+  return lines.join('\n') + parsed.body.replace(/^\r?\n/, '');
+}
+
 function listDraftFiles(kbPath, runId) {
-  const dir = path.join(kbPath, '_ai', 'drafts', runId);
+  const slug = path.basename(kbPath);
+  const dir = aiWorkspace.findExistingDraftDir({ slug, kbPath, runId });
   if (!fs.existsSync(dir)) return [];
   const out = [];
   const walk = (d) => {
@@ -87,21 +114,32 @@ function applyDrafts({ kbPath, slug, runId, drafts, allowGoalEdit, headCommitAtR
   // 1. Validate every draft before touching anything
   const errors = [];
   const prepared = [];
+  const v3 = isV3Kb(kbPath);
   for (const d of drafts) {
     const v = validateDraftSchema(d);
     if (!v.valid) { errors.push({ draft: d && d.path, errors: v.errors }); continue; }
     if (!isSafeApplyPath(kbPath, d.path)) { errors.push({ draft: d.path, errors: ['unsafe path'] }); continue; }
-    if (d.path === TRUSTED_GOAL_REL && !allowGoalEdit) {
+    if (v3) {
+      const policy = applyPolicyForPath(d.path, allowGoalEdit);
+      if (!policy.ok) {
+        errors.push({ draft: d.path, status: policy.status || 422, reviewRequired: !!policy.reviewRequired, errors: [policy.reason] });
+        continue;
+      }
+    } else if (d.path === TRUSTED_GOAL_REL && !allowGoalEdit) {
       errors.push({ draft: d.path, errors: ['refusing to overwrite project-goal.md without allowGoalEdit=true'] });
       continue;
     }
     prepared.push(d);
   }
-  if (errors.length) return { ok: false, status: 422, error: 'invalid drafts', errors };
+  if (errors.length) {
+    const status = errors.some(item => item.status === 409 || item.reviewRequired) ? 409 : 422;
+    return { ok: false, status, error: 'invalid drafts', errors };
+  }
   if (prepared.length === 0) return { ok: false, status: 400, error: 'no valid drafts after validation' };
 
   // 2. Backup everything we will overwrite, into _ai/backups/<runId>/
-  const backupsDir = path.join(kbPath, '_ai', 'backups', runId);
+  const aiRoot = aiWorkspace.ensureProjectAIPath(slug);
+  const backupsDir = path.join(aiRoot, 'backups', runId);
   fs.mkdirSync(backupsDir, { recursive: true });
   const backups = [];
   for (const d of prepared) {
@@ -116,7 +154,12 @@ function applyDrafts({ kbPath, slug, runId, drafts, allowGoalEdit, headCommitAtR
     const dest = path.join(kbPath, d.path);
     try {
       fs.mkdirSync(path.dirname(dest), { recursive: true });
-      fs.writeFileSync(dest, d.content, 'utf-8');
+      const stamp = {
+        sourceBranch: d.sourceBranch || undefined,
+        sourceHeadCommit: d.sourceHeadCommit || undefined,
+      };
+      const content = stamp.sourceBranch || stamp.sourceHeadCommit ? withStampedFrontmatter(d.content, stamp) : d.content;
+      fs.writeFileSync(dest, content, 'utf-8');
       writes.push(d.path);
     } catch (e) {
       failed.push({ path: d.path, error: e.message });
@@ -136,34 +179,39 @@ function applyDrafts({ kbPath, slug, runId, drafts, allowGoalEdit, headCommitAtR
     return { ok: false, status: 500, error: 'partial write failure, rolled back', failed, backups };
   }
 
-  // 4. Update manifest
-  const manifest = readManifest(kbPath) || { schema: 'kb-manifest/v1', project: slug, trustedKnowledge: [], draftAreas: [] };
+  // 4. Update manifest for legacy KBs; V3 relies on structure and regenerated indexes.
+  let manifest = null;
   const today = new Date().toISOString().slice(0, 10);
-  if (!manifest.trustedKnowledge.includes('README.md')) manifest.trustedKnowledge.push('README.md');
-  for (const d of prepared) {
-    if (d.path === TRUSTED_GOAL_REL) {
-      manifest.goal = { path: d.path, status: 'accepted', updatedAt: today };
-    } else if (d.path === 'project-analysis.md') {
-      manifest.analysis = manifest.analysis || {};
-      manifest.analysis.path = d.path;
-      manifest.analysis.updatedAt = today;
-      if (headCommitAtRun) manifest.analysis.lastAnalyzedCommit = headCommitAtRun;
-    } else if (d.path.startsWith('features/')) {
-      if (!manifest.trustedKnowledge.includes('features/')) manifest.trustedKnowledge.push('features/');
-    } else if (d.path.startsWith('modules/')) {
-      if (!manifest.trustedKnowledge.includes('modules/')) manifest.trustedKnowledge.push('modules/');
-    } else if (d.path.startsWith('changes/')) {
-      if (!manifest.trustedKnowledge.includes('changes/')) manifest.trustedKnowledge.push('changes/');
-    } else if (d.path.startsWith('architecture/')) {
-      if (!manifest.trustedKnowledge.includes('architecture/')) manifest.trustedKnowledge.push('architecture/');
+  let indexes = null;
+  if (v3) {
+    indexes = regenerateIndexes(kbPath);
+  } else {
+    manifest = readManifest(kbPath) || { schema: 'kb-manifest/v1', project: slug, trustedKnowledge: [], draftAreas: [] };
+    if (!manifest.trustedKnowledge.includes('README.md')) manifest.trustedKnowledge.push('README.md');
+    for (const d of prepared) {
+      if (d.path === TRUSTED_GOAL_REL) {
+        manifest.goal = { path: d.path, status: 'accepted', updatedAt: today };
+      } else if (d.path === 'project-analysis.md') {
+        manifest.analysis = manifest.analysis || {};
+        manifest.analysis.path = d.path;
+        manifest.analysis.updatedAt = today;
+        if (headCommitAtRun) manifest.analysis.lastAnalyzedCommit = headCommitAtRun;
+      } else if (d.path.startsWith('features/')) {
+        if (!manifest.trustedKnowledge.includes('features/')) manifest.trustedKnowledge.push('features/');
+      } else if (d.path.startsWith('modules/')) {
+        if (!manifest.trustedKnowledge.includes('modules/')) manifest.trustedKnowledge.push('modules/');
+      } else if (d.path.startsWith('changes/')) {
+        if (!manifest.trustedKnowledge.includes('changes/')) manifest.trustedKnowledge.push('changes/');
+      } else if (d.path.startsWith('architecture/')) {
+        if (!manifest.trustedKnowledge.includes('architecture/')) manifest.trustedKnowledge.push('architecture/');
+      }
     }
+    writeManifest(kbPath, manifest);
   }
-  writeManifest(kbPath, manifest);
 
   // 5. Mark the run as applied (caller is responsible for advancing
   //    lastAnalyzedCommit since they know the commit-batch size).
-  const runsDir = path.join(kbPath, '_ai', 'runs');
-  const runPath = path.join(runsDir, `${runId}.json`);
+  const runPath = aiWorkspace.findExistingRunPath({ slug, kbPath, runId });
   if (fs.existsSync(runPath)) {
     try {
       const run = JSON.parse(fs.readFileSync(runPath, 'utf-8'));
@@ -176,13 +224,13 @@ function applyDrafts({ kbPath, slug, runId, drafts, allowGoalEdit, headCommitAtR
     } catch {}
   }
 
-  return { ok: true, applied: writes, backups, manifest };
+  return { ok: true, applied: writes, backups, manifest, indexes };
 }
 
 function rejectDrafts({ kbPath, runId, reason }) {
   if (!kbPath || !runId) return { ok: false, status: 400, error: 'kbPath and runId required' };
-  const runsDir = path.join(kbPath, '_ai', 'runs');
-  const runPath = path.join(runsDir, `${runId}.json`);
+  const slug = path.basename(kbPath);
+  const runPath = aiWorkspace.findExistingRunPath({ slug, kbPath, runId });
   if (!fs.existsSync(runPath)) return { ok: false, status: 404, error: 'run not found' };
   const run = JSON.parse(fs.readFileSync(runPath, 'utf-8'));
   run.applyStatus = 'rejected';
@@ -197,7 +245,8 @@ function readDraftContent(kbPath, runId, rel) {
   if (path.isAbsolute(rel)) return null;
   const norm = rel.replace(/\\/g, '/');
   if (norm.startsWith('../') || norm.includes('/../') || norm.endsWith('/..')) return null;
-  const dir = path.join(kbPath, '_ai', 'drafts', runId);
+  const slug = path.basename(kbPath);
+  const dir = aiWorkspace.findExistingDraftDir({ slug, kbPath, runId });
   const target = path.join(dir, rel);
   // Reject if the resolved target escapes the drafts dir
   const relPath = path.relative(dir, target);

package/_site/lib/index-builder.js

@@ -0,0 +1,100 @@
+const fs = require('fs');
+const path = require('path');
+
+function parseFrontmatter(text) {
+  const match = /^---\r?\n([\s\S]*?)\r?\n---\r?\n/.exec(String(text || ''));
+  if (!match) return {};
+  const meta = {};
+  for (const line of match[1].split(/\r?\n/)) {
+    const m = /^([A-Za-z0-9_-]+):\s*(.*)$/.exec(line.trim());
+    if (!m) continue;
+    let value = m[2].trim();
+    if (/^\[.*\]$/.test(value)) {
+      value = value.slice(1, -1).split(',').map(s => s.trim()).filter(Boolean);
+    }
+    meta[m[1]] = value;
+  }
+  return meta;
+}
+
+function listMarkdown(dir) {
+  if (!fs.existsSync(dir)) return [];
+  return fs.readdirSync(dir, { withFileTypes: true })
+    .filter(entry => entry.isFile() && entry.name.endsWith('.md') && entry.name !== '00-index.md')
+    .map(entry => {
+      const rel = entry.name;
+      const full = path.join(dir, entry.name);
+      const text = fs.readFileSync(full, 'utf-8');
+      const meta = parseFrontmatter(text);
+      const title = meta.title || text.match(/^#\s+(.+)$/m)?.[1] || entry.name.replace(/\.md$/, '');
+      return { rel, full, meta, title, updatedAt: meta.updatedAt || meta.period || '' };
+    });
+}
+
+function tagLine(items) {
+  const tags = new Set();
+  for (const item of items) {
+    const raw = item.meta.tags;
+    if (Array.isArray(raw)) raw.forEach(t => tags.add(t));
+    else if (raw) String(raw).split(',').map(s => s.trim()).filter(Boolean).forEach(t => tags.add(t));
+  }
+  return [...tags].sort();
+}
+
+function writeModuleIndex(kbPath) {
+  const dir = path.join(kbPath, 'modules');
+  fs.mkdirSync(dir, { recursive: true });
+  const items = listMarkdown(dir).sort((a, b) => a.title.localeCompare(b.title));
+  const tags = tagLine(items);
+  const lines = [
+    '# Modules Index',
+    '',
+    tags.length ? `Tags: ${tags.map(t => `\`${t}\``).join(', ')}` : 'Tags: none',
+    '',
+    '| Module | Tags | Updated |',
+    '|---|---|---|',
+  ];
+  for (const item of items) {
+    const tagsText = Array.isArray(item.meta.tags) ? item.meta.tags.join(', ') : (item.meta.tags || '');
+    lines.push(`| [${item.title}](./${item.rel}) | ${tagsText || '-'} | ${item.updatedAt || '-'} |`);
+  }
+  if (!items.length) lines.push('| No modules yet | - | - |');
+  fs.writeFileSync(path.join(dir, '00-index.md'), lines.join('\n') + '\n', 'utf-8');
+  return { path: 'modules/00-index.md', count: items.length };
+}
+
+function writeChangesIndex(kbPath) {
+  const dir = path.join(kbPath, 'changes');
+  fs.mkdirSync(dir, { recursive: true });
+  const items = listMarkdown(dir).sort((a, b) => String(b.updatedAt).localeCompare(String(a.updatedAt)) || a.title.localeCompare(b.title));
+  const tags = tagLine(items);
+  const lines = [
+    '# Changes Index',
+    '',
+    tags.length ? `Tags: ${tags.map(t => `\`${t}\``).join(', ')}` : 'Tags: none',
+    '',
+    '| Change | Tags | Period / Updated |',
+    '|---|---|---|',
+  ];
+  for (const item of items) {
+    const tagsText = Array.isArray(item.meta.tags) ? item.meta.tags.join(', ') : (item.meta.tags || '');
+    lines.push(`| [${item.title}](./${item.rel}) | ${tagsText || '-'} | ${item.updatedAt || '-'} |`);
+  }
+  if (!items.length) lines.push('| No changes yet | - | - |');
+  fs.writeFileSync(path.join(dir, '00-index.md'), lines.join('\n') + '\n', 'utf-8');
+  return { path: 'changes/00-index.md', count: items.length };
+}
+
+function regenerateIndexes(kbPath) {
+  return {
+    modules: writeModuleIndex(kbPath),
+    changes: writeChangesIndex(kbPath),
+  };
+}
+
+module.exports = {
+  parseFrontmatter,
+  regenerateIndexes,
+  writeModuleIndex,
+  writeChangesIndex,
+};

package/_site/lib/job-orchestrator.js

@@ -89,7 +89,7 @@ function projectList(projects, slug) {
     .map(s => projects[s]);
 }
 
-function defaultProjectKbPath(slug) {
+function legacyDefaultProjectKbPath(slug) {
   return path.join('D:\\SanQian.Xu\\project-knowledge-base', 'projects', slug);
 }
 
@@ -112,11 +112,12 @@ async function runScan(projects, slug, job) {
   return { scanned, errors, total: list.length };
 }
 
-async function runInitial(projects, slug, job) {
+async function runInitial(projects, slug, job, options = {}) {
+  const resolveKbPath = options.defaultProjectKbPath || legacyDefaultProjectKbPath;
   const list = projectList(projects, slug);
   let ran = 0, skipped = 0, failed = 0;
   for (const p of list) {
-    const kbPath = p.kbPath || defaultProjectKbPath(p.slug);
+    const kbPath = p.kbPath || resolveKbPath(p.slug);
     if (!fs.existsSync(kbPath)) { skipped++; appendLine(job, `[analyze-initial] ${p.slug} → skipped (no KB)`); continue; }
     const goalPath = path.join(kbPath, 'project-goal.md');
     if (fs.existsSync(goalPath)) { skipped++; appendLine(job, `[analyze-initial] ${p.slug} → skipped (goal already exists)`); continue; }
@@ -127,11 +128,12 @@ async function runInitial(projects, slug, job) {
   return { ran, skipped, failed, total: list.length };
 }
 
-async function runCommits(projects, slug, job) {
+async function runCommits(projects, slug, job, options = {}) {
+  const resolveKbPath = options.defaultProjectKbPath || legacyDefaultProjectKbPath;
   const list = projectList(projects, slug);
   let ran = 0, noop = 0, failed = 0;
   for (const p of list) {
-    const kbPath = p.kbPath || defaultProjectKbPath(p.slug);
+    const kbPath = p.kbPath || resolveKbPath(p.slug);
     if (!fs.existsSync(kbPath)) { appendLine(job, `[analyze-commits] ${p.slug} → skipped (no KB)`); continue; }
     const result = await runCommitAnalysis({ slug: p.slug, ...p, kbPath });
     if (result.ok) {
@@ -154,7 +156,8 @@ function runLegacyScript(slug, job) {
   });
 }
 
-async function runJob({ job, projects, projectsPath, jobsLogPath, writeProjects }) {
+async function runJob({ job, projects, projectsPath, jobsLogPath, writeProjects, defaultProjectKbPath }) {
+  const runOptions = { defaultProjectKbPath };
   if (!job) throw new Error('job required');
   if (!KNOWN_MODES.has(job.mode)) {
     job.status = 'failed';
@@ -181,17 +184,17 @@ async function runJob({ job, projects, projectsPath, jobsLogPath, writeProjects
       job.status = summary.errors > 0 ? 'partial' : 'success';
       exitCode = summary.errors > 0 ? 1 : 0;
     } else if (job.mode === 'analyze-initial') {
-      summary = await runInitial(projects, slug, job);
+      summary = await runInitial(projects, slug, job, runOptions);
       job.status = summary.failed > 0 ? 'partial' : 'success';
       exitCode = summary.failed > 0 ? 1 : 0;
     } else if (job.mode === 'analyze-commits') {
-      summary = await runCommits(projects, slug, job);
+      summary = await runCommits(projects, slug, job, runOptions);
       job.status = summary.failed > 0 ? 'partial' : 'success';
       exitCode = summary.failed > 0 ? 1 : 0;
     } else if (job.mode === 'safe') {
       // scan → analyze-commits. Crucially, no apply step.
       const scanSummary = await runScan(projects, slug, job);
-      const commitSummary = await runCommits(projects, slug, job);
+      const commitSummary = await runCommits(projects, slug, job, runOptions);
       summary = { scan: scanSummary, commits: commitSummary, applied: 0 };
       const totalFailed = scanSummary.errors + commitSummary.failed;
       job.status = totalFailed > 0 ? 'partial' : 'success';

package/_site/lib/kb-v3.js

@@ -0,0 +1,188 @@
+const fs = require('fs');
+const path = require('path');
+const { migrateAIWorkspace, ensureProjectAIPath } = require('./ai-workspace');
+const { regenerateIndexes } = require('./index-builder');
+
+const V3_TOP_LEVEL = ['README.md', 'GOAL.md', 'ARCHITECTURE.md', 'modules', 'changes'];
+const TRUSTED_AUTO_PATHS = ['README.md', 'modules/', 'modules/00-index.md', 'changes/', 'changes/00-index.md'];
+const REVIEW_REQUIRED_PATHS = ['GOAL.md', 'ARCHITECTURE.md'];
+const NEVER_TOUCH_PREFIXES = ['.git/', '.gitignore', '_meta/', '_ai/'];
+
+function todayIso() {
+  return new Date().toISOString().slice(0, 10);
+}
+
+function frontmatter(fields) {
+  const lines = ['---'];
+  for (const [key, value] of Object.entries(fields)) {
+    if (value == null || value === '') continue;
+    if (Array.isArray(value)) lines.push(`${key}: [${value.join(', ')}]`);
+    else lines.push(`${key}: ${String(value).replace(/\r?\n/g, ' ')}`);
+  }
+  lines.push('---', '');
+  return lines.join('\n');
+}
+
+function ensureFile(file, content, created) {
+  if (fs.existsSync(file)) return;
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, content, 'utf-8');
+  if (created) created.push(path.relative(path.dirname(path.dirname(file)), file).replace(/\\/g, '/'));
+}
+
+function initV3ProjectDirs(slug, kbPath) {
+  const base = path.resolve(kbPath);
+  const created = [];
+  fs.mkdirSync(path.join(base, 'modules'), { recursive: true });
+  fs.mkdirSync(path.join(base, 'changes'), { recursive: true });
+  ensureFile(path.join(base, 'README.md'), `# ${slug}\n\nThis knowledge base is managed by Project Knowledge Base.\n\n- [Goal](./GOAL.md)\n- [Architecture](./ARCHITECTURE.md)\n- [Modules](./modules/00-index.md)\n- [Changes](./changes/00-index.md)\n`, created);
+  ensureFile(path.join(base, 'GOAL.md'), `${frontmatter({ title: `${slug} Goal`, status: 'draft', updatedAt: todayIso() })}# ${slug} Goal\n\nTODO: confirm the project goal.\n`, created);
+  ensureFile(path.join(base, 'ARCHITECTURE.md'), `${frontmatter({ title: `${slug} Architecture`, updatedAt: todayIso() })}# ${slug} Architecture\n\nTODO: summarize the project architecture.\n`, created);
+  regenerateIndexes(base);
+  ensureProjectAIPath(slug);
+  return { created, basePath: base, kbSchemaVersion: 'v3', topLevel: V3_TOP_LEVEL.slice() };
+}
+
+function readIfExists(file) {
+  return fs.existsSync(file) ? fs.readFileSync(file, 'utf-8') : '';
+}
+
+function visibleTopLevel(kbPath) {
+  if (!fs.existsSync(kbPath)) return [];
+  return fs.readdirSync(kbPath).filter(name => !name.startsWith('.')).sort();
+}
+
+function isV3Kb(kbPath) {
+  return fs.existsSync(path.join(kbPath, 'GOAL.md')) &&
+    fs.existsSync(path.join(kbPath, 'ARCHITECTURE.md')) &&
+    fs.existsSync(path.join(kbPath, 'modules')) &&
+    fs.existsSync(path.join(kbPath, 'changes'));
+}
+
+function consolidateLegacyCommits({ slug, kbPath }) {
+  const commitsDir = path.join(kbPath, 'commits');
+  const aiRoot = ensureProjectAIPath(slug);
+  const backupDir = path.join(aiRoot, 'legacy-commits');
+  const result = { found: 0, created: [], backupDir };
+  if (!fs.existsSync(commitsDir)) return result;
+  const files = fs.readdirSync(commitsDir).filter(f => f.endsWith('.md') && f !== '00-index.md').sort();
+  result.found = files.length;
+  if (!files.length) return result;
+  fs.mkdirSync(backupDir, { recursive: true });
+  for (const file of files) fs.copyFileSync(path.join(commitsDir, file), path.join(backupDir, file));
+  const bucketCount = Math.min(10, Math.max(1, Math.ceil(files.length / 4)));
+  const bucketSize = Math.ceil(files.length / bucketCount);
+  const changesDir = path.join(kbPath, 'changes');
+  fs.mkdirSync(changesDir, { recursive: true });
+  for (let i = 0; i < bucketCount; i++) {
+    const bucket = files.slice(i * bucketSize, (i + 1) * bucketSize);
+    if (!bucket.length) continue;
+    const rel = `legacy-change-${String(i + 1).padStart(2, '0')}.md`;
+    const title = `Legacy Change ${i + 1}`;
+    const body = [
+      frontmatter({
+        title,
+        tags: ['legacy-migration'],
+        updatedAt: todayIso(),
+        aggregatedFrom: `[${bucket.map(f => `commits/${f}`).join(', ')}]`,
+      }),
+      `# ${title}`,
+      '',
+      'This document consolidates legacy per-commit knowledge during the KB v3 migration.',
+      '',
+      '## Aggregated Commits',
+      '',
+      ...bucket.map(file => `- \`commits/${file}\``),
+      '',
+    ].join('\n');
+    fs.writeFileSync(path.join(changesDir, rel), body, 'utf-8');
+    result.created.push(`changes/${rel}`);
+  }
+  return result;
+}
+
+function removeV2OnlyItems(kbPath) {
+  const removed = [];
+  const names = [
+    '_ai', 'kb-manifest.json', 'project-goal.md', 'project-analysis.md', 'framework.md',
+    'architecture', 'commits', 'features', 'operations', 'quality', 'requirements', 'references',
+  ];
+  for (const name of names) {
+    const target = path.join(kbPath, name);
+    if (fs.existsSync(target)) {
+      fs.rmSync(target, { recursive: true, force: true });
+      removed.push(name);
+    }
+  }
+  return removed;
+}
+
+function migrateToV3({ slug, kbPath, preserveLegacyAI = true }) {
+  const base = path.resolve(kbPath);
+  fs.mkdirSync(base, { recursive: true });
+  const aiMigration = migrateAIWorkspace({ slug, kbPath: base, preserveOriginal: preserveLegacyAI });
+
+  const oldGoal = readIfExists(path.join(base, 'project-goal.md'));
+  const oldFramework = readIfExists(path.join(base, 'framework.md'));
+  const oldArch = readIfExists(path.join(base, 'architecture', 'overview.md'));
+  const oldAnalysis = readIfExists(path.join(base, 'project-analysis.md'));
+
+  const init = initV3ProjectDirs(slug, base);
+  if (oldGoal && !oldGoal.includes('TODO: confirm the project goal')) {
+    fs.writeFileSync(path.join(base, 'GOAL.md'), oldGoal, 'utf-8');
+  }
+  const archParts = [
+    oldFramework && `## Migrated Framework\n\n${oldFramework}`,
+    oldArch && `## Migrated Architecture Overview\n\n${oldArch}`,
+    oldAnalysis && `## Migrated Project Analysis\n\n${oldAnalysis}`,
+  ].filter(Boolean);
+  if (archParts.length) {
+    fs.writeFileSync(path.join(base, 'ARCHITECTURE.md'), `${frontmatter({ title: `${slug} Architecture`, updatedAt: todayIso() })}# ${slug} Architecture\n\n${archParts.join('\n\n')}\n`, 'utf-8');
+  }
+  const commits = consolidateLegacyCommits({ slug, kbPath: base });
+  const removed = removeV2OnlyItems(base);
+  regenerateIndexes(base);
+  return {
+    ok: true,
+    slug,
+    kbPath: base,
+    kbSchemaVersion: 'v3',
+    init,
+    aiMigration,
+    legacyCommits: commits,
+    removed,
+    topLevel: visibleTopLevel(base),
+  };
+}
+
+function normalizeApplyPath(rel) {
+  return String(rel || '').replace(/\\/g, '/').replace(/^\/+/, '');
+}
+
+function applyPolicyForPath(rel, allowGoalEdit = false) {
+  const norm = normalizeApplyPath(rel);
+  if (!norm || norm.includes('../') || norm.startsWith('../')) return { ok: false, reason: 'unsafe path' };
+  if (NEVER_TOUCH_PREFIXES.some(prefix => norm === prefix.replace(/\/$/, '') || norm.startsWith(prefix))) {
+    return { ok: false, reason: 'path is reserved and cannot be written by AI' };
+  }
+  if (REVIEW_REQUIRED_PATHS.includes(norm)) {
+    return allowGoalEdit ? { ok: true, reviewRequired: true } : { ok: false, status: 409, reviewRequired: true, reason: `${norm} requires human review` };
+  }
+  if (norm === 'README.md') return { ok: true, autoApply: true };
+  if (norm.startsWith('modules/') || norm.startsWith('changes/')) return { ok: true, autoApply: true };
+  return { ok: false, reason: `path is outside KB v3 trusted allowlist: ${norm}` };
+}
+
+module.exports = {
+  V3_TOP_LEVEL,
+  TRUSTED_AUTO_PATHS,
+  REVIEW_REQUIRED_PATHS,
+  NEVER_TOUCH_PREFIXES,
+  initV3ProjectDirs,
+  migrateToV3,
+  consolidateLegacyCommits,
+  isV3Kb,
+  visibleTopLevel,
+  applyPolicyForPath,
+  frontmatter,
+};