@descix/cli 1.0.6 → 1.0.8

package/lib/commands/init.js

@@ -5,7 +5,6 @@
  */
 
 import chalk from 'chalk';
-import readline from 'readline';
 import path from 'path';
 import fs from 'fs/promises';
 import { fileURLToPath } from 'url';
@@ -17,56 +16,29 @@ import { generateAgentFiles } from '../agent-files.js';
 // spelled here is a second derivation of the same fact, and the removed verb this replaced
 // reached a developer who had done everything right.
 import { CANONICAL_KB_SYNC } from './retired-kb-sync.js';
+// "May I prompt?" has ONE OWNER. init does not derive it, and holds no TTY check of its own.
+import { createPromptSession } from '../interactive.js';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 
-/**
- * Create readline interface for interactive prompts
- */
-function createPrompt() {
-  return readline.createInterface({
-    input: process.stdin,
-    output: process.stdout
-  });
-}
-
-/**
- * Ask for text input with optional default
- */
-function askInput(rl, question, defaultValue = '') {
-  return new Promise((resolve) => {
-    const prompt = defaultValue ? `${question} [${defaultValue}]: ` : `${question}: `;
-    rl.question(prompt, (answer) => {
-      resolve(answer.trim() || defaultValue);
-    });
-  });
-}
-
-/**
- * Ask a yes/no question
- */
-function askYesNo(rl, question, defaultYes = true) {
-  return new Promise((resolve) => {
-    const suffix = defaultYes ? '(Y/n)' : '(y/N)';
-    rl.question(`${question} ${suffix}: `, (answer) => {
-      const trimmed = answer.trim().toLowerCase();
-      if (trimmed === '') {
-        resolve(defaultYes);
-      } else {
-        resolve(trimmed === 'y' || trimmed === 'yes');
-      }
-    });
-  });
-}
-
 /**
  * Run the init command
  * @param {Object} apiClient - API client (optional, for listing communities)
  * @param {Object} options - Command options
  */
 export async function runInit(apiClient, options = {}) {
-  const rl = createPrompt();
+  // The session is GATED AT CONSTRUCTION: under a non-TTY this throws NonInteractiveError,
+  // which bin/descix.js's init action prints and exits 1 on. It can no longer hang on an open
+  // pipe/FIFO, nor exit 0 writing nothing on /dev/null.
+  const rl = createPromptSession({
+    what: 'descix init',
+    nonInteractiveForm: [
+      'descix init has no non-interactive form today. Run it in a terminal.',
+      '',
+      'Nothing has been changed. An existing .descix/workspace.json is left as it is.'
+    ]
+  });
   const projectPath = options.path ? path.resolve(options.path) : process.cwd();
 
   // If --from-invite provided, resolve the invite first to pre-fill context
@@ -134,7 +106,7 @@ export async function runInit(apiClient, options = {}) {
     }
 
     if (hasExisting && !options.force) {
-      const overwrite = await askYesNo(rl, chalk.yellow('Workspace already initialized. Overwrite?'), false);
+      const overwrite = await rl.askYesNo(chalk.yellow('Workspace already initialized. Overwrite?'), false);
       if (!overwrite) {
         console.log(chalk.gray('\nInitialization cancelled.\n'));
         rl.close();
@@ -160,7 +132,7 @@ export async function runInit(apiClient, options = {}) {
           // ignore
         }
       }
-      communityId = await askInput(rl, chalk.white('Community ID'));
+      communityId = await rl.ask(chalk.white('Community ID'));
       if (!communityId) {
         console.log(chalk.red('\n❌ Community ID is required.\n'));
         rl.close();
@@ -171,7 +143,7 @@ export async function runInit(apiClient, options = {}) {
     const defaultAppName = path.basename(projectPath).toLowerCase().replace(/[^a-z0-9]/g, '_');
     let appName = options.app;
     if (!appName) {
-      appName = await askInput(rl, chalk.white('App name'), defaultAppName);
+      appName = await rl.ask(chalk.white('App name'), defaultAppName);
       if (!appName) {
         console.log(chalk.red('\n❌ App name is required.\n'));
         rl.close();
@@ -185,7 +157,7 @@ export async function runInit(apiClient, options = {}) {
     console.log(chalk.white(`  Community: ${communityId}`));
     console.log(chalk.white(`  App:       ${appName} (${appId})`));
 
-    const proceed = await askYesNo(rl, chalk.white('\nProceed?'), true);
+    const proceed = await rl.askYesNo(chalk.white('\nProceed?'), true);
     if (!proceed) {
       console.log(chalk.gray('\nCancelled.\n'));
       rl.close();

package/lib/commands/kb.js

@@ -22,6 +22,8 @@ import ora from 'ora';
 import * as path from 'path';
 import * as fs from 'fs/promises';
 import inquirer from 'inquirer';
+// "May I prompt?" has ONE OWNER. --interactive is an opt-IN, not a guarantee a human is there.
+import { requireInteractive } from '../interactive.js';
 import { WorkspaceConfig } from '../workspace-config.js';
 import { hydrateKb, pushStaging, checkStagingFiles } from '../core/Hydrator.js';
 import { processKb } from '../core/Chunker.js';
@@ -176,6 +178,11 @@ export async function runKbPush(apiClient, options) {
     // Create conflict prompt callback for interactive mode
     const onConflictPrompt = options.interactive ? async (fileName, fileInfo) => {
       spinner.stop();
+      requireInteractive({
+        what: 'descix drive push --interactive',
+        question: `File "${fileName}" exists in Drive. Overwrite or skip?`,
+        nonInteractiveForm: ['descix drive push   # without --interactive, conflicts resolve without a prompt']
+      });
       const { action } = await inquirer.prompt([{
         type: 'list',
         name: 'action',

package/lib/commands/retired-kb-sync.js

@@ -19,20 +19,17 @@
 export const CANONICAL_KB_SYNC = 'descix kb corpus sync';
 
 /** The verb that creates a KB — `kb corpus sync`'s dependency (I4). */
-export const CANONICAL_KB_CREATE = 'descix kb create';
+export const CANONICAL_KB_CREATE = 'descix app init --kb <kb_name>';
 
 /**
  * Every KB-sync surface retired by ws-devplane-cli-kb-surface-single-canonical-sync.
  * `invocation` is what a user types; `parent` is the commander parent it hung off.
  */
 export const RETIRED_KB_SYNC_SURFACES = [
-  { id: 'sync',      parent: 'program', name: 'sync',  invocation: 'descix sync',      registered: true  },
-  { id: 'sync.kb',   parent: 'sync',    name: 'kb',    invocation: 'descix sync kb',   registered: true  },
-  { id: 'kb.chunk',  parent: 'kb',      name: 'chunk', invocation: 'descix kb chunk',  registered: true  },
-  { id: 'kb.sync',   parent: 'kb',      name: 'sync',  invocation: 'descix kb sync',   registered: true  },
-  // registered:false -- `update` survives for app/site, so this one is a dispatcher branch
-  // inside the live `update` command rather than a commander registration of its own.
-  { id: 'update.kb', parent: 'update',  name: 'kb',    invocation: 'descix update kb', registered: false },
+  { id: 'sync',      parent: 'program', name: 'sync',  invocation: 'descix sync' },
+  { id: 'sync.kb',   parent: 'sync',    name: 'kb',    invocation: 'descix sync kb' },
+  { id: 'kb.chunk',  parent: 'kb',      name: 'chunk', invocation: 'descix kb chunk' },
+  { id: 'kb.sync',   parent: 'kb',      name: 'sync',  invocation: 'descix kb sync' },
 ];
 
 /** Implementations deleted with those surfaces. No exported symbol survives without a caller (I3). */
@@ -61,24 +58,6 @@ export function retiredKbSyncMessage(invocation) {
   );
 }
 
-/**
- * Refuse a retired invocation LOUDLY and exit non-zero.
- *
- * MEASURED, not assumed: a `throw` from updateAuto is NOT swallowed — updateAuto's own catch
- * prints the message before rethrowing, so both forms reach the user and exit 1. This exists
- * for two smaller, real reasons: (1) ONE owner for the refusal, so the dispatcher branch and
- * updateAuto's kb branch cannot drift into different wording or different exit codes; and
- * (2) a deliberate retirement is not a crash, so it should not be framed as "✖ Update failed".
- *
- * @param {string} invocation - the retired invocation, e.g. 'descix update kb'
- * @param {(s:string)=>string} red - chalk.red or equivalent
- * @returns {never}
- */
-export function refuseRetiredKbSync(invocation, red) {
-  console.error(red(`\n❌ ${retiredKbSyncMessage(invocation)}\n`));
-  process.exit(1);
-}
-
 /**
  * Register a retired invocation so it exits NON-ZERO naming the canonical surface.
  * Accepts and ignores any args/options the old surface took, so an old script fails with
@@ -120,7 +99,6 @@ export function registerRetiredKbSync(parent, name, invocation, red) {
 export function registerAllRetiredKbSync(roots, red) {
   const byId = { ...roots };
   for (const s of RETIRED_KB_SYNC_SURFACES) {
-    if (!s.registered) continue;
     const parent = byId[s.parent];
     if (!parent) {
       throw new Error(

package/lib/commands/status.js

@@ -206,15 +206,6 @@ export async function runStatus(options = {}) {
     console.log(`Service Key:        ${chalk.gray('None')} (dev-overrides.json)`);
   }
 
-  // Check for MCP rules
-  const rulesPath = path.join(checkDir, '.cursor', 'rules', 'descix_mcp.mdc');
-  try {
-    await fs.access(rulesPath);
-    console.log(`MCP Rules:          ${chalk.green('Deployed')} (.cursor/rules/descix_mcp.mdc)`);
-  } catch {
-    console.log(`MCP Rules:          ${chalk.gray('Not Deployed')}`);
-  }
-
   // Check gcloud
   const gcloudStatus = await checkGcloud();
   if (gcloudStatus.installed) {

package/lib/core/Chunker.js

@@ -938,7 +938,7 @@ export async function processKb(config, options = {}) {
   try {
     await fs.access(srcDir);
   } catch {
-    throw new Error(`Source directory not found: ${srcDir}\nRun "descix kb pull" first.`);
+    throw new Error(`Source directory not found: ${srcDir}\nRun "descix drive pull" first.`);
   }
   
   await fs.mkdir(chunksDir, { recursive: true });

package/lib/core/CorpusWalker.js

@@ -7,16 +7,19 @@
  * Architecture:
  * - Files stay in place — no copying or staging
  * - Git blob SHAs provide versioning (same content = same SHA)
- * - Untracked/modified files use `git hash-object` for working tree version
+ * - GIT IS THE ONLY SOURCE OF TRUTH FOR WHAT IS A CORPUS SOURCE: a file must be TRACKED
+ *   AT THE MANIFEST'S REF or it is refused by name. There is no working-tree fallback.
  * - Chunk IDs are content-addressed: {app_id}:{kb_name}:{blob_sha}:{chunk_idx}
  */
 
 import * as fs from 'fs/promises';
+import * as fsSync from 'fs';
 import * as path from 'path';
 import { execSync } from 'child_process';
 import { minimatch } from 'minimatch';
-// The source-ref default is owned by ManifestLoader — consume it, never re-default.
-import { DEFAULT_SOURCE_REF } from './ManifestLoader.js';
+// The source-ref default and "which repository owns this file" are both owned by
+// ManifestLoader — consume them, never re-default and never re-derive.
+import { DEFAULT_SOURCE_REF, resolveOwningRepo } from './ManifestLoader.js';
 
 /**
  * File extensions that are processable for RAG chunking.
@@ -60,42 +63,132 @@ function isIgnored(relativePath, syncignore) {
   return false;
 }
 
+const SHA40 = /^[0-9a-f]{40}$/i;
+
 /**
- * Compute the git blob SHA for a file.
- * First tries `git rev-parse {ref}:{workspace-relative-path}` for tracked files.
- * Falls back to `git hash-object {file}` for untracked/modified files.
+ * Explain WHICH WAY a path failed the "tracked at ref" predicate. Purely diagnostic —
+ * it never decides anything, so there is still exactly one decision site. Each branch
+ * ends in an instruction the operator can act on without further investigation.
  *
- * @param {string} absolutePath - Absolute path to the file
- * @param {string} workspaceRelativePath - Path relative to workspace root
- * @param {string} ref - Git ref (branch/tag)
- * @param {string} workspaceRoot - Workspace root directory
- * @returns {string} Git blob SHA (40 hex chars)
+ * @returns {string} the reason string embedded in the aggregated refusal
  */
-function computeBlobSha(absolutePath, workspaceRelativePath, ref, workspaceRoot) {
+function diagnoseUntracked(repoRelativePath, ref, repoRoot, repoLabel) {
+  // Every diagnostic below runs IN THE OWNING REPOSITORY. Running them at the ambient
+  // workspace root is what produced the maximally wrong advice this gate was blocked for
+  // ("UNTRACKED — commit it on main" about content that was already committed, and
+  // "IGNORED BY GIT" about a sibling repo the SUPERREPO ignores but which tracks it fine).
+  const where = `in ${repoLabel}`;
+
+  // (c) Present at HEAD but absent at THIS ref — checked first, because .gitignore
+  // patterns do not apply to tracked files and would misdiagnose this case.
   try {
-    // Try to get the blob SHA from the git tree at the specified ref
-    const sha = execSync(
-      `git rev-parse "${ref}:${workspaceRelativePath}"`,
-      { cwd: workspaceRoot, encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] }
+    execSync(`git rev-parse "HEAD:${repoRelativePath}"`,
+      { cwd: repoRoot, encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] });
+    return `present at HEAD but ABSENT AT REF "${ref}" ${where} — the manifest pins a ref ` +
+           `that predates this file; commit it on "${ref}" or point the source at the right ref`;
+  } catch { /* not at HEAD either — fall through */ }
+
+  // (a) Deliberately excluded from the repository. The measured defect class.
+  try {
+    const hit = execSync(`git check-ignore -v "${repoRelativePath}"`,
+      { cwd: repoRoot, encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] }
+    ).trim().split('\n')[0];
+    if (hit) {
+      return `IGNORED BY GIT (${hit.split('\t')[0]}) ${where} and not tracked at ref ` +
+             `"${ref}" — content the repository deliberately excludes must never become a ` +
+             `citable KB source; remove this source from the manifest`;
+    }
+  } catch { /* not ignored — fall through */ }
+
+  // (b) Simply never committed.
+  return `UNTRACKED at ref "${ref}" ${where} — the file exists on disk but that repository ` +
+         `does not track it; commit it on "${ref}", or remove this source from the manifest`;
+}
+
+/**
+ * THE SOURCE GATE — the single owner of "is this file a legitimate corpus source".
+ *
+ * A source is legitimate iff GIT TRACKS IT AT THE MANIFEST'S REF. That one predicate is
+ * the whole rule, and it is deliberately not split by WHY a path fails it: gitignored
+ * scratch, never-committed, and absent-at-an-older-ref are all "not tracked at ref".
+ * Splitting them would re-derive "what is a corpus source" in a second place, and the
+ * copies would drift.
+ *
+ * THE WORKING TREE IS NEVER CONSULTED. Reading a sha from disk when the ref lookup failed
+ * is the measured defect: it served content git was explicitly told to exclude as a
+ * citable KB source (corpus:04406066... = `.claude/agent-memory/evp-descix/qa-pairs.jsonl`,
+ * excluded by .gitignore, chunked and served anyway). That path is deleted, not fenced
+ * behind a flag, and there is nothing that restores it — SUPER-DRY, CEO-D-2026-07-26.
+ *
+ * THE REF IS RESOLVED IN THE REPOSITORY THAT OWNS THE FILE, never in an ambient root. A
+ * workspace spans several repositories (superrepo, submodules, ignored sibling checkouts)
+ * and a ref names a branch in exactly one of them. Asking the superrepo about a file inside
+ * a submodule asks the wrong repository a question it cannot answer — it holds only a
+ * gitlink commit — and the honest-looking "not tracked" that comes back is FALSE. That was
+ * measured on this very branch: 596 committed files refused, the two largest live KBs
+ * stopped, with advice telling the operator to commit content already committed.
+ * "Which repository owns this file" has ONE owner: ManifestLoader::resolveOwningRepo.
+ *
+ * Returns a REASON rather than throwing so the caller can aggregate every offender into
+ * one refusal instead of failing on the first (mirroring CorpusDenyLint's report/assert
+ * split — the established refusal shape in this codebase).
+ *
+ * @param {string} absoluteFilePath - Absolute path to the file under test
+ * @param {string} ref - Git ref (branch/tag) the manifest source named
+ * @param {string} [workspaceRoot] - Only to label paths in messages; NEVER a resolution root
+ * @returns {{sha: string|null, reason: string|null, repoRoot: string|null}}
+ */
+export function resolveTrackedBlobSha(absoluteFilePath, ref, workspaceRoot = null) {
+  const owner = resolveOwningRepo(absoluteFilePath);
+  if (!owner) {
+    return {
+      sha: null, repoRoot: null,
+      reason: `NOT INSIDE ANY GIT REPOSITORY — no repository owns this path, so ref "${ref}" ` +
+              `cannot be resolved for it and nothing can vouch for its content; remove this ` +
+              `source from the manifest, or put the content in a repository and commit it`
+    };
+  }
+  const { repoRoot, repoRelativePath } = owner;
+  // How the owning repo is named in messages: relative to the workspace when we have one,
+  // so the operator reads "DeSciX/DeSciX_Cloud" rather than an absolute machine path.
+  // `repoRoot` is a REAL path (git resolves symlinks), so the workspace root must be one
+  // too or the subtraction escapes upward into `../../..`.
+  let workspaceReal = workspaceRoot;
+  try { if (workspaceRoot) workspaceReal = fsSync.realpathSync(workspaceRoot); } catch { /* keep as given */ }
+  const repoLabel = workspaceRoot ? (path.relative(workspaceReal, repoRoot) || '.') : repoRoot;
+
+  let sha;
+  try {
+    sha = execSync(
+      `git rev-parse "${ref}:${repoRelativePath}"`,
+      { cwd: repoRoot, encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] }
     ).trim();
-    return sha;
   } catch {
-    // File is untracked or path doesn't exist in git tree at that ref
-    // Fall back to hashing the working tree version
-    try {
-      const sha = execSync(
-        `git hash-object "${absolutePath}"`,
-        { cwd: workspaceRoot, encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] }
-      ).trim();
-      return sha;
-    } catch {
-      // Last resort: return null — caller should skip this file
-      return null;
-    }
+    // ONE PREDICATE ("tracked at ref, in the owning repo"), FOUR DIAGNOSTICS. The decision
+    // has already been made above — everything below only explains WHICH WAY the path
+    // failed, so DRY holds and each population gets a self-curing instruction.
+    return { sha: null, repoRoot, reason: diagnoseUntracked(repoRelativePath, ref, repoRoot, repoLabel) };
+  }
+
+  if (!SHA40.test(sha)) {
+    return {
+      sha: null, repoRoot,
+      reason: `git rev-parse "${ref}:${repoRelativePath}" in ${repoLabel} returned "${sha}", which is not a blob sha`
+    };
   }
+  return { sha, repoRoot, reason: null };
 }
 
-const SHA40 = /^[0-9a-f]{40}$/i;
+/**
+ * What this gate compares, catches, and does NOT read — printed with the verdict so a
+ * reader of a GREEN sees where the green stops, in the gate's own words.
+ */
+export const SOURCE_GATE_BOUNDARY = Object.freeze({
+  compares: 'each walked file against `git rev-parse <manifest source ref>:<path relative to THE REPOSITORY THAT OWNS THE FILE>`, where the owner is the nearest enclosing git repository (ManifestLoader::resolveOwningRepo) — the superrepo, a submodule, or an ignored sibling checkout',
+  catches: 'any corpus source not tracked at its ref BY ITS OWN REPOSITORY — gitignored scratch, never-committed files, paths absent from an older ref, and paths inside no repository at all',
+  does_not_read: 'file CONTENT (see CorpusDenyLint for content/path deny-classes), Pinecone live state, and cross-repo `repo:` sources (refused separately by resolveSourceProvenance). It also does NOT check that a submodule\'s ref matches the commit the superrepo pins at its gitlink: a source is walked at the ref it names in the repository that owns it, so content committed on that branch but not yet pinned by the superrepo is accepted.',
+  runs_automatically: 'yes — inside walkCorpus, so every `descix kb corpus sync` passes through it; there is no flag that skips it'
+});
 
 /**
  * Resolve ONE source's provenance: which repository, which ref, and the exact commit synced.
@@ -117,33 +210,62 @@ const SHA40 = /^[0-9a-f]{40}$/i;
 export async function resolveSourceProvenance(source, workspaceRoot) {
   const ref = source.ref || DEFAULT_SOURCE_REF;
   const repo = source.repo ?? null;
-  // ONE derivation of "which repo this content belongs to": the explicit slug when the source is
-  // cross-repo, else the leading path segment (the historical in-repo value, preserved verbatim so
-  // existing chunk metadata does not churn).
+  // `source_repo` is a LEGACY DISPLAY LABEL that rides into chunk metadata — NOT the
+  // ownership decision. Ownership is decided in exactly one place (resolveOwningRepo);
+  // this leading-path-segment value is preserved verbatim because rewriting it would
+  // re-stamp every existing chunk in every live KB. Do not read it as "which repository
+  // owns this file"; for that, ask the owner.
   const source_repo = repo ?? (String(source.path || '').split('/')[0] || 'unknown');
 
   if (!repo) {
+    // Resolve the commit IN THE REPOSITORY THAT OWNS THE SOURCE — the same one owner the
+    // gate consults. Resolving it at the ambient workspace root would record the
+    // SUPERREPO's commit for content whose blobs came from a submodule or a sibling repo:
+    // two derivations of "where did this content come from" that disagree, which is the
+    // mirror-drift this file already refuses elsewhere. A provenance record that names the
+    // wrong repository's commit is a FALSE record, not an approximate one.
+    const owner = resolveOwningRepo(source.absolutePath);
+    if (!owner) {
+      throw new Error(
+        `Source "${source.path}" resolves to ${source.absolutePath}, which is inside NO git ` +
+        `repository. Refusing to record provenance — there is no repository whose ref "${ref}" ` +
+        `could describe this content.`
+      );
+    }
+    const provenanceRoot = owner.repoRoot;
     let sha;
     try {
       sha = execSync(`git rev-parse "${ref}^{commit}"`, {
-        cwd: workspaceRoot, encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'],
+        cwd: provenanceRoot, encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'],
       }).trim();
     } catch {
       throw new Error(
-        `Cannot resolve ref "${ref}" to a commit in ${workspaceRoot} for source "${source.path}". ` +
-        `Refusing to record provenance — a sync-state commit of "unknown" is a FALSE record, not a ` +
-        `missing one. Check that the ref exists locally.`
+        `Cannot resolve ref "${ref}" to a commit in ${provenanceRoot} (the repository that owns ` +
+        `source "${source.path}") . Refusing to record provenance — a sync-state commit of ` +
+        `"unknown" is a FALSE record, not a missing one. Check that the ref exists in THAT ` +
+        `repository, which is not necessarily the workspace root ${workspaceRoot}.`
       );
     }
     if (!SHA40.test(sha)) {
       throw new Error(`Ref "${ref}" resolved to "${sha}", which is not a commit sha (source "${source.path}").`);
     }
-    return { repo: null, ref, resolved_commit_sha: sha, source_repo };
+    // `repo_root` MAKES THE RECORDED COMMIT SELF-DESCRIBING. Before this, every commit in
+    // sync-state was a workspace-root commit, so a reader could resolve it at the workspace
+    // root and be right by accident. Now a commit may belong to a submodule or a sibling
+    // repo, and the SAME 40 hex characters mean different things depending on which
+    // repository you ask. Writing the owning repo beside the commit is what keeps the store
+    // homogeneous: a reader resolves the commit WHERE THIS SAYS, and a record written before
+    // this field existed is missing it and can be detected rather than silently misread.
+    return {
+      repo: null, ref, resolved_commit_sha: sha, source_repo,
+      repo_root: path.relative(workspaceRoot, provenanceRoot) || '.',
+    };
   }
 
-  // CROSS-REPO: resolve against the remote. Never a local read.
+  // CROSS-REPO: resolve against the remote. Never a local read. `repo_root` is null because
+  // the content is not in this workspace at all — `repo` already says where it lives.
   if (SHA40.test(ref)) {
-    return { repo, ref, resolved_commit_sha: ref.toLowerCase(), source_repo };
+    return { repo, ref, resolved_commit_sha: ref.toLowerCase(), source_repo, repo_root: null };
   }
   const remoteUrl = `https://github.com/${repo}.git`;
   let out;
@@ -167,7 +289,7 @@ export async function resolveSourceProvenance(source, workspaceRoot) {
       `Repo "${repo}" has no ref "${ref}" (source "${source.path}"). REFUSING rather than guessing.`
     );
   }
-  return { repo, ref, resolved_commit_sha: sha, source_repo };
+  return { repo, ref, resolved_commit_sha: sha, source_repo, repo_root: null };
 }
 
 /**
@@ -247,6 +369,9 @@ async function isFile(filePath) {
 export async function walkCorpus(manifest, workspaceRoot) {
   const files = [];
   const provenance = [];
+  // Every file the source gate refused, collected so ONE error can name them all. A
+  // first-throw would hide offenders 2..N and turn one fix into N sync attempts.
+  const refused = [];
   let commitSha = 'unknown';
 
   // Nested-source dedup (WS-EVP-DESCIX-KB-CLEANUP item 4): a manifest may list both a directory
@@ -276,6 +401,39 @@ export async function walkCorpus(manifest, workspaceRoot) {
     const { absolutePath, ref, tier, doc_type, syncignore } = source;
     const thisSourceRoot = path.resolve(absolutePath);
 
+    // An IN-REPO source whose path lies in NO repository joins the AGGREGATED refusal rather
+    // than throwing. Both outcomes refuse — but throwing would abort on the first offending
+    // source and hide every later one, turning one manifest fix into N sync attempts, which
+    // is the whole reason this walk aggregates. Measured: `EGPT/` (in no repo) aborted the
+    // EVP-EGPT walk before its other sources were ever examined.
+    //
+    // CROSS-REPO SOURCES ARE DELIBERATELY EXEMPT. Their `absolutePath` is a fiction — the
+    // content lives in another repository — so "is it in a repo here" is the wrong question
+    // and answering it would MASK the accurate refusal resolveSourceProvenance already owns.
+    // Measured: EVP-BEAST's four `repo: eabadir/unk` sources were being reported as "not
+    // inside any git repository" instead of "cross-repo content fetch is not implemented".
+    if (source.repo === undefined) {
+      const exists = await fs.access(absolutePath).then(() => true, () => false);
+      if (!exists) {
+        refused.push({
+          path: source.path, ref, source: source.path,
+          reason: `DOES NOT EXIST at ${absolutePath} — the manifest names a path that is not ` +
+                  `on disk; correct the path or remove this source from the manifest`,
+        });
+        continue;
+      }
+      if (!resolveOwningRepo(absolutePath)) {
+        refused.push({
+          path: source.path, ref, source: source.path,
+          reason: `NOT INSIDE ANY GIT REPOSITORY (${absolutePath}) — no repository owns this ` +
+                  `path, so ref "${ref}" cannot be resolved for it and nothing can vouch for ` +
+                  `its content; remove this source from the manifest, or put the content in a ` +
+                  `repository and commit it`,
+        });
+        continue;
+      }
+    }
+
     // Resolve this source's exact provenance BEFORE reading anything. A cross-repo source that
     // cannot be fetched REFUSES here, naming the repo — it is never silently skipped and never
     // falls back to reading an adjacent working tree.
@@ -318,13 +476,17 @@ export async function walkCorpus(manifest, workspaceRoot) {
       if (ownerSourceRoot(filePath) !== thisSourceRoot) {
         continue;
       }
-      // Compute workspace-relative path for git operations
+      // Workspace-relative path is the DISPLAY/metadata spelling only. Git resolution uses
+      // the owning repository — see resolveTrackedBlobSha.
       const workspaceRelativePath = path.relative(workspaceRoot, filePath);
 
-      // Compute blob SHA
-      const blobSha = computeBlobSha(filePath, workspaceRelativePath, ref, workspaceRoot);
+      // THE SOURCE GATE. A file the OWNING repository does not track at this source's ref
+      // is REFUSED by name — never silently chunked from the working tree, and never
+      // silently skipped either (a skip on a clean worktree would PURGE its live chunks).
+      const { sha: blobSha, reason } = resolveTrackedBlobSha(filePath, ref, workspaceRoot);
       if (!blobSha) {
-        continue; // Skip files that can't be hashed
+        refused.push({ path: workspaceRelativePath, ref, reason, source: source.path });
+        continue;
       }
 
       // "Which repo does this content belong to" has ONE owner: resolveSourceProvenance.
@@ -351,7 +513,36 @@ export async function walkCorpus(manifest, workspaceRoot) {
     }
   }
 
-  return { files, commitSha, provenance };
+  // ONE aggregated refusal naming every offender, its ref and its reason. Raised AFTER
+  // the full walk so the operator fixes the manifest once rather than N times, and BEFORE
+  // any caller can chunk, upsert or purge — the refused files are neither served nor
+  // treated as deletions.
+  if (refused.length > 0) {
+    // The error must be fixable IN ONE ACT from its text alone: it names the manifest
+    // FILE to edit and the offending ENTRY within it, not merely the resolved path.
+    // `_manifestPath` is owned by ManifestLoader — consume it, never re-derive it.
+    const manifestFile = manifest._manifestPath || `(manifest for kb "${manifest.kb_name}")`;
+    const lines = refused.map(
+      r => `  - ${r.path}\n      ref: "${r.ref}"   manifest entry: sources[] path "${r.source}"\n      ${r.reason}`
+    );
+    const err = new Error(
+      `Corpus source gate FAILED for KB "${manifest.kb_name}": ${refused.length} file(s) are ` +
+      `not tracked by git at their manifest ref — refusing to sync.\n` +
+      `Manifest to edit: ${manifestFile}\n${lines.join('\n')}\n` +
+      `Every corpus source must be committed at its ref. There is no working-tree fallback: ` +
+      `content git excludes must never be served as a citable KB source.`
+    );
+    // The offenders as DATA, so a reporting tool consumes the gate's own verdict instead of
+    // re-implementing the predicate or scraping this prose. The message stays the human
+    // surface; `refused` is the machine one, and they cannot disagree because there is one
+    // decision behind both.
+    err.refused = refused;
+    err.kb_name = manifest.kb_name;
+    err.manifestPath = manifestFile;
+    throw err;
+  }
+
+  return { files, commitSha, provenance, gateBoundary: SOURCE_GATE_BOUNDARY };
 }
 
-export default { walkCorpus, resolveSourceProvenance };
+export default { walkCorpus, resolveSourceProvenance, resolveTrackedBlobSha, SOURCE_GATE_BOUNDARY };