spectra-cli 4.1.1

package/dist/panoramic/pipelines/adr-migration.d.ts

@@ -0,0 +1,26 @@
+export interface MigrateOldAdrsResult {
+    /** 检查到的总 .md 文件数（含跳过的）*/
+    totalFiles: number;
+    /** 实际被 supersede 的文件数 */
+    superseded: number;
+    /** 已经是 superseded 状态、跳过的文件数 */
+    alreadySuperseded: number;
+    /** 当前批次产物（在 currentBatchAdrPaths 中）跳过的文件数 */
+    skippedCurrentBatch: number;
+    /** 含 generatedByModel 字段、跳过的文件数（已是 v4.1+ 产物）*/
+    skippedNewFormat: number;
+    /** 因解析失败跳过的文件数（不报错，仅 warn）*/
+    skippedParseError: number;
+    /** 实际改写的文件路径列表 */
+    supersededFiles: string[];
+}
+/**
+ * 扫描 adrDir 下的旧版 ADR 并追加 supersede notice。
+ *
+ * @param adrDir ADR 目录绝对路径（通常 `<outputDir>/docs/adr`）
+ * @param currentBatchAdrPaths 当前批次新生成的 ADR 文件**绝对路径**集合
+ *                             （用于排除新产物，绝不能 supersede 它们）
+ * @returns 处理统计 + 改写的文件路径列表
+ */
+export declare function migrateOldAdrs(adrDir: string, currentBatchAdrPaths: Set<string>): MigrateOldAdrsResult;
+//# sourceMappingURL=adr-migration.d.ts.map

package/dist/panoramic/pipelines/adr-migration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adr-migration.d.ts","sourceRoot":"","sources":["../../../src/panoramic/pipelines/adr-migration.ts"],"names":[],"mappings":"AAwCA,MAAM,WAAW,oBAAoB;IACnC,yBAAyB;IACzB,UAAU,EAAE,MAAM,CAAC;IACnB,yBAAyB;IACzB,UAAU,EAAE,MAAM,CAAC;IACnB,+BAA+B;IAC/B,iBAAiB,EAAE,MAAM,CAAC;IAC1B,6CAA6C;IAC7C,mBAAmB,EAAE,MAAM,CAAC;IAC5B,+CAA+C;IAC/C,gBAAgB,EAAE,MAAM,CAAC;IACzB,6BAA6B;IAC7B,iBAAiB,EAAE,MAAM,CAAC;IAC1B,kBAAkB;IAClB,eAAe,EAAE,MAAM,EAAE,CAAC;CAC3B;AAMD;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAC5B,MAAM,EAAE,MAAM,EACd,oBAAoB,EAAE,GAAG,CAAC,MAAM,CAAC,GAChC,oBAAoB,CAsFtB"}

package/dist/panoramic/pipelines/adr-migration.js

@@ -0,0 +1,203 @@
+/**
+ * ADR Migration (Feature 140 T43)
+ *
+ * 实现 spec FR-006 — 旧版 ADR 在 v4.1.0 升级时自动追加 supersede notice。
+ *
+ * **关键不变量（修复 Codex review finding 1 — high-severity 谓词逻辑 bug）**：
+ * legacy 判定谓词必须用 AND，且**排除当前批次产物**：
+ *
+ *     旧 ADR := frontmatter.generatedByModel 缺失
+ *           AND frontmatter.status !== 'superseded'
+ *           AND 文件路径 NOT IN currentBatchAdrPaths
+ *
+ * **禁止用 OR 连接**：OR 会让新生成的 proposed/accepted 状态 ADR 也被误判
+ * 为旧 ADR 立即 supersede 自己，是已识别的高危逻辑 bug。
+ *
+ * 处理：
+ *  - 满足全部条件 → frontmatter.status 改为 'superseded' + 追加 supersededAt: '4.1.0'
+ *  - 不删除文件（保留供历史参考）
+ *  - 不修改文件正文（只动 frontmatter）
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { createLogger } from '../utils/logger.js';
+const logger = createLogger('adr-migration');
+// ============================================================
+// 常量
+// ============================================================
+/** spec FR-006 锁定：supersedeAt 字段值（与本 Feature 的 targetVersion 对齐）*/
+const SUPERSEDE_VERSION = '4.1.0';
+/** 简单 YAML frontmatter 块匹配正则（不依赖 yaml lib，零依赖原则）*/
+const FRONTMATTER_REGEX = /^---\r?\n([\s\S]*?)\r?\n---\r?\n/;
+// ============================================================
+// 主入口
+// ============================================================
+/**
+ * 扫描 adrDir 下的旧版 ADR 并追加 supersede notice。
+ *
+ * @param adrDir ADR 目录绝对路径（通常 `<outputDir>/docs/adr`）
+ * @param currentBatchAdrPaths 当前批次新生成的 ADR 文件**绝对路径**集合
+ *                             （用于排除新产物，绝不能 supersede 它们）
+ * @returns 处理统计 + 改写的文件路径列表
+ */
+export function migrateOldAdrs(adrDir, currentBatchAdrPaths) {
+    const result = {
+        totalFiles: 0,
+        superseded: 0,
+        alreadySuperseded: 0,
+        skippedCurrentBatch: 0,
+        skippedNewFormat: 0,
+        skippedParseError: 0,
+        supersededFiles: [],
+    };
+    if (!fs.existsSync(adrDir)) {
+        return result;
+    }
+    let entries;
+    try {
+        entries = fs.readdirSync(adrDir, { withFileTypes: true });
+    }
+    catch (err) {
+        logger.warn(`migrateOldAdrs 无法读取 ${adrDir}: ${String(err)}`);
+        return result;
+    }
+    for (const entry of entries) {
+        if (!entry.isFile() || !entry.name.endsWith('.md'))
+            continue;
+        // index.md / _PIPELINE_DISABLED.md / _PIPELINE_FAILED.md 等 meta 文件跳过
+        if (entry.name === 'index.md' || entry.name.startsWith('_'))
+            continue;
+        result.totalFiles++;
+        const filePath = path.join(adrDir, entry.name);
+        // 关键守卫 1：当前批次产物不进入 supersede 流程
+        if (currentBatchAdrPaths.has(filePath)) {
+            result.skippedCurrentBatch++;
+            continue;
+        }
+        let content;
+        try {
+            content = fs.readFileSync(filePath, 'utf-8');
+        }
+        catch (err) {
+            result.skippedParseError++;
+            logger.warn(`migrateOldAdrs 无法读取 ADR ${filePath}: ${String(err)}`);
+            continue;
+        }
+        const frontmatterMatch = FRONTMATTER_REGEX.exec(content);
+        if (!frontmatterMatch) {
+            // 文件没有 frontmatter（不是 ADR 格式）— 视为 parse error 跳过
+            result.skippedParseError++;
+            continue;
+        }
+        const frontmatterText = frontmatterMatch[1];
+        const fields = parseSimpleYamlFields(frontmatterText);
+        // 关键守卫 2：已是 superseded 状态 → 不重复处理
+        if (fields.status === 'superseded') {
+            result.alreadySuperseded++;
+            continue;
+        }
+        // 关键守卫 3：已经是 v4.1+ 新格式（含 generatedByModel）→ 不视为旧 ADR
+        if (fields.generatedByModel !== undefined) {
+            result.skippedNewFormat++;
+            continue;
+        }
+        // 满足全部 AND 条件 → 改写 frontmatter 追加 status=superseded + supersededAt
+        const updatedContent = supersedeFrontmatter(content, frontmatterText, frontmatterMatch[0]);
+        try {
+            fs.writeFileSync(filePath, updatedContent, 'utf-8');
+            result.superseded++;
+            result.supersededFiles.push(filePath);
+        }
+        catch (err) {
+            result.skippedParseError++;
+            logger.warn(`migrateOldAdrs 写入失败 ${filePath}: ${String(err)}`);
+        }
+    }
+    if (result.superseded > 0) {
+        logger.info(`migrateOldAdrs: ${result.superseded}/${result.totalFiles} 个旧 ADR 已追加 supersededAt: ${SUPERSEDE_VERSION}`);
+    }
+    return result;
+}
+// ============================================================
+// frontmatter 改写助手
+// ============================================================
+/**
+ * 解析简单 YAML frontmatter（支持 `key: value` 单行格式 + 嵌套对象的字符串检测）。
+ * 不实现完整 YAML — 只识别 status / supersededAt / generatedByModel 三个 key。
+ */
+function parseSimpleYamlFields(text) {
+    const result = {};
+    for (const line of text.split(/\r?\n/)) {
+        const trimmed = line.trim();
+        const statusMatch = /^status\s*:\s*(.+?)\s*$/.exec(trimmed);
+        if (statusMatch) {
+            result.status = statusMatch[1].replace(/^['"]|['"]$/g, '').trim();
+            continue;
+        }
+        const supersededMatch = /^supersededAt\s*:\s*(.+?)\s*$/.exec(trimmed);
+        if (supersededMatch) {
+            result.supersededAt = supersededMatch[1].replace(/^['"]|['"]$/g, '').trim();
+            continue;
+        }
+    }
+    // 修复 Codex W-4 — 严格验证 generatedByModel 值结构（不只是 key 存在）：
+    //  接受合规结构（视为新格式跳过 supersede）：
+    //   (1) 多行 YAML block scalar：`generatedByModel:` 后跟 `map:` 和 `reduce:` 子字段
+    //   (2) 单行内联对象：含 `map` / `reduce` 关键字段
+    //  拒绝（视为缺失，继续 supersede legacy）：
+    //   (1) `generatedByModel:` 空值（无后续 map/reduce 子字段）
+    //   (2) `generatedByModel: ""` / `generatedByModel: {}` 空对象 / 损坏字段
+    if (/^\s*generatedByModel\s*:/m.test(text)) {
+        // 找 generatedByModel: 后的所有内容（直到下一个顶层 key 或 frontmatter 结尾）
+        const lines = text.split(/\r?\n/);
+        let inBlock = false;
+        let blockContent = '';
+        for (const line of lines) {
+            if (/^\s*generatedByModel\s*:/.test(line)) {
+                inBlock = true;
+                blockContent += line + '\n';
+                continue;
+            }
+            if (inBlock) {
+                // 遇到下一个顶层字段（行首非空白）→ 结束 block
+                if (/^\S/.test(line)) {
+                    break;
+                }
+                blockContent += line + '\n';
+            }
+        }
+        // 必须同时含有 map 和 reduce 子字段
+        const hasMap = /\bmap\s*:/i.test(blockContent);
+        const hasReduce = /\breduce\s*:/i.test(blockContent);
+        if (hasMap && hasReduce) {
+            result.generatedByModel = blockContent;
+        }
+        // 其他情况 → 不设值（被视为缺失字段，触发 legacy supersede）
+    }
+    return result;
+}
+/**
+ * 在既有 frontmatter 中追加 status=superseded + supersededAt 字段。
+ * 如果已有 status 字段（非 superseded 值），原地替换；否则追加到末尾。
+ */
+function supersedeFrontmatter(fullContent, frontmatterText, fullMatch) {
+    let updated = frontmatterText;
+    // 替换或追加 status
+    if (/^status\s*:/m.test(updated)) {
+        updated = updated.replace(/^status\s*:.*$/m, 'status: superseded');
+    }
+    else {
+        updated += '\nstatus: superseded';
+    }
+    // 替换或追加 supersededAt
+    if (/^supersededAt\s*:/m.test(updated)) {
+        updated = updated.replace(/^supersededAt\s*:.*$/m, `supersededAt: "${SUPERSEDE_VERSION}"`);
+    }
+    else {
+        updated += `\nsupersededAt: "${SUPERSEDE_VERSION}"`;
+    }
+    // 重组：保留原 trailing newline 行为
+    const newFrontmatterBlock = `---\n${updated}\n---\n`;
+    return fullContent.replace(fullMatch, newFrontmatterBlock);
+}
+//# sourceMappingURL=adr-migration.js.map

package/dist/panoramic/pipelines/adr-migration.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"adr-migration.js","sourceRoot":"","sources":["../../../src/panoramic/pipelines/adr-migration.ts"],"names":[],"mappings":"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"}

package/dist/panoramic/pipelines/architecture-narrative-mapreduce.d.ts

@@ -0,0 +1,121 @@
+/**
+ * Architecture Narrative MapReduce Pipeline (Feature 140 T32-T34)
+ *
+ * 实现 spec FR-008 / US-003 — 基于 cluster orchestrator 的 4 段 LLM narrative 生成：
+ *   Phase A: 聚类（复用 cluster-orchestrator 的 community → directory → single fallback）
+ *   Phase B Map (sonnet): 每 cluster 输出 mini-narrative + key abstractions
+ *   Phase C Reduce (sonnet): 合并 cluster narratives 为 4-6 段项目级 narrative
+ *   Phase D Critique (sonnet): 独立 LLM 调用判定通过/失败
+ *   Phase E Refine (sonnet, optional): 仅 Phase D fail 时执行，最多 1 次
+ *   Phase F: 程序化 domain-words 校验（≥3 个核心抽象名）
+ *
+ * **设计权威**：
+ * - specs/140-spectra-doc-pipeline-quality/research/02-mapreduce-architecture.md §四
+ * - specs/140-spectra-doc-pipeline-quality/spec.md FR-008 / FR-009 / US-003
+ *
+ * **职责边界**：本模块仅负责 LLM-based narrative 生成；调用方负责文件写盘 + frontmatter
+ * 集成。fail-closed 时（domain-words < 3 即便 Refine 后）返回 finalOutput=null + 诊断信息，
+ * caller 决定是否写 `_PIPELINE_FAILED.md` 标记（沿用 Feature 135 模式）。
+ */
+import type Anthropic from '@anthropic-ai/sdk';
+import { z } from 'zod';
+import type { StoredModuleSpecRecord } from '../stored-module-specs.js';
+/** Phase B Map 输出：每 cluster 的 mini-narrative + 关键抽象 */
+export declare const MapOutputSchema: z.ZodObject<{
+    clusterNarrative: z.ZodString;
+    keyAbstractions: z.ZodArray<z.ZodString, "many">;
+}, "strip", z.ZodTypeAny, {
+    clusterNarrative: string;
+    keyAbstractions: string[];
+}, {
+    clusterNarrative: string;
+    keyAbstractions: string[];
+}>;
+export type MapOutput = z.infer<typeof MapOutputSchema>;
+/** Phase C Reduce 输出：项目级 4-6 段 narrative */
+export declare const ReduceOutputSchema: z.ZodObject<{
+    paragraphs: z.ZodArray<z.ZodString, "many">;
+    abstractionGlossary: z.ZodArray<z.ZodString, "many">;
+}, "strip", z.ZodTypeAny, {
+    paragraphs: string[];
+    abstractionGlossary: string[];
+}, {
+    paragraphs: string[];
+    abstractionGlossary: string[];
+}>;
+export type ReduceOutput = z.infer<typeof ReduceOutputSchema>;
+/** Phase D Critique 输出 */
+export declare const CritiqueOutputSchema: z.ZodObject<{
+    passed: z.ZodBoolean;
+    issues: z.ZodArray<z.ZodString, "many">;
+}, "strip", z.ZodTypeAny, {
+    issues: string[];
+    passed: boolean;
+}, {
+    issues: string[];
+    passed: boolean;
+}>;
+export type CritiqueOutput = z.infer<typeof CritiqueOutputSchema>;
+export interface EnrichNarrativeOptions {
+    /** Anthropic SDK 客户端（必填，由 caller 注入便于测试 mock）*/
+    anthropicClient: Anthropic;
+    /** 待 narrative 化的模块 spec 列表 */
+    modules: StoredModuleSpecRecord[];
+    /** README 全量内容（来自 Step 5 extraction-pipeline）*/
+    readmeContent?: string;
+    /** project-context.yaml 摘要（与 batch-orchestrator 入参一致）*/
+    projectContextSummary?: string;
+    /** LLM 模型 ID（默认 claude-sonnet-4-6）*/
+    model?: string;
+}
+export interface CritiqueResultRecord {
+    passed: boolean;
+    issues: string[];
+    /** Refine 是否被触发（仅 Phase D fail 时为 true）*/
+    refineAttempted: boolean;
+}
+export interface EnrichNarrativeResult {
+    /** Phase C Reduce 产出的 4-6 段 narrative；fail-closed 时为 null */
+    paragraphs: string[] | null;
+    /** Phase F 检测到的领域词（命中 module spec 中的核心抽象名）*/
+    domainWordsFound: string[];
+    /** Phase D/E critique 结果摘要 */
+    critiqueResult: CritiqueResultRecord;
+    /** fail-closed 标志 */
+    failClosed: boolean;
+    /** fail-closed 原因（仅 failClosed=true 时）— 与 cluster-orchestrator 的 union 对齐，
+     * 加上 narrative 专属的 'domain-words-insufficient'（修复 Codex W-2 — 透传 dispatch 原因不再压缩）*/
+    failClosedReason?: 'map-below-threshold' | 'reduce-failed' | 'clustering-failed' | 'shared-header-failed' | 'domain-words-insufficient';
+    /** 各阶段 LLM 调用 telemetry 累计（caller 写到 frontmatter）*/
+    totalTokens: {
+        input: number;
+        output: number;
+    };
+}
+/**
+ * Phase F: 校验 narrative 文本中是否出现 ≥ MIN_DOMAIN_WORDS 个项目特有抽象名。
+ *
+ * @returns 命中的领域词列表（去重）；caller 可根据 length 判定是否通过。
+ */
+export declare function validateDomainWords(paragraphs: string[], modules: StoredModuleSpecRecord[]): string[];
+/**
+ * 基于 cluster orchestrator 的 4 段 LLM narrative 生成。
+ *
+ * 阶段：
+ *   A: 聚类（cluster orchestrator 内置 community → directory → single fallback）
+ *   B Map: per cluster mini-narrative + key abstractions（sonnet）
+ *   C Reduce: 合并为 4-6 段 narrative（sonnet）
+ *   D Critique: 独立 LLM 判定通过 / 失败（sonnet）
+ *   E Refine: 仅 D fail 时执行，最多 1 次（sonnet）
+ *   F 程序化 domain-words 校验（≥3 个核心抽象名）
+ *
+ * fail-closed 触发条件：
+ *   - Map < 50% 成功 → finalOutput=null
+ *   - Reduce 重试 1 次仍失败 → finalOutput=null
+ *   - Refine 后 domain-words 仍 < 3 → finalOutput=null（spec 锁定）
+ *
+ * @param options 包含 LLM 客户端、modules、可选 readme + projectContext
+ * @returns paragraphs（成功时 4-6 段；fail-closed 时 null）+ critique + domain-words + telemetry
+ */
+export declare function enrichNarrativeWithLLM(options: EnrichNarrativeOptions): Promise<EnrichNarrativeResult>;
+//# sourceMappingURL=architecture-narrative-mapreduce.d.ts.map

package/dist/panoramic/pipelines/architecture-narrative-mapreduce.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"architecture-narrative-mapreduce.d.ts","sourceRoot":"","sources":["../../../src/panoramic/pipelines/architecture-narrative-mapreduce.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,KAAK,SAAS,MAAM,mBAAmB,CAAC;AAC/C,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,2BAA2B,CAAC;AAyBxE,uDAAuD;AACvD,eAAO,MAAM,eAAe;;;;;;;;;EAG1B,CAAC;AACH,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAExD,4CAA4C;AAC5C,eAAO,MAAM,kBAAkB;;;;;;;;;EAG7B,CAAC;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAE9D,0BAA0B;AAC1B,eAAO,MAAM,oBAAoB;;;;;;;;;EAG/B,CAAC;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAMlE,MAAM,WAAW,sBAAsB;IACrC,gDAAgD;IAChD,eAAe,EAAE,SAAS,CAAC;IAC3B,+BAA+B;IAC/B,OAAO,EAAE,sBAAsB,EAAE,CAAC;IAClC,gDAAgD;IAChD,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,wDAAwD;IACxD,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,qCAAqC;IACrC,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,OAAO,CAAC;IAChB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,0CAA0C;IAC1C,eAAe,EAAE,OAAO,CAAC;CAC1B;AAED,MAAM,WAAW,qBAAqB;IACpC,6DAA6D;IAC7D,UAAU,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;IAC5B,6CAA6C;IAC7C,gBAAgB,EAAE,MAAM,EAAE,CAAC;IAC3B,8BAA8B;IAC9B,cAAc,EAAE,oBAAoB,CAAC;IACrC,qBAAqB;IACrB,UAAU,EAAE,OAAO,CAAC;IACpB;wFACoF;IACpF,gBAAgB,CAAC,EACb,qBAAqB,GACrB,eAAe,GACf,mBAAmB,GACnB,sBAAsB,GACtB,2BAA2B,CAAC;IAChC,oDAAoD;IACpD,WAAW,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;CAChD;AA0DD;;;;GAIG;AACH,wBAAgB,mBAAmB,CACjC,UAAU,EAAE,MAAM,EAAE,EACpB,OAAO,EAAE,sBAAsB,EAAE,GAChC,MAAM,EAAE,CAYV;AAkOD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,sBAAsB,CAC1C,OAAO,EAAE,sBAAsB,GAC9B,OAAO,CAAC,qBAAqB,CAAC,CAmIhC"}