@descix/cli 1.0.1 → 1.0.3

package/lib/core/Hydrator.js

@@ -16,6 +16,38 @@
 import * as fs from 'fs/promises';
 import * as path from 'path';
 import { fileURLToPath } from 'url';
+
+import { SITE_SCAFFOLD_DIR } from '@descix/app-sdk/scaffold';
+
+/**
+ * ONE OWNER for scaffold path resolution. Hydrator.js lives at descix-cli/lib/core/, so two
+ * '..' walks reach the CLI package root. Two functions used to resolve this independently and
+ * they DISAGREED — copyScaffold walked two, getAvailableScaffolds walked four (and used a
+ * hand-rolled import.meta.url.replace('file://','') instead of fileURLToPath). The four-walk
+ * path does not exist, so getAvailableScaffolds returned [] on every call, and its bare catch
+ * made a path bug indistinguishable from "no scaffolds are installed".
+ *
+ * The SITE scaffold is not one of ours: it is app-side browser code whose generated
+ * `DeSciXAppSDK.js` is produced from @descix/app-sdk's template + bridgeResolver, so that
+ * package OWNS the directory and exports its location. The CLI consumes the constant rather
+ * than re-spelling the path, which is what lets `@descix/sdk/app`'s bin scaffold the very same
+ * bytes without a second copy existing anywhere.
+ */
+const CLI_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
+
+/**
+ * The scaffold registry — ONE owner of BOTH "which scaffold types exist" and "where each one
+ * lives". These used to be two facts derived in two places: a hand-kept `validTypes` array
+ * inside copyScaffold, and a readdir of the templates directory inside getAvailableScaffolds.
+ * Two derivations of one fact disagree silently, and this pair was primed to: moving `site`
+ * out of the CLI would have left `validTypes` still advertising it while the readdir stopped
+ * reporting it, and the error a developer saw would have named a missing directory rather
+ * than the move.
+ */
+const SCAFFOLD_DIRS = {
+  site: SITE_SCAFFOLD_DIR,
+  microservice: path.join(CLI_ROOT, 'templates', 'scaffolds', 'microservice'),
+};
 import { google } from 'googleapis';
 import * as driveADC from '../google-storage-adc.js';
 
@@ -254,27 +286,35 @@ async function pullFolder(localPath, driveFolderId, options = {}) {
  * @returns {Promise<{pulled: number, converted: number, skipped: number, unchanged: number}>}
  */
 export async function hydrateKb(config, options = {}) {
-  const { workspaceRoot, communityId, appId, kbId = 'General', baseFolderId, localPath } = config;
-  const { 
-    verbose = false, 
+  const { workspaceRoot, communityId, appId, kbId = 'General', baseFolderId, directFolderId, localPath } = config;
+  const {
+    verbose = false,
     mergeMode = 'merge',
     skipUnchanged = true,
     dryRun = false,
     onProgress = null
   } = options;
-  
+
   // Verify ADC auth
   await driveADC.verifyDriveAuth();
-  
-  // Navigate to KB folder using template path
-  const kbPath = `${communityId}/${appId}/kb/${kbId}`;
-  const kbDriveFolderId = await driveADC.findFolderByPath(baseFolderId, kbPath);
-  
-  if (!kbDriveFolderId) {
-    throw new Error(
-      `KB folder not found at path: ${kbPath}\n` +
-      'Ensure the app was created from template and the KB folder exists in Drive.'
-    );
+
+  // Resolve the KB Drive folder: direct override or navigate via base_folder_id
+  let kbDriveFolderId;
+  if (directFolderId) {
+    // --folder override: use the provided folder ID directly (arbitrary Drive folder)
+    kbDriveFolderId = directFolderId;
+    if (verbose) console.log(`  Using override folder: ${directFolderId}`);
+  } else {
+    // Standard path: navigate to KB folder using template path
+    const kbPath = `${communityId}/${appId}/kb/${kbId}`;
+    kbDriveFolderId = await driveADC.findFolderByPath(baseFolderId, kbPath);
+
+    if (!kbDriveFolderId) {
+      throw new Error(
+        `KB folder not found at path: ${kbPath}\n` +
+        'Ensure the app was created from template and the KB folder exists in Drive.'
+      );
+    }
   }
   
   // Prepare local directories with new structure
@@ -692,15 +732,13 @@ export async function checkStagingFiles(stagingDir) {
 export async function copyScaffold(scaffoldType, appPath, options = {}) {
   const { verbose = false, force = false } = options;
   
-  const validTypes = ['site', 'microservice'];
-  if (!validTypes.includes(scaffoldType)) {
-    throw new Error(`Invalid scaffold type: ${scaffoldType}. Valid types: ${validTypes.join(', ')}`);
+  const scaffoldDir = SCAFFOLD_DIRS[scaffoldType];
+  if (!scaffoldDir) {
+    throw new Error(
+      `Invalid scaffold type: ${scaffoldType}. Valid types: ${Object.keys(SCAFFOLD_DIRS).join(', ')}`
+    );
   }
   
-  // Find scaffold template directory (templates live inside CLI package)
-  const cliRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..', '..');
-  const scaffoldDir = path.join(cliRoot, 'templates', 'scaffolds', scaffoldType);
-  
   // Check if scaffold exists
   try {
     await fs.access(scaffoldDir);
@@ -773,15 +811,23 @@ async function copyDir(src, dest, stats, verbose) {
  * @returns {Promise<string[]>}
  */
 export async function getAvailableScaffolds() {
-  const sdkRoot = path.resolve(path.dirname(import.meta.url.replace('file://', '')), '..', '..', '..', '..');
-  const scaffoldsDir = path.join(sdkRoot, 'templates', 'scaffolds');
-  
-  try {
-    const entries = await fs.readdir(scaffoldsDir, { withFileTypes: true });
-    return entries.filter(e => e.isDirectory()).map(e => e.name);
-  } catch {
-    return [];
+  // FAIL LOUD per entry: an unreadable scaffold directory in a shipped CLI is a packaging
+  // failure, not "no scaffolds". Swallowing it to [] is what hid the original path bug — the
+  // caller could not tell a broken install from an empty one. Name the type, the owning
+  // package and the underlying error, because `site` now ships from a DIFFERENT package than
+  // `microservice` and "which package is broken" is the first thing you need to know.
+  for (const [type, dir] of Object.entries(SCAFFOLD_DIRS)) {
+    try {
+      await fs.access(dir);
+    } catch (err) {
+      throw new Error(
+        `Scaffold templates for "${type}" are unreadable at ${dir} (${err.code || err.message}). ` +
+        `This is a broken installation of ` +
+        `${type === 'site' ? '@descix/app-sdk' : '@descix/cli'}, not an empty template set.`
+      );
+    }
   }
+  return Object.keys(SCAFFOLD_DIRS);
 }
 
 // Named exports for functions not already exported inline

package/lib/core/ManifestLoader.js

@@ -0,0 +1,533 @@
+/**
+ * ManifestLoader - Load and validate corpus sync manifests
+ *
+ * Manifests declare a *view* over git-managed files for RAG indexing.
+ * Files stay in place — no staging. Git blob SHAs handle versioning.
+ * Pinecone metadata handles multi-tenancy (CEO-D12).
+ *
+ * Manifest location convention:
+ *   {app_root}/.descix/manifests/{kb_name}.json
+ *
+ * workspace.json `localPath` provides the app root.
+ * The CLI discovers manifests at `{localPath}/.descix/manifests/`.
+ */
+
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import { execFileSync } from 'child_process';
+// Canonical doc_class taxonomy lives in CorpusDenyLint — import it, never re-list.
+import { PUBLISHABLE_DOC_CLASSES, DENY_DOC_CLASSES } from './CorpusDenyLint.js';
+
+// Valid publish tiers (model §1). "I" internal (default), "P" public, "U" user.
+const PUBLISH_TIERS = new Set(['P', 'I', 'U']);
+
+// ============ Canonical Manifest Schema (WS-EVP-DESCIX-KB-CLEANUP item 5) ============
+//
+// ONE canonical corpus-manifest schema. Historically two families shared
+// `.descix/manifests/*.json` with drifting per-source field names — the DeSciX-family
+// (`tier`/`doc_type`/`syncignore`/`raw_path`) and the EGPT-research family (which also used
+// `src_path`). Because every field except `path` was optional, the loader SILENTLY accepted both
+// AND silently ignored any unrecognized/misspelled field (the same fail-loud gap as the KB command
+// params — a typo'd `synchignore` produced an empty syncignore with no signal). This is the single
+// source of truth for the recognized field set. Consumers (the walker, the deny-lint, a conformance
+// test) key off these exports so the schema can never drift by hand again.
+//
+// Deprecation window: unrecognized fields and deprecated aliases WARN (they do not throw) so both
+// legacy formats keep syncing. `src_path` is normalized to its canonical name `raw_path` at load.
+// The schema doc lives at V2_docs/architecture/corpus-manifest-schema.md.
+export const CANONICAL_SOURCE_FIELDS = new Set([
+  'path', 'repo', 'ref', 'tier', 'doc_type', 'syncignore',
+  'doc_class', 'license_basis', 'lint_exempt', 'exempt_reason', 'raw_path',
+]);
+
+/**
+ * The agreed shape of a manifest source (interface-ws-c4-I2-manifest-source), stated ONCE.
+ * Refusal messages quote from it, so the contract and its enforcement cannot drift apart.
+ */
+export const SOURCE_SHAPE_CONTRACT =
+  "A manifest source names WHERE its content comes from, and is synced by fetching that ref - " +
+  "never by reading an adjacent working tree. A source is exactly one of two shapes. IN-REPO: " +
+  "omit `repo`; `path` is repo-root-relative within the manifest's OWN repository, fetched at " +
+  "`ref`. CROSS-REPO: `repo` is REQUIRED and is an owner/name slug (e.g. 'eabadir/unk'), never a " +
+  "URL; `path` is repo-root-relative within that repository, fetched at `ref`. Naming your OWN " +
+  "repository explicitly in `repo` is REFUSED - omission is the single spelling of 'here', an " +
+  "explicit slug the single spelling of 'elsewhere'. A `path` beginning with '../' is REFUSED " +
+  "naming the migration: adjacency reads a working tree, so the source's `ref` is not honored and " +
+  "the provenance it claims is false. `ref` may be a branch, tag or sha; a mutable branch ref is " +
+  "legal, and sync-state records the RESOLVED COMMIT SHA actually synced, so provenance is exact " +
+  "even when the ref moves. `path` is a literal - no globs; `syncignore` already owns exclusion.";
+
+/** The ref a source is walked at when it names none. ONE owner — consumers import it. */
+export const DEFAULT_SOURCE_REF = 'main';
+
+// Glob metacharacters. `path` is a LITERAL — `syncignore` already owns exclusion, so a glob in
+// `path` is a second, silently-diverging spelling of the same intent.
+const GLOB_CHARS = /[*?[\]{}]/;
+
+/**
+ * Normalize any git remote URL spelling to ONE canonical `owner/name` slug.
+ *
+ * The single owner of "which repository is this". Every caller derives from here — deriving the
+ * slug a second way is how the self-naming refusal would silently start disagreeing with itself.
+ *
+ * Handles: https://host/owner/name(.git), git@host:owner/name(.git), ssh://git@host/owner/name(.git)
+ *
+ * @param {string|null|undefined} url - a git remote URL
+ * @returns {string|null} `owner/name`, or null when no slug can be read
+ */
+export function repoSlugFromRemoteUrl(url) {
+  if (!url || typeof url !== 'string') return null;
+  let s = url.trim();
+  if (!s) return null;
+  s = s.replace(/\.git$/, '');
+  // scp-style: git@host:owner/name
+  const scp = s.match(/^[^/]+@[^:/]+:(.+)$/);
+  if (scp) s = scp[1];
+  else {
+    // URL-style: scheme://[user@]host/owner/name
+    const u = s.match(/^[a-z][a-z0-9+.-]*:\/\/[^/]*\/(.+)$/i);
+    if (u) s = u[1];
+  }
+  const parts = s.split('/').filter(Boolean);
+  if (parts.length < 2) return null;
+  return `${parts[parts.length - 2]}/${parts[parts.length - 1]}`;
+}
+
+/**
+ * Read the `owner/name` slug of the repository that physically CONTAINS a directory.
+ *
+ * @param {string} dir - a directory inside the repository
+ * @returns {string|null} the slug, or null when there is no repo / no `origin` remote
+ */
+export function detectRepoSlug(dir) {
+  try {
+    const url = execFileSync('git', ['remote', 'get-url', 'origin'], {
+      cwd: dir, encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'],
+    }).trim();
+    return repoSlugFromRemoteUrl(url);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Enforce the two-shape source contract on ONE source entry.
+ *
+ * @param {Object} src - raw source entry
+ * @param {number} i - index (for message context)
+ * @param {string} filePath - manifest path (for message context)
+ * @param {string|null} ownRepoSlug - slug of the repository containing the manifest
+ * @throws {Error} naming the offending value and the canonical spelling
+ */
+function assertSourceShape(src, i, filePath, ownRepoSlug) {
+  const at = `Invalid manifest at ${filePath}: sources[${i}] (${src.path})`;
+
+  // ── `path` must be a literal, repo-root-relative path — never adjacency, never a glob.
+  const segments = String(src.path).split('/');
+  if (String(src.path).startsWith('../') || segments.includes('..')) {
+    throw new Error(
+      `${at}: a path beginning with '../' is REFUSED. Adjacency reads a working tree, so the ` +
+      `source's ref "${src.ref ?? DEFAULT_SOURCE_REF}" is NOT honored and the provenance it claims is false. ` +
+      `MIGRATE to the cross-repo shape: set \`repo\` to the owner/name slug of the repository that ` +
+      `owns this content and make \`path\` repo-root-relative within it ` +
+      `(e.g. { "repo": "eabadir/unk", "path": "unkamon-beast/README.md", "ref": "main" }).`
+    );
+  }
+  if (GLOB_CHARS.test(String(src.path))) {
+    throw new Error(
+      `${at}: \`path\` is a literal — globs are REFUSED. \`syncignore\` already owns exclusion; ` +
+      `name the directory literally and express the filter in \`syncignore\`.`
+    );
+  }
+
+  if (src.repo === undefined) return; // IN-REPO shape: omission is the single spelling of "here".
+
+  // ── CROSS-REPO shape.
+  if (typeof src.repo !== 'string' || !src.repo.trim()) {
+    throw new Error(`${at}: \`repo\` must be an owner/name slug string.`);
+  }
+  const repo = src.repo.trim();
+  const looksLikeUrl = /:\/\//.test(repo) || /^[^/]+@/.test(repo) || /\.git$/.test(repo);
+  if (looksLikeUrl || repo.split('/').filter(Boolean).length !== 2 || repo.startsWith('/') || repo.endsWith('/')) {
+    const suggestion = repoSlugFromRemoteUrl(repo);
+    throw new Error(
+      `${at}: \`repo\` must be an owner/name slug (e.g. 'eabadir/unk'), never a URL — got "${repo}"` +
+      `${suggestion ? `. Did you mean "${suggestion}"?` : '.'}`
+    );
+  }
+  if (ownRepoSlug && repo.toLowerCase() === ownRepoSlug.toLowerCase()) {
+    throw new Error(
+      `${at}: \`repo\` names this manifest's OWN repository ("${repo}") — REFUSED. Omission is the ` +
+      `single spelling of 'here' and an explicit slug the single spelling of 'elsewhere'; two ` +
+      `spellings of 'here' is exactly the drift this field exists to prevent. Remove \`repo\` and ` +
+      `keep \`path\` relative to this repository.`
+    );
+  }
+  if (!ownRepoSlug) {
+    throw new Error(
+      `${at}: \`repo\` is set ("${repo}") but this manifest's OWN repository slug could not be ` +
+      `determined (no git repository or no 'origin' remote at ${path.dirname(filePath)}), so the ` +
+      `"names its own repository" check CANNOT run. Refusing rather than accepting an unverifiable ` +
+      `cross-repo source.`
+    );
+  }
+}
+
+// Deprecated per-source field -> canonical replacement. Normalized at load (canonical wins if both
+// are present); a deprecation warning is emitted during the migration window.
+export const DEPRECATED_SOURCE_ALIASES = Object.freeze({ src_path: 'raw_path' });
+
+// Recognized manifest-level (top-level) keys. `_`-prefixed keys are annotation/comment keys and are
+// always allowed (e.g. `_purpose`). Unknown top-level keys warn like unknown source fields.
+export const CANONICAL_MANIFEST_FIELDS = new Set([
+  'kb_name', 'sync_mode', 'publish_tier', 'sources', 'github',
+]);
+
+/**
+ * Collect schema warnings for a manifest WITHOUT throwing — the validator half of the canonical
+ * schema. Flags unknown per-source/top-level fields (typo guard) and deprecated aliases. Exported
+ * so a conformance test drives off the SAME field set the loader enforces (no hand-mirrored list).
+ *
+ * @param {Object} manifest - parsed manifest object
+ * @param {string} filePath - manifest path (for message context)
+ * @returns {string[]} human-readable warning lines (empty when the manifest is fully canonical)
+ */
+export function collectManifestSchemaWarnings(manifest, filePath) {
+  const warnings = [];
+  const base = path.basename(filePath || 'manifest.json');
+  const recognized = [...CANONICAL_SOURCE_FIELDS].join(', ');
+
+  for (const key of Object.keys(manifest || {})) {
+    if (key.startsWith('_')) continue; // annotation/comment key
+    if (CANONICAL_MANIFEST_FIELDS.has(key)) continue;
+    warnings.push(`  ⚠ ${base}: unknown top-level field "${key}" is ignored — check for a typo.`);
+  }
+
+  const sources = Array.isArray(manifest?.sources) ? manifest.sources : [];
+  sources.forEach((src, i) => {
+    for (const key of Object.keys(src || {})) {
+      if (key.startsWith('_')) continue;
+      if (CANONICAL_SOURCE_FIELDS.has(key)) continue;
+      if (key in DEPRECATED_SOURCE_ALIASES) {
+        warnings.push(
+          `  ⚠ ${base} sources[${i}] (${src.path}): field "${key}" is DEPRECATED — rename to ` +
+          `"${DEPRECATED_SOURCE_ALIASES[key]}" (normalized for now; support is removed after the ` +
+          `deprecation window).`
+        );
+      } else {
+        warnings.push(
+          `  ⚠ ${base} sources[${i}] (${src.path}): unknown field "${key}" is ignored — check for a ` +
+          `typo (recognized: ${recognized}).`
+        );
+      }
+    }
+  });
+
+  return warnings;
+}
+
+/**
+ * Validate a parsed manifest object against the schema.
+ * Required: kb_name (string), sources (non-empty array).
+ * Each source: path (string) required; ref, tier, doc_type, syncignore optional.
+ * KB-curation (CEO-D-2026-07-11): manifest-level `publish_tier` ("P"|"I"|"U",
+ * default "I") + per-source `doc_class`, `license_basis`, `lint_exempt`,
+ * `exempt_reason`, `raw_path` (all optional). A `publish_tier:"P"` manifest hard-
+ * fails if any source lacks a publishable `doc_class` (no default is allowed).
+ * github block: optional, validated but not used for sync_mode: "local".
+ *
+ * @param {Object} manifest - Parsed JSON manifest
+ * @param {string} filePath - Path to manifest file (for error messages)
+ * @throws {Error} If validation fails
+ */
+function validateManifest(manifest, filePath, ownRepoSlug = null) {
+  if (!manifest || typeof manifest !== 'object') {
+    throw new Error(`Invalid manifest at ${filePath}: not a JSON object`);
+  }
+
+  if (!manifest.kb_name || typeof manifest.kb_name !== 'string') {
+    throw new Error(`Invalid manifest at ${filePath}: kb_name (string) is required`);
+  }
+
+  if (manifest.publish_tier !== undefined) {
+    if (typeof manifest.publish_tier !== 'string' || !PUBLISH_TIERS.has(manifest.publish_tier)) {
+      throw new Error(`Invalid manifest at ${filePath}: publish_tier must be one of "P", "I", "U"`);
+    }
+  }
+  const isTierP = manifest.publish_tier === 'P';
+
+  if (!Array.isArray(manifest.sources) || manifest.sources.length === 0) {
+    throw new Error(`Invalid manifest at ${filePath}: sources (non-empty array) is required`);
+  }
+
+  for (let i = 0; i < manifest.sources.length; i++) {
+    const src = manifest.sources[i];
+    if (!src.path || typeof src.path !== 'string') {
+      throw new Error(`Invalid manifest at ${filePath}: sources[${i}].path (string) is required`);
+    }
+    // Optional fields: ref (string), tier (number), doc_type (string), syncignore (string[])
+    if (src.ref !== undefined && typeof src.ref !== 'string') {
+      throw new Error(`Invalid manifest at ${filePath}: sources[${i}].ref must be a string`);
+    }
+    if (src.tier !== undefined && typeof src.tier !== 'number') {
+      throw new Error(`Invalid manifest at ${filePath}: sources[${i}].tier must be a number`);
+    }
+    if (src.doc_type !== undefined && typeof src.doc_type !== 'string') {
+      throw new Error(`Invalid manifest at ${filePath}: sources[${i}].doc_type must be a string`);
+    }
+    if (src.syncignore !== undefined && !Array.isArray(src.syncignore)) {
+      throw new Error(`Invalid manifest at ${filePath}: sources[${i}].syncignore must be an array`);
+    }
+    // KB-curation optional per-source fields.
+    if (src.doc_class !== undefined && typeof src.doc_class !== 'string') {
+      throw new Error(`Invalid manifest at ${filePath}: sources[${i}].doc_class must be a string`);
+    }
+    if (src.license_basis !== undefined && typeof src.license_basis !== 'string') {
+      throw new Error(`Invalid manifest at ${filePath}: sources[${i}].license_basis must be a string`);
+    }
+    if (src.lint_exempt !== undefined && !Array.isArray(src.lint_exempt)) {
+      throw new Error(`Invalid manifest at ${filePath}: sources[${i}].lint_exempt must be an array`);
+    }
+    if (src.exempt_reason !== undefined && typeof src.exempt_reason !== 'string') {
+      throw new Error(`Invalid manifest at ${filePath}: sources[${i}].exempt_reason must be a string`);
+    }
+    if (src.raw_path !== undefined && typeof src.raw_path !== 'string') {
+      throw new Error(`Invalid manifest at ${filePath}: sources[${i}].raw_path must be a string`);
+    }
+
+    // Two-shape source contract (interface-ws-c4-I2-manifest-source): adjacency/glob paths and
+    // self-naming or URL-shaped `repo` values are REFUSED here, loudly, naming the migration.
+    assertSourceShape(src, i, filePath, ownRepoSlug);
+
+    // Tier-P: every source MUST carry a publishable doc_class (no default allowed).
+    if (isTierP) {
+      if (!src.doc_class) {
+        throw new Error(
+          `Invalid manifest at ${filePath}: sources[${i}] (${src.path}) requires a doc_class ` +
+          `in a Tier-P (publish_tier:"P") manifest — no default is allowed.`
+        );
+      }
+      if (DENY_DOC_CLASSES.has(src.doc_class)) {
+        throw new Error(
+          `Invalid manifest at ${filePath}: sources[${i}] (${src.path}) doc_class "${src.doc_class}" ` +
+          `is a deny-class {${[...DENY_DOC_CLASSES].join(', ')}} — structurally invalid in a Tier-P manifest.`
+        );
+      }
+      if (!PUBLISHABLE_DOC_CLASSES.has(src.doc_class)) {
+        throw new Error(
+          `Invalid manifest at ${filePath}: sources[${i}] (${src.path}) doc_class "${src.doc_class}" ` +
+          `is not a publishable class {${[...PUBLISHABLE_DOC_CLASSES].join(', ')}}.`
+        );
+      }
+    }
+  }
+
+  // github block: validate structure if present, but skip for local sync
+  if (manifest.github !== undefined) {
+    if (typeof manifest.github !== 'object') {
+      throw new Error(`Invalid manifest at ${filePath}: github must be an object`);
+    }
+  }
+}
+
+/**
+ * Load a single manifest file.
+ *
+ * @param {string} manifestPath - Absolute path to manifest JSON file
+ * @param {string} workspaceRoot - Workspace root for resolving relative paths
+ * @returns {Promise<Object>} Validated manifest with resolved paths
+ */
+export async function loadManifest(manifestPath, workspaceRoot, options = {}) {
+  const raw = await fs.readFile(manifestPath, 'utf-8');
+  const manifest = JSON.parse(raw);
+
+  // The repository that physically contains this manifest — the thing `repo` may never name.
+  // Injectable so tests drive the check without depending on the ambient checkout.
+  const ownRepoSlug = options.ownRepoSlug !== undefined
+    ? options.ownRepoSlug
+    : detectRepoSlug(path.dirname(manifestPath));
+
+  validateManifest(manifest, manifestPath, ownRepoSlug);
+
+  // Canonical-schema warnings (WS-EVP-DESCIX-KB-CLEANUP item 5): surface deprecated aliases and
+  // unknown/misspelled fields during the deprecation window — warn, never throw, so both legacy
+  // formats keep syncing.
+  for (const w of collectManifestSchemaWarnings(manifest, manifestPath)) {
+    console.warn(w);
+  }
+
+  // Resolve source paths relative to workspace root
+  manifest._resolvedSources = manifest.sources.map(src => {
+    // Normalize deprecated field aliases (src_path -> raw_path). Canonical field wins if both set.
+    const s = { ...src };
+    for (const [alias, canonical] of Object.entries(DEPRECATED_SOURCE_ALIASES)) {
+      if (s[alias] !== undefined && s[canonical] === undefined) {
+        s[canonical] = s[alias];
+      }
+    }
+    return {
+      ...s,
+      // `repo` stays UNDEFINED when omitted — omission is the single spelling of "here" and must
+      // survive the load, so an in-repo source is never silently rewritten into a cross-repo one.
+      repo: s.repo === undefined ? undefined : String(s.repo).trim(),
+      absolutePath: path.resolve(workspaceRoot, s.path),
+      ref: s.ref || DEFAULT_SOURCE_REF,
+      tier: s.tier || 3,
+      doc_type: s.doc_type || 'generic',
+      syncignore: s.syncignore || [],
+      // KB-curation carry-through. doc_class is as-is (may be undefined for tier I).
+      doc_class: s.doc_class,
+      license_basis: s.license_basis ?? null,
+      lint_exempt: s.lint_exempt || [],
+      exempt_reason: s.exempt_reason ?? null,
+      raw_path: s.raw_path ?? null
+    };
+  });
+
+  // Surface publish_tier on the manifest object (default "I") so corpus.js can
+  // read manifest.publish_tier to decide whether to run the Tier-P deny lint.
+  manifest.publish_tier = manifest.publish_tier || 'I';
+
+  manifest._manifestPath = manifestPath;
+  return manifest;
+}
+
+/**
+ * Discover and load all manifests for an app.
+ * Looks in {appRoot}/.descix/manifests/*.json
+ *
+ * @param {string} appRoot - Absolute path to app root directory
+ * @param {string} workspaceRoot - Workspace root for resolving relative paths
+ * @param {string} [filterKbName] - If provided, only load manifest with this kb_name
+ * @returns {Promise<Array<Object>>} Array of validated manifest objects
+ */
+export async function loadManifests(appRoot, workspaceRoot, filterKbName = null) {
+  const manifestsDir = path.join(appRoot, '.descix', 'manifests');
+
+  let files;
+  try {
+    files = await fs.readdir(manifestsDir);
+  } catch {
+    return []; // No manifests directory — not an error
+  }
+
+  // M2 (2026-04-20): skip non-KB manifests.
+  // {app}/.descix/manifests/ can hold schemas other than KB manifests
+  // (notably site.json, which has its own schema — see loadSiteManifest).
+  // The legacy loader validated every .json as a KB manifest and blocked
+  // 'descix kb corpus sync' with `kb_name required` whenever a site.json
+  // was present. We now:
+  //   (a) explicitly skip known non-KB filenames (site.json)
+  //   (b) try-catch each load and treat validation failures as "not a KB
+  //       manifest" when the cause is a missing kb_name, rather than
+  //       aborting the whole operation.
+  // Any other error (I/O, malformed JSON) is still propagated with context.
+  const NON_KB_MANIFESTS = new Set(['site.json']);
+  const jsonFiles = files.filter(f => f.endsWith('.json') && !NON_KB_MANIFESTS.has(f));
+  const manifests = [];
+
+  for (const file of jsonFiles) {
+    const manifestPath = path.join(manifestsDir, file);
+    let manifest;
+    try {
+      manifest = await loadManifest(manifestPath, workspaceRoot);
+    } catch (err) {
+      // If the file is missing kb_name, it's not a KB manifest — skip it
+      // with a warning rather than aborting the whole operation. This
+      // lets future non-KB schemas coexist without editing this allowlist.
+      if (/kb_name \(string\) is required/.test(err.message)) {
+        console.warn(`  ⚠ Skipping non-KB manifest: ${file} (${err.message})`);
+        continue;
+      }
+      throw err;
+    }
+
+    if (filterKbName && manifest.kb_name !== filterKbName) {
+      continue;
+    }
+
+    manifests.push(manifest);
+  }
+
+  return manifests;
+}
+
+// ============ Site Manifest Support ============
+
+/**
+ * Validate a site manifest against its schema.
+ * Required: sources (non-empty array).
+ * Each source: path (string) required; include, exclude optional string arrays.
+ * buildCommand: optional string.
+ *
+ * @param {Object} manifest - Parsed JSON manifest
+ * @param {string} filePath - Path to manifest file (for error messages)
+ * @throws {Error} If validation fails
+ */
+function validateSiteManifest(manifest, filePath) {
+  if (!manifest || typeof manifest !== 'object') {
+    throw new Error(`Invalid site manifest at ${filePath}: not a JSON object`);
+  }
+
+  if (!Array.isArray(manifest.sources) || manifest.sources.length === 0) {
+    throw new Error(`Invalid site manifest at ${filePath}: sources (non-empty array) is required`);
+  }
+
+  for (let i = 0; i < manifest.sources.length; i++) {
+    const src = manifest.sources[i];
+    if (!src.path || typeof src.path !== 'string') {
+      throw new Error(`Invalid site manifest at ${filePath}: sources[${i}].path (string) is required`);
+    }
+    if (src.include !== undefined && !Array.isArray(src.include)) {
+      throw new Error(`Invalid site manifest at ${filePath}: sources[${i}].include must be a string array`);
+    }
+    if (src.exclude !== undefined && !Array.isArray(src.exclude)) {
+      throw new Error(`Invalid site manifest at ${filePath}: sources[${i}].exclude must be a string array`);
+    }
+  }
+
+  if (manifest.buildCommand !== undefined && manifest.buildCommand !== null && typeof manifest.buildCommand !== 'string') {
+    throw new Error(`Invalid site manifest at ${filePath}: buildCommand must be a string or null`);
+  }
+}
+
+/**
+ * Load a site manifest from {appRoot}/.descix/manifests/site.json.
+ *
+ * Resolves source paths relative to the app's localPath in workspace.json.
+ * Each source entry gets include/exclude defaults applied.
+ *
+ * @param {string} appRoot - Absolute path to the app root directory
+ * @returns {Promise<Object|null>} Validated site manifest with _resolvedSources, or null if not found
+ */
+export async function loadSiteManifest(appRoot) {
+  const manifestPath = path.join(appRoot, '.descix', 'manifests', 'site.json');
+
+  let raw;
+  try {
+    raw = await fs.readFile(manifestPath, 'utf-8');
+  } catch (err) {
+    if (err.code === 'ENOENT') {
+      return null; // No site manifest — not an error
+    }
+    throw err;
+  }
+
+  const manifest = JSON.parse(raw);
+  validateSiteManifest(manifest, manifestPath);
+
+  // Resolve source paths relative to app root
+  manifest._resolvedSources = manifest.sources.map(src => ({
+    sourcePath: src.path,
+    absolutePath: path.resolve(appRoot, src.path),
+    include: src.include || [],  // empty = include everything
+    exclude: src.exclude || [],
+  }));
+
+  manifest._manifestPath = manifestPath;
+  manifest.buildCommand = manifest.buildCommand || null;
+
+  return manifest;
+}
+
+export default { loadManifest, loadManifests, loadSiteManifest };