byterover-cli 3.0.1 → 3.2.0

package/dist/server/core/domain/source/source-operations.js

@@ -0,0 +1,201 @@
+import { existsSync, readFileSync, realpathSync, writeFileSync } from 'node:fs';
+import { basename, join } from 'node:path';
+import { BRV_DIR, PROJECT_CONFIG_FILE, SOURCES_FILE } from '../../../constants.js';
+import { getSourceStatuses, loadSources, SourcesFileSchema, } from './source-schema.js';
+// ============================================================================
+// Add source
+// ============================================================================
+/**
+ * Adds a read-only knowledge source from another project's context tree.
+ *
+ * Validates: target is a brv project, not self, not duplicate, not circular.
+ * Writes to `.brv/sources.json`.
+ */
+export function addSource(projectRoot, targetPath, alias) {
+    // 1. Local project must have .brv/
+    const localConfigPath = join(projectRoot, BRV_DIR, PROJECT_CONFIG_FILE);
+    if (!existsSync(localConfigPath)) {
+        return { message: `Current project has no .brv/ — run 'brv' first to initialize.`, success: false };
+    }
+    // 2. Resolve target to canonical path
+    let targetRoot;
+    try {
+        targetRoot = realpathSync(targetPath);
+    }
+    catch {
+        return { message: `Target path does not exist: ${targetPath}`, success: false };
+    }
+    // 3. Target must be a brv project
+    const targetConfigPath = join(targetRoot, BRV_DIR, PROJECT_CONFIG_FILE);
+    if (!existsSync(targetConfigPath)) {
+        return { message: `Target "${targetRoot}" is not a ByteRover project (no .brv/config.json).`, success: false };
+    }
+    // 4. Not self
+    let canonicalProjectRoot;
+    try {
+        canonicalProjectRoot = realpathSync(projectRoot);
+    }
+    catch {
+        canonicalProjectRoot = projectRoot;
+    }
+    if (targetRoot === canonicalProjectRoot) {
+        return { message: 'Cannot add a source pointing to the current project.', success: false };
+    }
+    // 5. Read existing file — refuse to mutate if malformed
+    const existing = readSourcesFile(projectRoot);
+    if (existing.error) {
+        return { message: existing.error, success: false };
+    }
+    // 6. Not duplicate
+    const isDuplicate = existing.data.sources.some((source) => {
+        try {
+            return realpathSync(source.projectRoot) === targetRoot;
+        }
+        catch {
+            return source.projectRoot === targetRoot;
+        }
+    });
+    if (isDuplicate) {
+        return { message: `Source "${targetRoot}" already added.`, success: false };
+    }
+    // 7. Not circular
+    if (detectCircularSource(canonicalProjectRoot, targetRoot)) {
+        return {
+            message: `Circular source detected: "${basename(targetRoot)}" already references this project as a source.`,
+            success: false,
+        };
+    }
+    // 8. Derive alias — reject empty/whitespace-only
+    if (alias !== undefined && alias.trim() === '') {
+        return { message: 'Alias must not be empty.', success: false };
+    }
+    const derivedAlias = alias ?? basename(targetRoot);
+    // 9. Ensure alias uniqueness — append suffix if collision
+    const finalAlias = ensureUniqueAlias(derivedAlias, existing.data.sources);
+    // 10. Append and write
+    const newSource = {
+        addedAt: new Date().toISOString(),
+        alias: finalAlias,
+        projectRoot: targetRoot,
+        readOnly: true,
+    };
+    existing.data.sources.push(newSource);
+    writeSourcesFile(projectRoot, existing.data);
+    return { message: `Added source "${targetRoot}" as "${finalAlias}".`, success: true };
+}
+// ============================================================================
+// Remove source
+// ============================================================================
+/**
+ * Removes a knowledge source by alias or path.
+ */
+export function removeSource(projectRoot, aliasOrPath) {
+    const existing = readSourcesFile(projectRoot);
+    if (existing.error) {
+        return { message: existing.error, success: false };
+    }
+    if (existing.data.sources.length === 0) {
+        return { message: 'No knowledge sources configured.', success: false };
+    }
+    // Try match by alias first, then by canonical path
+    let matchIndex = existing.data.sources.findIndex((source) => source.alias === aliasOrPath);
+    if (matchIndex === -1) {
+        // Try matching by path
+        let canonicalTarget;
+        try {
+            canonicalTarget = realpathSync(aliasOrPath);
+        }
+        catch {
+            canonicalTarget = aliasOrPath;
+        }
+        matchIndex = existing.data.sources.findIndex((source) => {
+            try {
+                return realpathSync(source.projectRoot) === canonicalTarget;
+            }
+            catch {
+                return source.projectRoot === canonicalTarget;
+            }
+        });
+    }
+    if (matchIndex === -1) {
+        return { message: `No source found matching "${aliasOrPath}".`, success: false };
+    }
+    const removed = existing.data.sources.splice(matchIndex, 1)[0];
+    writeSourcesFile(projectRoot, existing.data);
+    return { message: `Removed source "${removed.alias}" (${removed.projectRoot}).`, success: true };
+}
+/**
+ * Returns status for all sources in the project.
+ * Surfaces malformed file errors instead of silently returning empty.
+ */
+export function listSourceStatuses(projectRoot) {
+    const existing = readSourcesFile(projectRoot);
+    if (existing.error) {
+        return { error: existing.error, statuses: [] };
+    }
+    if (existing.data.sources.length === 0) {
+        return { statuses: [] };
+    }
+    return { statuses: getSourceStatuses(existing.data.sources) };
+}
+// ============================================================================
+// Circular source detection
+// ============================================================================
+/**
+ * Checks if adding projectRoot → targetRoot would create a circular dependency.
+ * A circular reference exists if the target project already has a source pointing
+ * back to the current project (direct cycle only — no transitive check in v1).
+ */
+export function detectCircularSource(projectRoot, targetRoot) {
+    const targetSources = loadSources(targetRoot);
+    if (!targetSources) {
+        return false;
+    }
+    return targetSources.sources.some((source) => {
+        try {
+            return realpathSync(source.projectRoot) === projectRoot;
+        }
+        catch {
+            return source.projectRoot === projectRoot;
+        }
+    });
+}
+function readSourcesFile(projectRoot) {
+    const filePath = join(projectRoot, BRV_DIR, SOURCES_FILE);
+    if (!existsSync(filePath)) {
+        return { data: { sources: [], version: 1 } };
+    }
+    let raw;
+    try {
+        raw = JSON.parse(readFileSync(filePath, 'utf8'));
+    }
+    catch {
+        return {
+            data: { sources: [], version: 1 },
+            error: `Malformed ${SOURCES_FILE}: file is not valid JSON. Back up or delete the file to recover.`,
+        };
+    }
+    const result = SourcesFileSchema.safeParse(raw);
+    if (!result.success) {
+        return {
+            data: { sources: [], version: 1 },
+            error: `Malformed ${SOURCES_FILE}: schema validation failed. Back up or delete the file to recover.`,
+        };
+    }
+    return { data: result.data };
+}
+function writeSourcesFile(projectRoot, data) {
+    const filePath = join(projectRoot, BRV_DIR, SOURCES_FILE);
+    writeFileSync(filePath, JSON.stringify(data, null, 2) + '\n', 'utf8');
+}
+function ensureUniqueAlias(baseAlias, existingSources) {
+    const existingAliases = new Set(existingSources.map((source) => source.alias));
+    if (!existingAliases.has(baseAlias)) {
+        return baseAlias;
+    }
+    let counter = 2;
+    while (existingAliases.has(`${baseAlias}-${counter}`)) {
+        counter++;
+    }
+    return `${baseAlias}-${counter}`;
+}

package/dist/server/core/domain/source/source-schema.d.ts

@@ -0,0 +1,94 @@
+import { z } from 'zod';
+export declare const SourceSchema: z.ZodObject<{
+    addedAt: z.ZodString;
+    alias: z.ZodString;
+    projectRoot: z.ZodString;
+    readOnly: z.ZodLiteral<true>;
+}, "strip", z.ZodTypeAny, {
+    addedAt: string;
+    alias: string;
+    projectRoot: string;
+    readOnly: true;
+}, {
+    addedAt: string;
+    alias: string;
+    projectRoot: string;
+    readOnly: true;
+}>;
+export declare const SourcesFileSchema: z.ZodObject<{
+    sources: z.ZodArray<z.ZodObject<{
+        addedAt: z.ZodString;
+        alias: z.ZodString;
+        projectRoot: z.ZodString;
+        readOnly: z.ZodLiteral<true>;
+    }, "strip", z.ZodTypeAny, {
+        addedAt: string;
+        alias: string;
+        projectRoot: string;
+        readOnly: true;
+    }, {
+        addedAt: string;
+        alias: string;
+        projectRoot: string;
+        readOnly: true;
+    }>, "many">;
+    version: z.ZodLiteral<1>;
+}, "strip", z.ZodTypeAny, {
+    version: 1;
+    sources: {
+        addedAt: string;
+        alias: string;
+        projectRoot: string;
+        readOnly: true;
+    }[];
+}, {
+    version: 1;
+    sources: {
+        addedAt: string;
+        alias: string;
+        projectRoot: string;
+        readOnly: true;
+    }[];
+}>;
+export type Source = z.infer<typeof SourceSchema>;
+export type SourcesFile = z.infer<typeof SourcesFileSchema>;
+export interface SearchOrigin {
+    alias?: string;
+    contextTreeRoot: string;
+    origin: 'local' | 'shared';
+    originKey: string;
+}
+/**
+ * Derives a stable, short origin key from a canonical path.
+ * Uses first 12 hex chars of SHA-256 to avoid alias-based collisions.
+ */
+export declare function deriveOriginKey(canonicalPath: string): string;
+export interface LoadedSources {
+    mtime: number;
+    /** Search origins derived from valid sources (callers can search them) */
+    origins: SearchOrigin[];
+    /** All configured sources (including broken ones — for status display) */
+    sources: Source[];
+}
+/**
+ * Loads and validates `.brv/sources.json` from a project root.
+ *
+ * Returns null if the file does not exist.
+ * Broken sources (target `.brv/` missing) are included in `sources` but excluded
+ * from `origins` — callers decide how to surface them (status vs search).
+ */
+export declare function loadSources(projectRoot: string): LoadedSources | null;
+export interface SourceStatus {
+    alias: string;
+    contextTreeSize?: number;
+    projectRoot: string;
+    valid: boolean;
+}
+/**
+ * Validates each source and returns status for display.
+ *
+ * A source is valid only when both `.brv/config.json` AND `.brv/context-tree/`
+ * exist — matching what loadSources() requires before including a source in
+ * search origins. When valid, `contextTreeSize` counts `.md` files.
+ */
+export declare function getSourceStatuses(sources: Source[]): SourceStatus[];

package/dist/server/core/domain/source/source-schema.js

@@ -0,0 +1,121 @@
+import { createHash } from 'node:crypto';
+import { existsSync, readdirSync, readFileSync, realpathSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { z } from 'zod';
+import { BRV_DIR, CONTEXT_TREE_DIR, PROJECT_CONFIG_FILE, SOURCES_FILE } from '../../../constants.js';
+// ============================================================================
+// Schema
+// ============================================================================
+export const SourceSchema = z.object({
+    addedAt: z.string(),
+    alias: z.string().min(1),
+    projectRoot: z.string().min(1),
+    readOnly: z.literal(true),
+});
+export const SourcesFileSchema = z.object({
+    sources: z.array(SourceSchema),
+    version: z.literal(1),
+});
+/**
+ * Derives a stable, short origin key from a canonical path.
+ * Uses first 12 hex chars of SHA-256 to avoid alias-based collisions.
+ */
+export function deriveOriginKey(canonicalPath) {
+    return createHash('sha256').update(canonicalPath).digest('hex').slice(0, 12);
+}
+/**
+ * Loads and validates `.brv/sources.json` from a project root.
+ *
+ * Returns null if the file does not exist.
+ * Broken sources (target `.brv/` missing) are included in `sources` but excluded
+ * from `origins` — callers decide how to surface them (status vs search).
+ */
+export function loadSources(projectRoot) {
+    const filePath = join(projectRoot, BRV_DIR, SOURCES_FILE);
+    if (!existsSync(filePath)) {
+        return null;
+    }
+    const mtime = statSync(filePath).mtimeMs;
+    let raw;
+    try {
+        raw = JSON.parse(readFileSync(filePath, 'utf8'));
+    }
+    catch {
+        return { mtime, origins: [], sources: [] };
+    }
+    const result = SourcesFileSchema.safeParse(raw);
+    if (!result.success) {
+        return { mtime, origins: [], sources: [] };
+    }
+    const origins = [];
+    for (const source of result.data.sources) {
+        const targetConfigPath = join(source.projectRoot, BRV_DIR, PROJECT_CONFIG_FILE);
+        if (!existsSync(targetConfigPath)) {
+            // Broken source — skip from origins but keep in sources for status display
+            continue;
+        }
+        let canonicalRoot;
+        try {
+            canonicalRoot = realpathSync(source.projectRoot);
+        }
+        catch {
+            continue;
+        }
+        const contextTreeRoot = join(canonicalRoot, BRV_DIR, CONTEXT_TREE_DIR);
+        if (!existsSync(contextTreeRoot)) {
+            continue;
+        }
+        origins.push({
+            alias: source.alias,
+            contextTreeRoot,
+            origin: 'shared',
+            originKey: deriveOriginKey(canonicalRoot),
+        });
+    }
+    return { mtime, origins, sources: result.data.sources };
+}
+/**
+ * Validates each source and returns status for display.
+ *
+ * A source is valid only when both `.brv/config.json` AND `.brv/context-tree/`
+ * exist — matching what loadSources() requires before including a source in
+ * search origins. When valid, `contextTreeSize` counts `.md` files.
+ */
+export function getSourceStatuses(sources) {
+    return sources.map((source) => {
+        const targetConfigPath = join(source.projectRoot, BRV_DIR, PROJECT_CONFIG_FILE);
+        const targetContextTree = join(source.projectRoot, BRV_DIR, CONTEXT_TREE_DIR);
+        const valid = existsSync(targetConfigPath) && existsSync(targetContextTree);
+        let contextTreeSize;
+        if (valid) {
+            contextTreeSize = countMarkdownFiles(targetContextTree);
+        }
+        return {
+            alias: source.alias,
+            contextTreeSize,
+            projectRoot: source.projectRoot,
+            valid,
+        };
+    });
+}
+/**
+ * Recursively counts .md files in a directory.
+ */
+function countMarkdownFiles(dir) {
+    let count = 0;
+    try {
+        const entries = readdirSync(dir, { withFileTypes: true });
+        for (const entry of entries) {
+            if (entry.isDirectory()) {
+                count += countMarkdownFiles(join(dir, entry.name));
+            }
+            else if (entry.isFile() && entry.name.endsWith('.md')) {
+                count++;
+            }
+        }
+    }
+    catch {
+        // Directory unreadable — return 0
+    }
+    return count;
+}

package/dist/server/core/domain/transport/schemas.d.ts

@@ -515,24 +515,28 @@ export declare const TaskExecuteSchema: z.ZodObject<{
     taskId: z.ZodString;
     /** Task type */
     type: z.ZodEnum<["curate", "curate-folder", "query"]>;
+    /** Workspace root for scoped query/curate */
+    worktreeRoot: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
     type: "curate" | "query" | "curate-folder";
     content: string;
     taskId: string;
     clientId: string;
     files?: string[] | undefined;
-    projectPath?: string | undefined;
-    folderPath?: string | undefined;
     clientCwd?: string | undefined;
+    folderPath?: string | undefined;
+    projectPath?: string | undefined;
+    worktreeRoot?: string | undefined;
 }, {
     type: "curate" | "query" | "curate-folder";
     content: string;
     taskId: string;
     clientId: string;
     files?: string[] | undefined;
-    projectPath?: string | undefined;
-    folderPath?: string | undefined;
     clientCwd?: string | undefined;
+    folderPath?: string | undefined;
+    projectPath?: string | undefined;
+    worktreeRoot?: string | undefined;
 }>;
 /**
  * task:cancel - Transport tells Agent to cancel a task
@@ -689,15 +693,15 @@ export declare const TaskCreatedSchema: z.ZodObject<{
     content: string;
     taskId: string;
     files?: string[] | undefined;
-    folderPath?: string | undefined;
     clientCwd?: string | undefined;
+    folderPath?: string | undefined;
 }, {
     type: "curate" | "query" | "curate-folder";
     content: string;
     taskId: string;
     files?: string[] | undefined;
-    folderPath?: string | undefined;
     clientCwd?: string | undefined;
+    folderPath?: string | undefined;
 }>;
 /**
  * task:started - Agent begins processing the task
@@ -960,22 +964,26 @@ export declare const TaskCreateRequestSchema: z.ZodObject<{
     taskId: z.ZodString;
     /** Task type */
     type: z.ZodEnum<["curate", "curate-folder", "query"]>;
+    /** Workspace root for scoped query/curate (stable linked root or projectRoot if unlinked) */
+    worktreeRoot: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
     type: "curate" | "query" | "curate-folder";
     content: string;
     taskId: string;
     files?: string[] | undefined;
-    projectPath?: string | undefined;
-    folderPath?: string | undefined;
     clientCwd?: string | undefined;
+    folderPath?: string | undefined;
+    projectPath?: string | undefined;
+    worktreeRoot?: string | undefined;
 }, {
     type: "curate" | "query" | "curate-folder";
     content: string;
     taskId: string;
     files?: string[] | undefined;
-    projectPath?: string | undefined;
-    folderPath?: string | undefined;
     clientCwd?: string | undefined;
+    folderPath?: string | undefined;
+    projectPath?: string | undefined;
+    worktreeRoot?: string | undefined;
 }>;
 /**
  * Response after task creation

package/dist/server/core/domain/transport/schemas.js

@@ -315,6 +315,8 @@ export const TaskExecuteSchema = z.object({
     taskId: z.string(),
     /** Task type */
     type: z.enum(['curate', 'curate-folder', 'query']),
+    /** Workspace root for scoped query/curate */
+    worktreeRoot: z.string().optional(),
 });
 /**
  * task:cancel - Transport tells Agent to cancel a task
@@ -492,6 +494,8 @@ export const TaskCreateRequestSchema = z.object({
     taskId: z.string().uuid('Invalid taskId format - must be UUID'),
     /** Task type */
     type: TaskTypeSchema,
+    /** Workspace root for scoped query/curate (stable linked root or projectRoot if unlinked) */
+    worktreeRoot: z.string().optional(),
 });
 /**
  * Response after task creation

package/dist/server/core/domain/transport/task-info.d.ts

@@ -18,4 +18,6 @@ export type TaskInfo = {
     projectPath?: string;
     taskId: string;
     type: TaskType;
+    /** Workspace root (linked subdir or projectRoot if unlinked) */
+    worktreeRoot?: string;
 };

package/dist/server/core/interfaces/client/i-client-manager.d.ts

@@ -114,4 +114,17 @@ export interface IClientManager {
      * @param clientId - The client's Socket.IO ID
      */
     unregister(clientId: string): void;
+    /**
+     * Update a client's project path, even if already associated.
+     * Used for reassociation after worktree add/remove operations.
+     * Moves the client from the old project index to the new one,
+     * and fires onProjectEmpty if the old project has no remaining external clients.
+     *
+     * No-op if client is unknown.
+     *
+     * @param clientId - The client's Socket.IO ID
+     * @param newProjectPath - The new project path to associate
+     * @returns The previous project path (undefined if client not found or not previously associated)
+     */
+    updateProjectPath(clientId: string, newProjectPath: string): string | undefined;
 }

package/dist/server/core/interfaces/executor/i-curate-executor.d.ts

@@ -10,8 +10,12 @@ export interface CurateExecuteOptions {
     content: string;
     /** Optional file paths for --files flag */
     files?: string[];
+    /** Canonical project root where .brv/ lives (for post-processing: snapshot, summary, manifest) */
+    projectRoot?: string;
     /** Task ID for event routing (required for concurrent task isolation) */
     taskId: string;
+    /** Workspace root — linked subdir or same as projectRoot for direct projects */
+    worktreeRoot?: string;
 }
 /**
  * ICurateExecutor - Executes curate tasks with an injected CipherAgent.

package/dist/server/core/interfaces/executor/i-folder-pack-executor.d.ts

@@ -4,14 +4,18 @@ import type { ICipherAgent } from '../../../../agent/core/interfaces/i-cipher-ag
  * Agent uses its default session (Single-Session pattern).
  */
 export interface FolderPackExecuteOptions {
-    /** Client's working directory for resolving relative paths */
+    /** Client's working directory for resolving relative paths (shell semantics) */
     clientCwd?: string;
     /** Optional context to guide the analysis */
     content?: string;
-    /** Folder path to pack (relative to clientCwd or absolute) */
-    folderPath: string;
+    /** Folder path to pack (relative to clientCwd or absolute). When absent, defaults to worktreeRoot. */
+    folderPath?: string;
+    /** Canonical project root where .brv/ lives (for temp file location) */
+    projectRoot?: string;
     /** Task ID for event routing (required for concurrent task isolation) */
     taskId: string;
+    /** Workspace root — linked subdir or same as projectRoot. Used as default folderPath when none supplied. */
+    worktreeRoot?: string;
 }
 /**
  * IFolderPackExecutor - Executes folder pack + curate tasks with an injected CipherAgent.

package/dist/server/core/interfaces/executor/i-query-executor.d.ts

@@ -8,6 +8,8 @@ export interface QueryExecuteOptions {
     query: string;
     /** Task ID for event routing (required for concurrent task isolation) */
     taskId: string;
+    /** Stable workspace root for scoping search and cache isolation */
+    worktreeRoot?: string;
 }
 /**
  * IQueryExecutor - Executes query tasks with an injected CipherAgent.

package/dist/server/infra/client/client-manager.d.ts

@@ -41,6 +41,7 @@ export declare class ClientManager implements IClientManager {
     register(clientId: string, type: ClientType, projectPath?: string): void;
     setAgentName(clientId: string, agentName: string): void;
     unregister(clientId: string): void;
+    updateProjectPath(clientId: string, newProjectPath: string): string | undefined;
     private addToProjectIndex;
     /**
      * Check if a project has no remaining external clients.

package/dist/server/infra/client/client-manager.js

@@ -111,6 +111,22 @@ export class ClientManager {
         // Notify idle timeout policy
         this.clientDisconnectedCallback?.();
     }
+    updateProjectPath(clientId, newProjectPath) {
+        const client = this.clients.get(clientId);
+        if (!client)
+            return undefined;
+        const oldPath = client.updateProjectPath(newProjectPath);
+        // Move between project indexes
+        if (oldPath) {
+            this.removeFromProjectIndex(clientId, oldPath);
+        }
+        this.addToProjectIndex(clientId, newProjectPath);
+        // Check if old project is now empty
+        if (oldPath && oldPath !== newProjectPath && client.isExternalClient) {
+            this.checkProjectEmpty(oldPath);
+        }
+        return oldPath;
+    }
     addToProjectIndex(clientId, projectPath) {
         let members = this.projectClients.get(projectPath);
         if (!members) {

package/dist/server/infra/context-tree/derived-artifact.js

@@ -6,7 +6,7 @@
  * - isArchiveStub()      — searchable stubs (included in BM25 index and fingerprint)
  * - isExcludedFromSync() — union of above (excluded from snapshot/sync/merge/push)
  */
-import { ARCHIVE_DIR, FULL_ARCHIVE_EXTENSION, MANIFEST_FILE, STUB_EXTENSION, SUMMARY_INDEX_FILE } from '../../constants.js';
+import { ABSTRACT_EXTENSION, ARCHIVE_DIR, FULL_ARCHIVE_EXTENSION, MANIFEST_FILE, OVERVIEW_EXTENSION, STUB_EXTENSION, SUMMARY_INDEX_FILE } from '../../constants.js';
 import { toUnixPath } from './path-utils.js';
 /**
  * Returns true if the given relative path is a derived artifact
@@ -24,6 +24,10 @@ export function isDerivedArtifact(relativePath) {
         return true;
     if (fileName === MANIFEST_FILE)
         return true;
+    if (fileName.endsWith(ABSTRACT_EXTENSION))
+        return true;
+    if (fileName.endsWith(OVERVIEW_EXTENSION))
+        return true;
     if (segments.includes(ARCHIVE_DIR) && fileName.endsWith(FULL_ARCHIVE_EXTENSION))
         return true;
     return false;

package/dist/server/infra/context-tree/file-context-tree-manifest-service.d.ts

@@ -44,7 +44,8 @@ export declare class FileContextTreeManifestService implements IContextTreeManif
     private scanForManifest;
     /**
      * Recursively collect stat data for all source files (for fingerprint).
-     * Excludes derived artifacts.
+     * Excludes derived artifacts except .abstract.md siblings, which are included
+     * so abstract generation invalidates the manifest without a second tree walk.
      */
     private scanSourceStats;
 }