@descix/cli 1.0.5 → 1.0.7

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 };

package/lib/core/Hydrator.js

@@ -726,11 +726,15 @@ export async function checkStagingFiles(stagingDir) {
  * 
  * @param {string} scaffoldType - 'site' or 'microservice'
  * @param {string} appPath - Path to the app directory
- * @param {Object} options - { verbose, force }
+ * @param {Object} options - { verbose, force, substitute }
+ * @param {{appId: string, communityId: string, appName?: string}} [options.substitute] - the
+ *   caller's real identity. Supply it for any scaffold a developer will actually use: without it
+ *   the copy is verbatim and every {{TOKEN}} ships unresolved. Omitting it is only appropriate
+ *   when materializing the raw template itself.
  * @returns {Promise<{copied: number}>}
  */
 export async function copyScaffold(scaffoldType, appPath, options = {}) {
-  const { verbose = false, force = false } = options;
+  const { verbose = false, force = false, substitute = null } = options;
   
   const scaffoldDir = SCAFFOLD_DIRS[scaffoldType];
   if (!scaffoldDir) {
@@ -767,8 +771,36 @@ export async function copyScaffold(scaffoldType, appPath, options = {}) {
   
   // Copy scaffold recursively
   const stats = { copied: 0 };
-  await copyDir(scaffoldDir, targetDir, stats, verbose);
-  
+  let values = null;
+  if (substitute) {
+    if (!substitute.appId || !substitute.communityId) {
+      throw new Error(
+        'copyScaffold: substitute requires both appId and communityId. Refusing to resolve a ' +
+        'scaffold against a partial identity — a half-substituted scaffold is harder to spot ' +
+        'than an unsubstituted one.'
+      );
+    }
+    values = {
+      APP_ID: substitute.appId,
+      COMMUNITY_ID: substitute.communityId,
+      APP_NAME: substitute.appName || substitute.appId,
+    };
+  }
+
+  const unresolved = [];
+  await copyDir(scaffoldDir, targetDir, stats, verbose, values, unresolved);
+
+  // FAIL LOUD. A placeholder that survives the copy reaches the developer as literal braces, and
+  // that is exactly the class of defect this substitution exists to end — so it must never be a
+  // warning. Name every offender so a new token added to a template cannot ship unnoticed.
+  if (unresolved.length > 0) {
+    throw new Error(
+      `Scaffold "${scaffoldType}" has ${unresolved.length} unresolved placeholder(s): ` +
+      `${unresolved.join(', ')}. Every {{TOKEN}} in a scaffold needs a value in copyScaffold's ` +
+      `substitute map (see templates/scaffolds/README.md for the documented set).`
+    );
+  }
+
   return stats;
 }
 
@@ -785,21 +817,66 @@ async function hasContentInDir(dirPath) {
 }
 
 /**
- * Recursively copy a directory
+ * THE ONE OWNER of scaffold placeholder substitution.
+ *
+ * templates/scaffolds/README.md has documented this contract all along — "Scaffolds use these
+ * placeholders (replaced during copy): {{APP_NAME}}, {{APP_ID}}, {{COMMUNITY_ID}}" — but nothing
+ * ever performed the replacement. Both scaffolds shipped their placeholders and their sample
+ * literals verbatim, so a developer's site was titled `{{APP_NAME}}` and the sample handler
+ * queried a community that is not theirs.
+ *
+ * SUBSTITUTION, NOT A SECOND LITERAL. The fix resolves each token to the caller's real values;
+ * it does not swap one hardcoded community for another. That is what lets the same scaffold serve
+ * every community without the CLI knowing any of their names.
+ *
+ * @param {string} text - file contents
+ * @param {Record<string,string>} values - token name (without braces) -> replacement
+ * @returns {string}
  */
-async function copyDir(src, dest, stats, verbose) {
+function applyScaffoldTokens(text, values) {
+  return text.replace(/\{\{([A-Z_]+)\}\}/g, (whole, token) =>
+    Object.prototype.hasOwnProperty.call(values, token) ? values[token] : whole
+  );
+}
+
+/** A NUL byte is the cheap, dependency-free binary tell. Never rewrite bytes we cannot read. */
+function looksBinary(buf) {
+  return buf.includes(0);
+}
+
+/**
+ * Recursively copy a directory, optionally substituting scaffold tokens on the way.
+ *
+ * @param {Record<string,string>|null} values - when null, the copy is byte-for-byte verbatim
+ * @param {string[]} unresolved - collects `file:{{TOKEN}}` for tokens no value was supplied for
+ */
+async function copyDir(src, dest, stats, verbose, values = null, unresolved = [], relBase = '') {
   await fs.mkdir(dest, { recursive: true });
-  
+
   const entries = await fs.readdir(src, { withFileTypes: true });
-  
+
   for (const entry of entries) {
     const srcPath = path.join(src, entry.name);
     const destPath = path.join(dest, entry.name);
-    
+    const rel = relBase ? `${relBase}/${entry.name}` : entry.name;
+
     if (entry.isDirectory()) {
-      await copyDir(srcPath, destPath, stats, verbose);
+      await copyDir(srcPath, destPath, stats, verbose, values, unresolved, rel);
     } else {
-      await fs.copyFile(srcPath, destPath);
+      if (values) {
+        const buf = await fs.readFile(srcPath);
+        if (looksBinary(buf)) {
+          await fs.copyFile(srcPath, destPath);
+        } else {
+          const out = applyScaffoldTokens(buf.toString('utf8'), values);
+          // Anything still wearing braces had no value supplied. Collect it rather than shipping
+          // it: an unresolved placeholder reaching a developer is the defect this exists to end.
+          for (const m of out.matchAll(/\{\{([A-Z_]+)\}\}/g)) unresolved.push(`${rel}:{{${m[1]}}}`);
+          await fs.writeFile(destPath, out);
+        }
+      } else {
+        await fs.copyFile(srcPath, destPath);
+      }
       stats.copied++;
       if (verbose) console.log(`  Copied: ${entry.name}`);
     }

package/lib/core/ManifestLoader.js

@@ -13,6 +13,7 @@
  */
 
 import * as fs from 'fs/promises';
+import { statSync, realpathSync } from 'fs';
 import * as path from 'path';
 import { execFileSync } from 'child_process';
 // Canonical doc_class taxonomy lives in CorpusDenyLint — import it, never re-list.
@@ -110,6 +111,73 @@ export function detectRepoSlug(dir) {
   }
 }
 
+/**
+ * THE ONE OWNER OF "WHICH REPOSITORY OWNS THIS FILE".
+ *
+ * A workspace is NOT one repository. This one crosses three kinds of boundary at once:
+ * the superrepo itself; git SUBMODULES (DeSciX/DeSciX_Cloud|Core|Powch are gitlinks —
+ * `git ls-tree HEAD DeSciX/` shows mode 160000); and SIBLING repos that are not submodules
+ * at all but independent checkouts the superrepo deliberately ignores (EGPT-research via
+ * .gitignore:9, FRAQTL — each with its own `.git` and its own `origin` remote).
+ *
+ * A REF HAS NO MEANING EXCEPT RELATIVE TO A REPOSITORY. Resolving one against the ambient
+ * workspace root is what made this gate refuse 596 files that ARE committed: the superrepo
+ * sees a submodule only as a gitlink commit, and an ignored sibling repo not at all.
+ * `git rev-parse --show-toplevel` walks UP from the path and stops at the FIRST enclosing
+ * repository — which is precisely the repository whose branches the source's `ref` names,
+ * and which settles submodule and sibling boundaries with ONE mechanism rather than two.
+ *
+ * This is NOT the question `detectRepoSlug` answers. That one is "what is this repository
+ * CALLED" (for the cross-repo self-naming refusal); this one is "where does it BEGIN", so a
+ * ref and a repo-relative path can be formed. Both live here so repository identity has a
+ * single home and no consumer re-derives either.
+ *
+ * @param {string} absolutePath - absolute path to a file or directory in the workspace
+ * @returns {{repoRoot: string, repoRelativePath: string}|null} null when the path lies in
+ *          NO git repository at all — callers must fail loud, never assume a root.
+ */
+const OWNING_REPO_CACHE = new Map(); // real directory -> repoRoot. POSITIVE results only.
+export function resolveOwningRepo(absolutePath) {
+  const abs = path.resolve(absolutePath);
+  // `--show-toplevel` needs a directory that exists, and a source may name a file. Split
+  // off the basename ONLY for a non-directory: for a DIRECTORY source, `path.dirname` would
+  // step over the very boundary being resolved (dirname of `DeSciX/DeSciX_Cloud` is the
+  // superrepo, which is the wrong answer).
+  let dir = abs, base = null;
+  try {
+    if (!statSync(abs).isDirectory()) { dir = path.dirname(abs); base = path.basename(abs); }
+  } catch {
+    dir = path.dirname(abs); base = path.basename(abs);
+  }
+
+  // BOTH SIDES MUST BE REAL PATHS OR THE SUBTRACTION IS GARBAGE. `git rev-parse
+  // --show-toplevel` always answers with symlinks resolved, so comparing it against a
+  // caller path that still contains one yields a `../../..`-riddled relative path that
+  // matches nothing. This is not a corner case: on macOS every temp dir is /var ->
+  // /private/var, and this repo's own dev flow serves the Core tree through a symlink.
+  let realDir;
+  try { realDir = realpathSync(dir); } catch { realDir = dir; }
+
+  let repoRoot = OWNING_REPO_CACHE.get(realDir);
+  if (repoRoot === undefined) {
+    try {
+      repoRoot = execFileSync('git', ['rev-parse', '--show-toplevel'], {
+        cwd: realDir, encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'],
+      }).trim();
+    } catch {
+      return null; // No repository. NOT cached: a negative is not durable — the directory
+    }              //  may be `git init`-ed later in the same process (fixtures do exactly this).
+    if (!repoRoot) return null;
+    OWNING_REPO_CACHE.set(realDir, repoRoot);
+  }
+
+  const repoRelativeDir = path.relative(repoRoot, realDir);
+  return {
+    repoRoot,
+    repoRelativePath: base ? path.join(repoRelativeDir, base) : repoRelativeDir,
+  };
+}
+
 /**
  * Enforce the two-shape source contract on ONE source entry.
  *