spectra-cli 4.2.0 → 4.3.0

package/dist/batch/batch-orchestrator.js

@@ -20,10 +20,11 @@ import { estimateModuleCost, buildDryRunReport, renderDryRunReport, runBudgetGat
 import { decideModelOverride } from './model-override-decision.js';
 import { createLogger } from '../panoramic/utils/logger.js';
 import { groupFilesToModules } from './module-grouper.js';
+import { buildSpecCacheKey, normalizeProjectPath, resolveRegenPlan, resolveSourceTarget } from './regen-plan.js';
 import { groupFilesByLanguage } from './language-grouper.js';
-import { scanFiles } from '../utils/file-scanner.js';
+import { scanFiles, createGitignoreFilter } from '../utils/file-scanner.js';
 import { LanguageAdapterRegistry } from '../adapters/language-adapter-registry.js';
-import { buildDocGraph, runAnchorIntegration, runHyperedgeIntegration, scanStoredModuleSpecs, } from '../panoramic/builders/doc-graph-builder.js';
+import { buildDocGraph, isBatchGenerated, runAnchorIntegration, runHyperedgeIntegration, scanStoredModuleSpecs, } from '../panoramic/builders/doc-graph-builder.js';
 import { chunkMarkdownFiles } from '../panoramic/anchoring/chunker.js';
 import { createEmbeddingProvider } from '../panoramic/anchoring/providers/factory.js';
 import { DOC_NODE_KINDS } from '../panoramic/hyperedges/constants.js';
@@ -37,12 +38,13 @@ import { detectAuth } from '../auth/auth-detector.js';
 import { orchestrateDocsBundle } from '../panoramic/pipelines/docs-bundle-orchestrator.js';
 import { generateDebtIntelligence, } from '../panoramic/pipelines/debt-intelligence-pipeline.js';
 import { BATCH_OUTPUT_SUBDIRS } from '../panoramic/output-filenames.js';
-import { buildKnowledgeGraph, writeKnowledgeGraph } from '../panoramic/graph/index.js';
+import { buildKnowledgeGraph, writeKnowledgeGraph, normalizeGraphForWrite } from '../panoramic/graph/index.js';
 import { buildUnifiedGraph, setCurrentUnifiedGraph, getCurrentUnifiedGraph, } from '../knowledge-graph/index.js';
 import { buildHtmlTemplate } from '../panoramic/exporters/html-template.js';
 import { SpecStore } from '../spec-store/index.js';
 import { createRequire } from 'node:module';
-import { resolvePythonImport, resolveTsJsImport, findNearestTsConfig, buildTsConfigContext, } from '../knowledge-graph/import-resolver.js';
+import { resolvePythonImport } from '../knowledge-graph/import-resolver.js';
+import { resolveTsJsImport, findNearestTsConfig, buildTsConfigContext, } from '../core/import-resolver.js';
 // 从 package.json 读取版本号（避免硬编码）
 const _require = createRequire(import.meta.url);
 const SPECTRA_VERSION = _require('../../package.json').version;
@@ -64,6 +66,39 @@ const logger = createLogger('batch-orchestrator');
 // ============================================================
 // 内部辅助函数
 // ============================================================
+/**
+ * Feature 182 修复面 4：checkpoint replace 语义（completed/failed 互斥去重）。
+ *
+ * 背景：F175 给 checkpoint 加了「mustRegen 失效重跑」（fall-through）语义，但 completedModules
+ * 仍沿用 append-only 写法——已完成 module 被重跑后会二次 push，导致 resume 进度超 totalModules，
+ * 且 completed / failed 可能交叉污染（同一 module 同时出现在两个集合）。
+ *
+ * 本 helper 以 path 为身份键先剔除两个集合中的同名旧条目，再 push 到目标集合，保证：
+ *   (1) 同一 module 在每个集合最多出现一次；(2) completed 与 failed 互斥。
+ *
+ * 注意：helper 内不得有 await——JS 单线程下同步段不被 pLimit 并发交错，
+ * 保持纯同步可防未来插入 await 后语义退化为「读-改-写」竞态。
+ */
+function upsertCompletedModule(state, entry) {
+    state.completedModules = state.completedModules.filter((m) => m.path !== entry.path);
+    state.failedModules = state.failedModules.filter((m) => m.path !== entry.path);
+    state.completedModules.push(entry);
+}
+function recordFailedModule(state, entry) {
+    state.failedModules = state.failedModules.filter((m) => m.path !== entry.path);
+    state.completedModules = state.completedModules.filter((m) => m.path !== entry.path);
+    state.failedModules.push(entry);
+}
+/**
+ * F175 FR-017/EC-009：判定 absPath 是否位于受管 modules/ 输出目录内（孤儿删除 ownership 必要条件2）。
+ *
+ * 用 path.relative 判定目录归属，禁用字符串 startsWith——否则 `specs/modules-old/...` 这类
+ * sibling 目录会被前缀匹配误判为受管目录（目录穿越）。同时校验 .spec.md 后缀。
+ */
+function isInManagedOutputDir(absPath, modulesDir) {
+    const rel = path.relative(modulesDir, path.resolve(absPath));
+    return !rel.startsWith('..') && !path.isAbsolute(rel) && absPath.endsWith('.spec.md');
+}
 /**
  * 合并多个语言的 ModuleGraph 用于全局拓扑排序
  * 仅合并 modules 和 edges，SCC/Mermaid 按语言独立保留（TD-002 选项 C）
@@ -172,7 +207,14 @@ export async function runBatch(projectRoot, options = {}) {
     const effectiveMode = options.mode ?? 'full';
     // F5：FR-006 — 日志输出当前 mode
     logger.info(`[info] batch mode: ${effectiveMode}`);
-    const { force = false, incremental = false, maxRetries = 3, outputDir = 'specs', } = options;
+    const { maxRetries = 3, outputDir = 'specs', } = options;
+    // F175 FR-002：唯一默认值来源——对直接调用方兜底解析 RegenPlan（CLI/MCP 已在各自入口解析后传入有效值）。
+    // 删除原 `incremental = false` 硬编码，默认增量（regenPlan.incremental）由 resolveRegenPlan 决定（FR-001）。
+    const regenPlan = resolveRegenPlan({
+        incremental: options.incremental,
+        full: options.full,
+        force: options.force,
+    });
     const startTime = Date.now();
     const resolvedRoot = path.resolve(projectRoot);
     const resolvedOutputDir = path.isAbsolute(outputDir)
@@ -187,7 +229,6 @@ export async function runBatch(projectRoot, options = {}) {
         const rel = path.relative(resolvedRoot, absPath);
         return rel.startsWith('..') ? absPath : rel;
     };
-    const normalizeProjectPath = (inputPath) => inputPath.split(path.sep).join('/');
     // 步骤 1：扫描文件获取 languageStats
     const scanResult = scanFiles(resolvedRoot, { projectRoot: resolvedRoot });
     const languageStats = scanResult.languageStats;
@@ -237,42 +278,34 @@ export async function runBatch(projectRoot, options = {}) {
     const moduleGroups = new Map(groupResult.groups.map((g) => [g.name, g]));
     const rootModuleName = options.grouping?.rootModuleName ?? 'root';
     const existingStoredSpecs = scanStoredModuleSpecs(resolvedOutputDir, resolvedRoot);
-    const storedSpecByTarget = new Map(existingStoredSpecs.map((spec) => [spec.sourceTarget, spec]));
+    // Feature 182：以 cache key 入索引（languageSplit 组带 `::language` 后缀），与 processOneModule
+    // 的 moduleCacheKey 口径对齐；旧 spec 无 sourceTargetKey 时回落纯路径 sourceTarget。
+    const storedSpecByTarget = new Map(existingStoredSpecs.map((spec) => [spec.sourceTargetKey ?? spec.sourceTarget, spec]));
+    // F175：全量逃生口（--full / --force 合并为 regenPlan.full）打可观测日志，
+    // 替代原 fallbackReason='force-enabled' 内部信号（W-1 取舍）。
+    if (regenPlan.full) {
+        logger.info(`[regen] full regeneration (source=${regenPlan.source})`);
+    }
+    // F175：仅增量路径（regenPlan.incremental）调用 DeltaRegenerator；full 路径直接走全量。
     let deltaReport;
-    if (incremental) {
-        if (force) {
-            deltaReport = {
-                title: 'Delta Regeneration Report',
-                generatedAt: new Date().toISOString(),
-                projectRoot: resolvedRoot,
-                mode: 'full',
-                totalTargets: groupResult.groups.reduce((sum, group) => {
-                    const isRootGroup = group.name === rootModuleName || group.name.startsWith(`${rootModuleName}--`);
-                    return sum + (isRootGroup ? group.files.length : 1);
-                }, 0),
-                regenerateTargets: [],
-                directChanges: [],
-                propagatedChanges: [],
-                unchangedTargets: [],
-                fallbackReason: 'force-enabled',
-            };
-        }
-        else {
-            const deltaRegenerator = new DeltaRegenerator();
-            deltaReport = await deltaRegenerator.plan({
-                projectRoot: resolvedRoot,
-                dependencyGraph: mergedGraph,
-                moduleGroups: groupResult.groups,
-                storedSpecs: existingStoredSpecs,
-                // Bug 142：传入 effectiveMode 启用 mode-aware cache，
-                // 旧 spec（无 generatedByMode）或 mode 不匹配时强制 cache miss。
-                effectiveMode,
-            });
-        }
+    if (regenPlan.incremental) {
+        const deltaRegenerator = new DeltaRegenerator();
+        deltaReport = await deltaRegenerator.plan({
+            projectRoot: resolvedRoot,
+            dependencyGraph: mergedGraph,
+            moduleGroups: groupResult.groups,
+            storedSpecs: existingStoredSpecs,
+            // Bug 142：传入 effectiveMode 启用 mode-aware cache，
+            // 旧 spec（无 generatedByMode）或 mode 不匹配时强制 cache miss。
+            effectiveMode,
+        });
     }
     const regenerateTargets = new Set(deltaReport?.regenerateTargets ?? []);
-    const forceFullRegeneration = force || (incremental && deltaReport?.mode === 'full');
-    const shouldUseIncrementalPlan = incremental && !force && deltaReport?.mode === 'incremental';
+    // EC-001 force/full 优先：regenPlan.full 直接全量；增量路径 deltaReport.mode==='full'
+    //（首次运行 / 无历史 spec / mode 切换）退化全量仍走 forceFullRegeneration。
+    // Feature 182：改为 let——full-resume 时序修复需在 checkpoint 加载后回写（见下方 isResume 块）。
+    let forceFullRegeneration = regenPlan.full || (regenPlan.incremental && deltaReport?.mode === 'full');
+    let shouldUseIncrementalPlan = regenPlan.incremental && deltaReport?.mode === 'incremental';
     console.log(`发现 ${mergedGraph.modules.length} 个文件，聚合为 ${processingOrder.length} 个模块`);
     if (isMultiLang) {
         console.log(`检测到 ${processedLanguages.length} 种语言: ${processedLanguages.join(', ')}`);
@@ -363,6 +396,18 @@ export async function runBatch(projectRoot, options = {}) {
     }
     // 步骤 3：检查是否存在检查点
     let state = loadCheckpoint(checkpointPath);
+    // F175 FR-016/EC-007：full/force 启动时丢弃已加载的 checkpoint completed + failed state，
+    // 防止残留 checkpoint 命中导致全量语义被绕过（必须在 completedPaths 构建前清空——
+    // 加载时即清，而非在 processOneModule 内"忽略"，避免中途崩溃 resume 复用脏 set）。
+    // W-1：必须同时清空 failedModules——否则 full 后 summary（:1749 起用 checkedState.failedModules）
+    // 仍混入上一轮的旧失败详情，与"full 是干净全量"语义矛盾。
+    if (state &&
+        regenPlan.full &&
+        (state.completedModules.length > 0 || state.failedModules.length > 0)) {
+        logger.info(`[regen] full regeneration 丢弃残留 checkpoint state（completed ${state.completedModules.length} / failed ${state.failedModules.length} 模块）`);
+        state = { ...state, completedModules: [], failedModules: [] };
+        saveCheckpoint(state, checkpointPath);
+    }
     const isResume = state !== null;
     if (!state) {
         state = {
@@ -374,7 +419,7 @@ export async function runBatch(projectRoot, options = {}) {
             processingOrder,
             completedModules: [],
             failedModules: [],
-            forceRegenerate: force,
+            forceRegenerate: regenPlan.full,
             // 多语言扩展字段
             languageGroups: isMultiLang
                 ? Object.fromEntries(languageGroupsList.map((g) => [g.adapterId, g.files]))
@@ -384,6 +429,17 @@ export async function runBatch(projectRoot, options = {}) {
     }
     if (isResume) {
         console.log(`恢复断点: 已完成 ${state.completedModules.length}/${state.totalModules} 模块`);
+        // Feature 182 修复面 5：恢复中断的 --full run 意图。
+        // 背景：首轮 --full 把 forceRegenerate=true 落盘到 checkpoint（:660），但 runtime 仅用本轮
+        // regenPlan 重算的 forceFullRegeneration——裸增量 resume 时为 false，剩余模块静默降级为增量，
+        // 产出半新半旧混合产物。此处从 checkpoint 恢复 full 意图，剩余模块继续全量。
+        // 时序安全：两变量消费点全在 processOneModule 内（在此回写之后才被调用）。
+        // 注意：full-resume 不清空 completed（:636 清空条件用 regenPlan.full 而非本变量），正是 resume 语义。
+        if (state.forceRegenerate && !forceFullRegeneration) {
+            forceFullRegeneration = true;
+            shouldUseIncrementalPlan = false;
+            logger.info('[resume] 检测到中断的 full run，剩余模块继续全量');
+        }
     }
     // 步骤 4：按模块级拓扑顺序处理
     // Feature 146 FR-010/FR-011：通过 getActiveCount getter 注入 limit.activeCount，
@@ -443,16 +499,30 @@ export async function runBatch(projectRoot, options = {}) {
         const group = moduleGroups.get(moduleName);
         if (!group)
             return;
-        if (completedPaths.has(moduleName))
-            return;
         const isRoot = moduleName === rootModuleName || moduleName.startsWith(`${rootModuleName}--`);
         const specPath = path.join(modulesDir, `${moduleName}.spec.md`);
-        // H4 修复：文件级降级场景下 moduleSourceTarget 须与 targetPath 保持一致（文件路径）
-        // 否则 --incremental 的 regenerateTargets 查询和 storedSpecByTarget 查询全部错位
-        const hasDirPathConflict = !isRoot && group.files.length === 1 && conflictingDirPaths.has(group.dirPath);
-        const moduleSourceTarget = hasDirPathConflict
-            ? normalizeProjectPath(group.files[0])
-            : normalizeProjectPath(group.dirPath);
+        // FR-019：target 口径与 DeltaRegenerator 共用 resolveSourceTarget（文件级降级分支一致），
+        // 否则 --incremental 的 regenerateTargets 查询和 storedSpecByTarget 查询全部错位。
+        // T020：target 计算前移到 checkpoint 判定之前，供增量 resume 失效判定使用。
+        const moduleSourceTarget = resolveSourceTarget(group, conflictingDirPaths, isRoot);
+        // Feature 182：cache key（languageSplit 组带 `::language` 后缀），用于 regenerateTargets /
+        // storedSpecByTarget / existingVersion 查询，消除同目录多语言组键碰撞；targetPath 与
+        // frontmatter 继续用纯路径 moduleSourceTarget（statSync 路径 + panoramic 匹配口径不变）。
+        const moduleCacheKey = buildSpecCacheKey(moduleSourceTarget, group);
+        // F175 FR-016：checkpoint 判定。full 路径已在加载时清空 completedPaths（必为干净）；
+        // 增量 resume 下若 checkpoint 命中但本轮 delta 要求重生成该 target，则失效重跑。
+        // C-3：root 模块的 regenerateTargets 是文件级（DeltaRegenerator 对 root 按每个文件
+        // 产出 snapshot），但 moduleSourceTarget（root 时为 group.dirPath）不在文件级集合里，
+        // 用 dirPath 查永远 miss → mustRegen=false → root 文件变更时 checkpoint 命中被错误跳过。
+        // 故 root 模块改判 group.files 中任一文件 target 是否命中 regenerateTargets。
+        if (completedPaths.has(moduleName)) {
+            const mustRegen = shouldUseIncrementalPlan &&
+                (isRoot
+                    ? group.files.some((filePath) => regenerateTargets.has(normalizeProjectPath(filePath)))
+                    : regenerateTargets.has(moduleCacheKey));
+            if (!mustRegen)
+                return;
+        }
         const rootTargetsToGenerate = isRoot
             ? group.files
                 .map((filePath) => normalizeProjectPath(filePath))
@@ -475,7 +545,7 @@ export async function runBatch(projectRoot, options = {}) {
         else {
             const shouldGenerate = forceFullRegeneration
                 || (shouldUseIncrementalPlan
-                    ? regenerateTargets.has(moduleSourceTarget)
+                    ? regenerateTargets.has(moduleCacheKey)
                     : !fs.existsSync(specPath));
             if (!shouldGenerate) {
                 skipped.push(moduleName);
@@ -589,24 +659,32 @@ export async function runBatch(projectRoot, options = {}) {
                     }
                     successful.push(moduleName);
                     reporter.complete(moduleName, 'success');
-                    checkedState.completedModules.push({
+                    // Feature 182：replace 语义（失效重跑时去重 + completed/failed 互斥）
+                    upsertCompletedModule(checkedState, {
                         path: moduleName,
                         specPath: generatedRootSpecs[0],
                         completedAt: new Date().toISOString(),
                     });
                 }
                 else {
-                    // BUG-A 修复：同一 dirPath 下有多个单文件模块时（如 graphify/ 下有 a.py/b.py），
-                    // 使用文件路径避免多个模块覆盖同一个 {dirName}.spec.md；
-                    // 否则仍使用目录路径（每个目录只有一个文件时，目录名才是有意义的模块标识）
-                    // 注意：hasDirPathConflict 已在上方计算（H4 修复）
-                    const targetPath = hasDirPathConflict
-                        ? path.join(resolvedRoot, group.files[0])
-                        : path.join(resolvedRoot, group.dirPath);
+                    // BUG-A / H4 修复：targetPath 直接由 moduleSourceTarget 推导（FR-019：resolveSourceTarget
+                    // 已处理"同一 dirPath 多单文件冲突走文件路径"的降级分支），与 sourceTarget 口径保持一致。
+                    const targetPath = path.join(resolvedRoot, moduleSourceTarget);
                     // genOptions.skipEnrichment 已在 L648 处理 reading/code-only 模式分派
                     const result = await generateSpec(targetPath, {
                         ...genOptions,
-                        existingVersion: storedSpecByTarget.get(moduleSourceTarget)?.version,
+                        // Feature 182：注入 group.files（语言限定子集，绝对路径），使写侧只分析本语言文件，
+                        // 与读侧 group.files 文件集口径一致（消除混语言 hash 分叉 + 双倍分析）。
+                        files: group.files.map((f) => path.join(resolvedRoot, f)),
+                        existingVersion: storedSpecByTarget.get(moduleCacheKey)?.version,
+                        // Feature 182 修复 1：仅 languageSplit 组按 moduleName 显式命名输出文件，
+                        // 避免同目录多语言组(ts / py)都派生为同名 `<dir>.spec.md` 互相覆盖；
+                        // 非拆分组不传 → basename 派生，存量单语言仓库命名零变化。
+                        ...(group.languageSplit ? { outputFileName: `${moduleName}.spec.md` } : {}),
+                        // Feature 182 修复 2：languageSplit 组首写即落入 frontmatter.sourceTargetKey，
+                        // 消除「post-mutation 依赖 doc-graph re-render 落盘晚于 checkpoint save」崩溃窗口；
+                        // in-memory moduleSpec.frontmatter 由 generateFrontmatter 返回自然带上。
+                        sourceTargetKey: group.languageSplit ? moduleCacheKey : undefined,
                     });
                     // Bug 142：非 root 分支累积 input token，供 catch 块统一做预算检查。
                     if (result.costMetadata?.tokenUsage.input) {
@@ -631,7 +709,8 @@ export async function runBatch(projectRoot, options = {}) {
                         successful.push(moduleName);
                         reporter.complete(moduleName, 'success');
                     }
-                    checkedState.completedModules.push({
+                    // Feature 182：replace 语义（失效重跑时去重 + completed/failed 互斥）
+                    upsertCompletedModule(checkedState, {
                         path: moduleName,
                         specPath: toProjectPath(path.resolve(result.specPath)),
                         completedAt: new Date().toISOString(),
@@ -686,7 +765,8 @@ export async function runBatch(projectRoot, options = {}) {
                         reason: 'retry-budget-exceeded',
                     };
                     failed.push(failedModule);
-                    checkedState.failedModules.push(failedModule);
+                    // Feature 182：replace 语义（失效重跑时去重 + completed/failed 互斥）
+                    recordFailedModule(checkedState, failedModule);
                     reporter.complete(moduleName, 'failed');
                     break;
                 }
@@ -700,7 +780,8 @@ export async function runBatch(projectRoot, options = {}) {
                         degradedToAstOnly: false,
                     };
                     failed.push(failedModule);
-                    checkedState.failedModules.push(failedModule);
+                    // Feature 182：replace 语义（失效重跑时去重 + completed/failed 互斥）
+                    recordFailedModule(checkedState, failedModule);
                     reporter.complete(moduleName, 'failed');
                 }
             }
@@ -745,7 +826,8 @@ export async function runBatch(projectRoot, options = {}) {
                 reason: 'unhandled-exception',
             };
             failed.push(failedModule);
-            checkedState.failedModules.push(failedModule);
+            // Feature 182：replace 语义（失效重跑时去重 + completed/failed 互斥）
+            recordFailedModule(checkedState, failedModule);
             try {
                 reporter.complete(moduleName, 'failed');
             }
@@ -764,10 +846,63 @@ export async function runBatch(projectRoot, options = {}) {
     let projectDocsResult;
     let docsBundleManifestPath;
     let docsBundleProfiles;
-    // SpecStore 统一查询入口：所有消费方（README、graph、coverage、index、cross-ref）共享此源
+    // F175 FR-017/EC-008/EC-009：删除孤儿 spec（源文件已删除的 batch 产物），使增量产物文件集与全量一致。
+    // 必须在构造 SpecStore 之前执行 + 从 storedSpecs 集合中剔除已删项（C-2）——否则后续
+    // 所有聚合（index/graph/coverage/cross-ref）仍引用陈旧的已删 spec 视图，产生 stale 输出。
+    // 仅在增量/全量路径执行；ownership 边界缺一不删：(1) generatedByMode 存在（batch 专属标记）+
+    // (2) 位于受管 modules/ 输出目录内（path.relative 防目录穿越，禁字符串 startsWith）+
+    // (3) sourceTarget 已无任何在库源文件（EC-008：删除模块最后一个源文件后，空目录仍 existsSync=true，
+    //     故不能仅靠目录存在性判定——以当前扫描到的源文件集合为准）。
+    let storedSpecsForStore = existingStoredSpecs;
+    if (regenPlan.incremental || regenPlan.full) {
+        // 当前扫描到的源文件（项目相对，正斜杠口径），用于判定 sourceTarget 是否仍有活跃源文件
+        const liveSourceFiles = new Set(scanResult.files.map((f) => normalizeProjectPath(f)));
+        const hasLiveSource = (sourceTarget) => {
+            const prefix = `${sourceTarget}/`;
+            for (const f of liveSourceFiles) {
+                if (f === sourceTarget || f.startsWith(prefix))
+                    return true;
+            }
+            return false;
+        };
+        // 已确认删除的孤儿 outputPath 集合，用于从 storedSpecs 中剔除，使 SpecStore 不持有陈旧视图。
+        const deletedOrphanPaths = new Set();
+        for (const orphan of existingStoredSpecs) {
+            if (!isBatchGenerated(orphan))
+                continue; // 必要条件1：无 generatedByMode → 跳过（防误删手写 / 单文件 generate 产物）
+            if (hasLiveSource(orphan.sourceTarget))
+                continue; // 必要条件3：仍有活跃源文件 → 非孤儿
+            const absPath = path.isAbsolute(orphan.outputPath)
+                ? orphan.outputPath
+                : path.join(resolvedRoot, orphan.outputPath);
+            if (!isInManagedOutputDir(absPath, modulesDir))
+                continue; // 必要条件2：受管 modules/ 目录外 → 跳过
+            // 磁盘文件已被本轮其它逻辑清理：视为已删除，从内存视图剔除（保持内存与磁盘一致）。
+            if (!fs.existsSync(absPath)) {
+                deletedOrphanPaths.add(orphan.outputPath);
+                continue;
+            }
+            // W-1（quality-review）：rmSync 是破坏性新操作，权限/OS 错误不应让整个 batch 崩溃。
+            // 失败时 warn + 跳过，且【不】加入 deletedOrphanPaths——文件仍在磁盘，内存视图须保留它，
+            // 避免"内存说已删、磁盘还在"的不一致。仅删除成功才剔除内存视图。
+            try {
+                logger.info(`[orphan-cleanup] 删除孤儿 spec: ${orphan.outputPath}`);
+                fs.rmSync(absPath, { force: true });
+                deletedOrphanPaths.add(orphan.outputPath);
+            }
+            catch (err) {
+                logger.warn(`[orphan-cleanup] 删除孤儿 spec 失败，保守跳过: ${orphan.outputPath}（${err.message}）`);
+            }
+        }
+        if (deletedOrphanPaths.size > 0) {
+            storedSpecsForStore = existingStoredSpecs.filter((spec) => !deletedOrphanPaths.has(spec.outputPath));
+        }
+    }
+    // SpecStore 统一查询入口：所有消费方（README、graph、coverage、index、cross-ref）共享此源。
+    // 使用已剔除孤儿的 storedSpecsForStore，确保后续聚合不引用已删 spec（C-2）。
     const specStore = new SpecStore({
         currentSpecs: collectedModuleSpecs,
-        storedSpecs: existingStoredSpecs,
+        storedSpecs: storedSpecsForStore,
         projectRoot: resolvedRoot,
         toProjectPath,
     });
@@ -1115,6 +1250,11 @@ export async function runBatch(projectRoot, options = {}) {
             catch (communityErr) {
                 logger.warn(`community-analysis: 社区分析失败，跳过报告生成: ${communityErr instanceof Error ? communityErr.message : String(communityErr)}`);
             }
+            // F175 FR-006/FR-007：写盘前归一化（byte-stable）——nodes/links/hyperedges 确定性排序，
+            // 在追加 semantic edges + 社区分析之后调用，覆盖完整边集。
+            // F179：stripTimestamps:true 使 graph.generatedAt 固定为 epoch，落盘 graph.json 真 byte-stable
+            // （此前 F175 仅在测试读取侧 delete generatedAt，是 over-claim；现在落盘侧直接固定）。
+            normalizeGraphForWrite(graphJson, { stripTimestamps: true });
             // 社区分析完成后写盘（graphJson 已含 degree metadata）
             const graphWrittenPath = writeKnowledgeGraph(graphJson, resolvedOutputDir);
             docGraphPath = toProjectPath(graphWrittenPath);
@@ -1374,6 +1514,7 @@ export async function runBatch(projectRoot, options = {}) {
         docGraphPath,
         coverageReportPath,
         deltaReportPath,
+        deltaReport,
         projectDocs,
         docsBundleManifestPath,
         docsBundleProfiles,
@@ -1616,8 +1757,10 @@ export async function collectPythonCodeSkeletons(projectRoot) {
     // 避免调用方传相对路径 → Map key 与 imports[].resolvedPath 形态不一致
     // → call-resolver buildImportIndex lookup miss
     const resolvedProjectRoot = path.resolve(projectRoot);
+    // F194：构建 .gitignore 过滤器，基准 = resolvedProjectRoot（与 walk 内 path.relative 同口径）
+    const isGitignored = createGitignoreFilter(resolvedProjectRoot);
     const pyFiles = [];
-    walkPyFiles(resolvedProjectRoot, pyFiles);
+    walkPyFiles(resolvedProjectRoot, pyFiles, isGitignored, resolvedProjectRoot);
     // Feature 152 P3 T-017：大文件 size guard 提前到 parse 之前（避免 tree-sitter 解析阻塞）
     // 1MB 阈值与 PythonMapper.CALLSITES_MAX_FILE_BYTES 对齐（EC-14）
     const MAX_FILE_BYTES = 1_000_000;
@@ -1695,7 +1838,11 @@ export async function collectPythonCodeSkeletons(projectRoot) {
     }
     return out;
 }
-function walkPyFiles(dir, out) {
+/**
+ * F194：isGitignored 与 resolvedRoot 由 collectPythonCodeSkeletons 构建并通过参数传入，
+ * 在自写 walk 上叠加 .gitignore 过滤层（保留 PY_SKELETON_IGNORE_DIRS 与点前缀剪枝不变）。
+ */
+function walkPyFiles(dir, out, isGitignored, resolvedRoot) {
     let entries;
     try {
         entries = fs.readdirSync(dir, { withFileTypes: true });
@@ -1704,14 +1851,20 @@ function walkPyFiles(dir, out) {
         return;
     }
     for (const entry of entries) {
+        // 基准 = resolvedRoot，path.relative 输出不做 sep 转换（与 file-scanner walkDir 一致）
+        const relPath = path.relative(resolvedRoot, path.join(dir, entry.name));
         if (entry.isDirectory()) {
             if (entry.name.startsWith('.'))
                 continue;
             if (PY_SKELETON_IGNORE_DIRS.has(entry.name))
                 continue;
-            walkPyFiles(path.join(dir, entry.name), out);
+            if (isGitignored(relPath))
+                continue; // 目录命中 .gitignore → 剪枝
+            walkPyFiles(path.join(dir, entry.name), out, isGitignored, resolvedRoot);
         }
         else if (entry.isFile() && (entry.name.endsWith('.py') || entry.name.endsWith('.pyi'))) {
+            if (isGitignored(relPath))
+                continue; // 文件命中 .gitignore → 跳过
             out.push(path.join(dir, entry.name));
         }
     }
@@ -1742,8 +1895,10 @@ export async function collectTsJsCodeSkeletons(projectRoot, options) {
     // Codex P3+P4 复审 C-2 修复：projectRoot 显式 normalize 为绝对路径
     // 避免调用方传相对路径 → Map key 与 imports[].resolvedPath 形态不一致
     const resolvedProjectRoot = path.resolve(projectRoot);
+    // F194：构建 .gitignore 过滤器，基准 = resolvedProjectRoot（与 walk 内 path.relative 同口径）
+    const isGitignored = createGitignoreFilter(resolvedProjectRoot);
     const tsJsFiles = [];
-    walkTsJsFiles(resolvedProjectRoot, tsJsFiles);
+    walkTsJsFiles(resolvedProjectRoot, tsJsFiles, isGitignored, resolvedProjectRoot);
     // T-021a：tsconfig context 缓存（by configDir），避免每个文件重复读
     const tsConfigCache = new Map();
     // 大文件 size guard 与 Python 版本对齐（EC-14：1MB 阈值）
@@ -1764,14 +1919,14 @@ export async function collectTsJsCodeSkeletons(projectRoot, options) {
             const skeleton = await adapter.analyzeFile(filePath, {
                 extractCallSites: options?.extractCallSites,
             });
-            // T-021a：查找最近的 tsconfig.json 并缓存 context
-            const nearest = findNearestTsConfig(filePath, resolvedProjectRoot);
+            // T-021a：查找最近的 tsconfig.json 并缓存 context（Feature 181：loader 收口为 configPath 单参）
+            const configPath = findNearestTsConfig(filePath, resolvedProjectRoot);
             let tsConfigContext = null;
-            if (nearest) {
-                if (!tsConfigCache.has(nearest.configDir)) {
-                    tsConfigCache.set(nearest.configDir, buildTsConfigContext(nearest.rawConfig, nearest.configDir));
+            if (configPath) {
+                if (!tsConfigCache.has(configPath)) {
+                    tsConfigCache.set(configPath, buildTsConfigContext(configPath));
                 }
-                tsConfigContext = tsConfigCache.get(nearest.configDir) ?? null;
+                tsConfigContext = tsConfigCache.get(configPath) ?? null;
             }
             // 解析 imports[].resolvedPath（EC-10：转绝对路径）
             const resolvedSkeleton = {
@@ -1798,8 +1953,11 @@ export async function collectTsJsCodeSkeletons(projectRoot, options) {
 /**
  * 递归扫描 .ts/.tsx/.js/.jsx 文件（排除产物目录）。
  * 复用 walkPyFiles 的扫描模式，扩展 TS/JS 扩展名集合。
+ *
+ * F194：isGitignored 与 resolvedRoot 由 collectTsJsCodeSkeletons 构建并通过参数传入，
+ * 在自写 walk 上叠加 .gitignore 过滤层（保留 TSJS_SKELETON_IGNORE_DIRS 与点前缀剪枝不变）。
  */
-function walkTsJsFiles(dir, out) {
+function walkTsJsFiles(dir, out, isGitignored, resolvedRoot) {
     let entries;
     try {
         entries = fs.readdirSync(dir, { withFileTypes: true });
@@ -1808,12 +1966,16 @@ function walkTsJsFiles(dir, out) {
         return;
     }
     for (const entry of entries) {
+        // 基准 = resolvedRoot，path.relative 输出不做 sep 转换（与 file-scanner walkDir 一致）
+        const relPath = path.relative(resolvedRoot, path.join(dir, entry.name));
         if (entry.isDirectory()) {
             if (entry.name.startsWith('.'))
                 continue;
             if (TSJS_SKELETON_IGNORE_DIRS.has(entry.name))
                 continue;
-            walkTsJsFiles(path.join(dir, entry.name), out);
+            if (isGitignored(relPath))
+                continue; // 目录命中 .gitignore → 剪枝
+            walkTsJsFiles(path.join(dir, entry.name), out, isGitignored, resolvedRoot);
         }
         else if (entry.isFile()) {
             const name = entry.name;
@@ -1821,9 +1983,83 @@ function walkTsJsFiles(dir, out) {
                 name.endsWith('.tsx') ||
                 name.endsWith('.js') ||
                 name.endsWith('.jsx')) {
+                if (isGitignored(relPath))
+                    continue; // 文件命中 .gitignore → 跳过
                 out.push(path.join(dir, entry.name));
             }
         }
     }
 }
+/**
+ * Feature 195：全仓纯 AST、零 LLM 的 graph-only 建图。
+ *
+ * 与 runBatch 解耦的姊妹管线——只跑 AST 采集 → unifiedGraph（call graph + depends-on）
+ * + Python 符号节点 → buildKnowledgeGraph → writeKnowledgeGraph，全程不调用任何
+ * spec-gen / enrichment / hyperedge LLM，也不需要认证。
+ *
+ * why 复用 collectPython/collectTsJs 而非 scanFiles：batch 的 unifiedGraph（见 runBatch
+ * 内早期 UnifiedGraph 构建段）正是用这两个采集器构建，复用它们使 graph-only 的 unifiedGraph
+ * 与 batch 口径逐一对齐（扩展名集合 + ignore 规则一致）。不按 languages 过滤，与 batch
+ * unifiedGraph 行为一致。
+ *
+ * why writeKnowledgeGraph 传 stripTimestamps:true：与 batch 写盘一致，剥除 generatedAt
+ * 实时戳，保 byte-stable 与跨 worktree 一致（F193/NFR-002）。
+ */
+export async function buildAstGraphOnly(projectRoot, options) {
+    const startTime = Date.now();
+    const resolvedRoot = path.resolve(projectRoot);
+    const outputDir = options?.outputDir ?? 'specs';
+    const resolvedOutputDir = path.isAbsolute(outputDir)
+        ? outputDir
+        : path.join(resolvedRoot, outputDir);
+    logger.info('[Feature 195] graph-only 建图：纯 AST / 零 LLM');
+    // 步骤 1：AST 采集（与 batch unifiedGraph 同款采集器，合并 Python + TS/JS）
+    const pythonSkeletons = await collectPythonCodeSkeletons(resolvedRoot);
+    const tsJsSkeletons = await collectTsJsCodeSkeletons(resolvedRoot, {
+        extractCallSites: true,
+    });
+    const codeSkeletons = new Map([...pythonSkeletons, ...tsJsSkeletons]);
+    if (codeSkeletons.size === 0) {
+        // EC-001：无可解析源码 → 仍产出 schema 合法的空图，不崩溃
+        logger.warn('[Feature 195] 未发现可建图的源码（将产出空图）');
+    }
+    // 步骤 2：UnifiedGraph（calls + depends-on，纯 AST）
+    const unifiedGraph = codeSkeletons.size > 0
+        ? buildUnifiedGraph({ projectRoot: resolvedRoot, codeSkeletons })
+        : undefined;
+    // 步骤 3：Python 符号节点（纯 AST，extractionResults 第四路）
+    // EC-003：extractSymbolNodes 内部已 best-effort（单文件失败仍产文件级节点），此处仅兜底捕获
+    let pythonSymbolResults = [];
+    try {
+        const { PythonLanguageAdapter } = await import('../adapters/python-adapter.js');
+        pythonSymbolResults = await new PythonLanguageAdapter().extractSymbolNodes(resolvedRoot);
+    }
+    catch (pyErr) {
+        logger.warn(`[Feature 195] Python 符号提取失败，跳过: ${String(pyErr)}`);
+    }
+    const pythonSymbolCount = pythonSymbolResults.reduce((sum, r) => sum + r.nodes.filter((n) => n.kind === 'component').length, 0);
+    // 步骤 4：合并构建 knowledge graph（不传 docGraph/architectureIR/crossReferenceLinks——
+    // 那三路依赖 spec-gen 产物；EC-004：buildKnowledgeGraph 对缺席数据源 graceful skip）
+    const graphJson = buildKnowledgeGraph({
+        ...(unifiedGraph ? { unifiedGraph } : {}),
+        ...(pythonSymbolResults.length > 0 ? { extractionResults: pythonSymbolResults } : {}),
+    });
+    // 步骤 5：复用 F183 写盘出口（内部 portable 守卫扫描 → normalizeGraphForWrite → 原子写）
+    const graphPath = writeKnowledgeGraph(graphJson, resolvedOutputDir, {
+        stripTimestamps: true,
+    });
+    const callEdgeCount = graphJson.links.filter((e) => e.relation === 'calls').length;
+    const dependsOnEdgeCount = graphJson.links.filter((e) => e.relation === 'depends-on').length;
+    logger.info(`[Feature 195] graph-only 完成：${graphJson.nodes.length} 节点 / ${graphJson.links.length} 边 ` +
+        `(${callEdgeCount} calls, ${dependsOnEdgeCount} depends-on, ${pythonSymbolCount} Python 符号)`);
+    return {
+        graphPath,
+        nodeCount: graphJson.nodes.length,
+        edgeCount: graphJson.links.length,
+        callEdgeCount,
+        dependsOnEdgeCount,
+        pythonSymbolCount,
+        durationMs: Date.now() - startTime,
+    };
+}
 //# sourceMappingURL=batch-orchestrator.js.map