@sanqianx/project-knowledge 5.0.23 → 5.0.25

package/_site/lib/kb-framework.js

@@ -1,191 +1,191 @@
-const fs = require('fs');
-const path = require('path');
-const { migrateAIWorkspace, ensureProjectAIPath } = require('./ai-workspace');
-const { regenerateIndexes } = require('./index-builder');
-
-const PROJECT_SCHEMA_VERSION = 'minimal';
-const KB_FRAMEWORK_SCHEMA = 'minimal-kb/v1';
-const TOP_LEVEL = ['README.md', 'GOAL.md', 'ARCHITECTURE.md', 'modules', 'changes'];
-
-function todayIso() {
-  return new Date().toISOString().slice(0, 10);
-}
-
-function readTemplate(name) {
-  const file = path.resolve(__dirname, '..', '..', 'templates', name);
-  if (!fs.existsSync(file)) return null;
-  return fs.readFileSync(file, 'utf-8');
-}
-
-function renderTemplate(name, vars, fallback) {
-  const tpl = readTemplate(name) || fallback;
-  return String(tpl || '').replace(/__([A-Z_][A-Z0-9_]*)__/g, (_, key) => (
-    key in vars ? String(vars[key]) : `__${key}__`
-  ));
-}
-
-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, base) {
-  if (fs.existsSync(file)) return;
-  fs.mkdirSync(path.dirname(file), { recursive: true });
-  fs.writeFileSync(file, content, 'utf-8');
-  if (created) created.push(path.relative(base, file).replace(/\\/g, '/'));
-}
-
-function initProjectDirs(slug, kbPath) {
-  const base = path.resolve(kbPath);
-  // Import only declares the external project directory. Real Markdown and
-  // collection directories are created lazily by validated promotion; an
-  // empty/TODO skeleton would turn guesses into durable project knowledge.
-  fs.mkdirSync(base, { recursive: true });
-  return {
-    created: [],
-    basePath: base,
-    kbSchemaVersion: PROJECT_SCHEMA_VERSION,
-    frameworkSchema: KB_FRAMEWORK_SCHEMA,
-    topLevel: TOP_LEVEL.slice(),
-    lazy: true,
-  };
-}
-
-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 isCurrentKb(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({
-        schema: KB_FRAMEWORK_SCHEMA,
-        title,
-        tags: ['legacy-migration'],
-        updatedAt: todayIso(),
-        aggregatedFrom: `[${bucket.map(f => `commits/${f}`).join(', ')}]`,
-      }),
-      `# ${title}`,
-      '',
-      '## Development Intent',
-      '',
-      'This change was generated by consolidating older per-commit records. No raw prompts are preserved.',
-      '',
-      '## Implementation Result',
-      '',
-      'Legacy commit notes were grouped into this durable change summary.',
-      '',
-      '## Evidence',
-      '',
-      ...bucket.map(file => `- \`commits/${file}\``),
-      '',
-    ].join('\n');
-    fs.writeFileSync(path.join(changesDir, rel), body, 'utf-8');
-    result.created.push(`changes/${rel}`);
-  }
-  return result;
-}
-
-function removeLegacyItems(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 migrateToFramework({ 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 = initProjectDirs(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({ schema: KB_FRAMEWORK_SCHEMA, title: `${slug} Architecture`, updatedAt: todayIso() })}# ${slug} Architecture\n\n${archParts.join('\n\n')}\n`, 'utf-8');
-  }
-  const commits = consolidateLegacyCommits({ slug, kbPath: base });
-  const removed = removeLegacyItems(base);
-  regenerateIndexes(base);
-  return {
-    ok: true,
-    slug,
-    kbPath: base,
-    kbSchemaVersion: PROJECT_SCHEMA_VERSION,
-    frameworkSchema: KB_FRAMEWORK_SCHEMA,
-    init,
-    aiMigration,
-    legacyCommits: commits,
-    removed,
-    topLevel: visibleTopLevel(base),
-  };
-}
-
-module.exports = {
-  PROJECT_SCHEMA_VERSION,
-  KB_FRAMEWORK_SCHEMA,
-  TOP_LEVEL,
-  initProjectDirs,
-  migrateToFramework,
-  consolidateLegacyCommits,
-  isCurrentKb,
-  visibleTopLevel,
-  frontmatter,
-};
+const fs = require('fs');
+const path = require('path');
+const { migrateAIWorkspace, ensureProjectAIPath } = require('./ai-workspace');
+const { regenerateIndexes } = require('./index-builder');
+
+const PROJECT_SCHEMA_VERSION = 'minimal';
+const KB_FRAMEWORK_SCHEMA = 'minimal-kb/v1';
+const TOP_LEVEL = ['README.md', 'GOAL.md', 'ARCHITECTURE.md', 'modules', 'changes'];
+
+function todayIso() {
+  return new Date().toISOString().slice(0, 10);
+}
+
+function readTemplate(name) {
+  const file = path.resolve(__dirname, '..', '..', 'templates', name);
+  if (!fs.existsSync(file)) return null;
+  return fs.readFileSync(file, 'utf-8');
+}
+
+function renderTemplate(name, vars, fallback) {
+  const tpl = readTemplate(name) || fallback;
+  return String(tpl || '').replace(/__([A-Z_][A-Z0-9_]*)__/g, (_, key) => (
+    key in vars ? String(vars[key]) : `__${key}__`
+  ));
+}
+
+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, base) {
+  if (fs.existsSync(file)) return;
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, content, 'utf-8');
+  if (created) created.push(path.relative(base, file).replace(/\\/g, '/'));
+}
+
+function initProjectDirs(slug, kbPath) {
+  const base = path.resolve(kbPath);
+  // Import only declares the external project directory. Real Markdown and
+  // collection directories are created lazily by validated promotion; an
+  // empty/TODO skeleton would turn guesses into durable project knowledge.
+  fs.mkdirSync(base, { recursive: true });
+  return {
+    created: [],
+    basePath: base,
+    kbSchemaVersion: PROJECT_SCHEMA_VERSION,
+    frameworkSchema: KB_FRAMEWORK_SCHEMA,
+    topLevel: TOP_LEVEL.slice(),
+    lazy: true,
+  };
+}
+
+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 isCurrentKb(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({
+        schema: KB_FRAMEWORK_SCHEMA,
+        title,
+        tags: ['legacy-migration'],
+        updatedAt: todayIso(),
+        aggregatedFrom: `[${bucket.map(f => `commits/${f}`).join(', ')}]`,
+      }),
+      `# ${title}`,
+      '',
+      '## Development Intent',
+      '',
+      'This change was generated by consolidating older per-commit records. No raw prompts are preserved.',
+      '',
+      '## Implementation Result',
+      '',
+      'Legacy commit notes were grouped into this durable change summary.',
+      '',
+      '## Evidence',
+      '',
+      ...bucket.map(file => `- \`commits/${file}\``),
+      '',
+    ].join('\n');
+    fs.writeFileSync(path.join(changesDir, rel), body, 'utf-8');
+    result.created.push(`changes/${rel}`);
+  }
+  return result;
+}
+
+function removeLegacyItems(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 migrateToFramework({ 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 = initProjectDirs(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({ schema: KB_FRAMEWORK_SCHEMA, title: `${slug} Architecture`, updatedAt: todayIso() })}# ${slug} Architecture\n\n${archParts.join('\n\n')}\n`, 'utf-8');
+  }
+  const commits = consolidateLegacyCommits({ slug, kbPath: base });
+  const removed = removeLegacyItems(base);
+  regenerateIndexes(base);
+  return {
+    ok: true,
+    slug,
+    kbPath: base,
+    kbSchemaVersion: PROJECT_SCHEMA_VERSION,
+    frameworkSchema: KB_FRAMEWORK_SCHEMA,
+    init,
+    aiMigration,
+    legacyCommits: commits,
+    removed,
+    topLevel: visibleTopLevel(base),
+  };
+}
+
+module.exports = {
+  PROJECT_SCHEMA_VERSION,
+  KB_FRAMEWORK_SCHEMA,
+  TOP_LEVEL,
+  initProjectDirs,
+  migrateToFramework,
+  consolidateLegacyCommits,
+  isCurrentKb,
+  visibleTopLevel,
+  frontmatter,
+};

package/_site/lib/kb-validator.js

@@ -1,124 +1,124 @@
-// KB Validator
-//
-// The current knowledge base framework is intentionally small:
-//
-//   README.md
-//   GOAL.md
-//   ARCHITECTURE.md
-//   modules/
-//     00-index.md
-//   changes/
-//     00-index.md
-//
-// Everything inside this layout is trusted project memory. AI run state,
-// context packs, backups, and Claude workbench sessions live under the
-// application data directory, outside the project KB.
-
-const fs = require('fs');
-const path = require('path');
-const { KB_FRAMEWORK_SCHEMA, PROJECT_SCHEMA_VERSION, TOP_LEVEL } = require('./kb-framework');
-
-function walkTrustedFiles(root, dir = root, prefix = '') {
-  const out = [];
-  let entries = [];
-  try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { return out; }
-  for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
-    if (entry.name.startsWith('.')) continue;
-    if (entry.name === '_ai' || entry.name === '_meta' || entry.name === 'node_modules') continue;
-    const rel = (prefix ? `${prefix}/` : '') + entry.name;
-    const full = path.join(dir, entry.name);
-    if (entry.isDirectory()) out.push(...walkTrustedFiles(root, full, rel));
-    else if (entry.isFile() && entry.name.endsWith('.md')) {
-      out.push({ path: rel, content: fs.readFileSync(full, 'utf-8'), size: fs.statSync(full).size });
-    }
-  }
-  return out;
-}
-
-function validateKb(kbPath) {
-  const info = {
-    kbPath,
-    schemaVersion: PROJECT_SCHEMA_VERSION,
-    frameworkSchema: KB_FRAMEWORK_SCHEMA,
-    goalStatus: 'unknown',
-    architectureStatus: 'unknown',
-    trustedKnowledgeEntries: 0,
-  };
-
-  if (!kbPath || !fs.existsSync(kbPath)) {
-    return { ok: false, status: 400, error: `kbPath does not exist: ${kbPath}` };
-  }
-  if (!fs.statSync(kbPath).isDirectory()) {
-    return { ok: false, status: 400, error: `kbPath is not a directory: ${kbPath}` };
-  }
-
-  const errors = [];
-  const warnings = [];
-  const required = [
-    ['README.md', 'file'],
-    ['GOAL.md', 'file'],
-    ['ARCHITECTURE.md', 'file'],
-    ['modules', 'dir'],
-    ['changes', 'dir'],
-    ['modules/00-index.md', 'file'],
-    ['changes/00-index.md', 'file'],
-  ];
-  for (const [rel, kind] of required) {
-    const abs = path.join(kbPath, rel);
-    if (!fs.existsSync(abs)) {
-      errors.push(`${rel} missing`);
-      continue;
-    }
-    const stat = fs.statSync(abs);
-    if (kind === 'file' && !stat.isFile()) errors.push(`${rel} must be a file`);
-    if (kind === 'dir' && !stat.isDirectory()) errors.push(`${rel} must be a directory`);
-  }
-
-  const top = fs.readdirSync(kbPath).filter(name => !name.startsWith('.')).sort();
-  const unexpected = top.filter(name => !TOP_LEVEL.includes(name));
-  if (unexpected.length) errors.push(`unexpected top-level KB items: ${unexpected.join(', ')}`);
-  if (fs.existsSync(path.join(kbPath, '_ai'))) errors.push('_ai must not live inside a project KB');
-  if (fs.existsSync(path.join(kbPath, 'kb-manifest.json'))) errors.push('kb-manifest.json is not part of the current KB framework');
-
-  info.goalStatus = fs.existsSync(path.join(kbPath, 'GOAL.md')) ? 'present' : 'missing';
-  info.architectureStatus = fs.existsSync(path.join(kbPath, 'ARCHITECTURE.md')) ? 'present' : 'missing';
-  info.trustedKnowledgeEntries = walkTrustedFiles(kbPath).length;
-
-  return {
-    ok: errors.length === 0,
-    status: errors.length ? 422 : 200,
-    info,
-    errors,
-    warnings,
-  };
-}
-
-function buildPrContextPack(kbPath) {
-  const validation = validateKb(kbPath);
-  if (!validation.ok) return { ok: false, status: validation.status || 422, error: 'kb invalid', validation };
-  const files = walkTrustedFiles(kbPath);
-  const readFile = rel => files.find(item => item.path === rel) || null;
-  return {
-    ok: true,
-    pack: {
-      schema: 'pr-context-pack/v1',
-      frameworkSchema: KB_FRAMEWORK_SCHEMA,
-      generatedAt: new Date().toISOString(),
-      project: path.basename(kbPath),
-      goal: readFile('GOAL.md'),
-      architecture: readFile('ARCHITECTURE.md'),
-      indexes: {
-        modules: readFile('modules/00-index.md'),
-        changes: readFile('changes/00-index.md'),
-      },
-      trustedKnowledge: files,
-    },
-  };
-}
-
-module.exports = {
-  KB_FRAMEWORK_SCHEMA,
-  validateKb,
-  buildPrContextPack,
-  walkTrustedFiles,
-};
+// KB Validator
+//
+// The current knowledge base framework is intentionally small:
+//
+//   README.md
+//   GOAL.md
+//   ARCHITECTURE.md
+//   modules/
+//     00-index.md
+//   changes/
+//     00-index.md
+//
+// Everything inside this layout is trusted project memory. AI run state,
+// context packs, backups, and Claude workbench sessions live under the
+// application data directory, outside the project KB.
+
+const fs = require('fs');
+const path = require('path');
+const { KB_FRAMEWORK_SCHEMA, PROJECT_SCHEMA_VERSION, TOP_LEVEL } = require('./kb-framework');
+
+function walkTrustedFiles(root, dir = root, prefix = '') {
+  const out = [];
+  let entries = [];
+  try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { return out; }
+  for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+    if (entry.name.startsWith('.')) continue;
+    if (entry.name === '_ai' || entry.name === '_meta' || entry.name === 'node_modules') continue;
+    const rel = (prefix ? `${prefix}/` : '') + entry.name;
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) out.push(...walkTrustedFiles(root, full, rel));
+    else if (entry.isFile() && entry.name.endsWith('.md')) {
+      out.push({ path: rel, content: fs.readFileSync(full, 'utf-8'), size: fs.statSync(full).size });
+    }
+  }
+  return out;
+}
+
+function validateKb(kbPath) {
+  const info = {
+    kbPath,
+    schemaVersion: PROJECT_SCHEMA_VERSION,
+    frameworkSchema: KB_FRAMEWORK_SCHEMA,
+    goalStatus: 'unknown',
+    architectureStatus: 'unknown',
+    trustedKnowledgeEntries: 0,
+  };
+
+  if (!kbPath || !fs.existsSync(kbPath)) {
+    return { ok: false, status: 400, error: `kbPath does not exist: ${kbPath}` };
+  }
+  if (!fs.statSync(kbPath).isDirectory()) {
+    return { ok: false, status: 400, error: `kbPath is not a directory: ${kbPath}` };
+  }
+
+  const errors = [];
+  const warnings = [];
+  const required = [
+    ['README.md', 'file'],
+    ['GOAL.md', 'file'],
+    ['ARCHITECTURE.md', 'file'],
+    ['modules', 'dir'],
+    ['changes', 'dir'],
+    ['modules/00-index.md', 'file'],
+    ['changes/00-index.md', 'file'],
+  ];
+  for (const [rel, kind] of required) {
+    const abs = path.join(kbPath, rel);
+    if (!fs.existsSync(abs)) {
+      errors.push(`${rel} missing`);
+      continue;
+    }
+    const stat = fs.statSync(abs);
+    if (kind === 'file' && !stat.isFile()) errors.push(`${rel} must be a file`);
+    if (kind === 'dir' && !stat.isDirectory()) errors.push(`${rel} must be a directory`);
+  }
+
+  const top = fs.readdirSync(kbPath).filter(name => !name.startsWith('.')).sort();
+  const unexpected = top.filter(name => !TOP_LEVEL.includes(name));
+  if (unexpected.length) errors.push(`unexpected top-level KB items: ${unexpected.join(', ')}`);
+  if (fs.existsSync(path.join(kbPath, '_ai'))) errors.push('_ai must not live inside a project KB');
+  if (fs.existsSync(path.join(kbPath, 'kb-manifest.json'))) errors.push('kb-manifest.json is not part of the current KB framework');
+
+  info.goalStatus = fs.existsSync(path.join(kbPath, 'GOAL.md')) ? 'present' : 'missing';
+  info.architectureStatus = fs.existsSync(path.join(kbPath, 'ARCHITECTURE.md')) ? 'present' : 'missing';
+  info.trustedKnowledgeEntries = walkTrustedFiles(kbPath).length;
+
+  return {
+    ok: errors.length === 0,
+    status: errors.length ? 422 : 200,
+    info,
+    errors,
+    warnings,
+  };
+}
+
+function buildPrContextPack(kbPath) {
+  const validation = validateKb(kbPath);
+  if (!validation.ok) return { ok: false, status: validation.status || 422, error: 'kb invalid', validation };
+  const files = walkTrustedFiles(kbPath);
+  const readFile = rel => files.find(item => item.path === rel) || null;
+  return {
+    ok: true,
+    pack: {
+      schema: 'pr-context-pack/v1',
+      frameworkSchema: KB_FRAMEWORK_SCHEMA,
+      generatedAt: new Date().toISOString(),
+      project: path.basename(kbPath),
+      goal: readFile('GOAL.md'),
+      architecture: readFile('ARCHITECTURE.md'),
+      indexes: {
+        modules: readFile('modules/00-index.md'),
+        changes: readFile('changes/00-index.md'),
+      },
+      trustedKnowledge: files,
+    },
+  };
+}
+
+module.exports = {
+  KB_FRAMEWORK_SCHEMA,
+  validateKb,
+  buildPrContextPack,
+  walkTrustedFiles,
+};