/incremental-project-analysis

name: incremental-project-analysis
description: 增量项目分析 Owner — 知识快照、内容 digest、分析视角覆盖、changed→impact 选择性失效、智能分批可见交付、全局优先级综合、分析精度合同与双层验证；大型/逐文件分析禁止只缓存自然语言总结。

Incremental Project Analysis

职责

承接大库 / 逐文件 / 多会话项目分析的**可复用认知层**：把稳定事实、依赖图、分析视角覆盖与结论新鲜度做成可校验快照，支持增量重算、分批交付与全局综合。 **不**替代 `skill-gap-analysis` 的规模分批扫描本身；**不**替代 `analyze-default` 的只读多轮分析主流程。本 Skill 提供快照、精度、批次交付与验证状态机。

何时触发

• 用户要求完整深度 / 逐文件 / 多批项目分析，且语料 non-small。
• 用户要求「后续只分析增量 / 不要每轮重读全库」。
• `analyze-default` / `skill-gap-analysis` 在 ScaleDecision 为 `batched` / `sampled+deep-read` 时必须调用本 Skill 的交付与精度门禁。
• 用户要求最终确认清单 / 可吸纳包时，叠加 `FindingThemeCoverageMatrix`（与 `report` ABS-17 一致）。

与相邻 Skill 分界

| Skill | 本 Skill 管 | 对方管 | |-------|-------------|--------| | `skill-gap-analysis` | 知识快照、全局 backlog、精度与验证阶段 | 规模路由、缺口 vs Owner 矩阵、corpus inventory | | `analyze-default` | 快照复用、BatchProgress、GlobalBacklog、双产物 | 三轮收敛、PCV、只读边界、治理 intake | | `memory` | 快照路径链接；**禁止**把快照正文写入 SUMMARY | 会话日记、handoff、TimingCard | | `report` | Theme+Detail 链接、CoverageMatrix 字段 | 报告路径与五项验证列 |

核心产物

| 产物 | 说明 | |------|------| | `ProjectKnowledgeSnapshotV2` | 可持久化 accepted 项目知识；含 repo/root、Merkle、环境绑定、policy/schema 版本 | | `FileKnowledgeRecordV2` | 每文件 content identity、coverageLevel、结构观察与已接受声明 | | `SemanticClaimV1` | 类型化声明；绑定 sourceRange/rangeDigest、authority、lens、policy 与依赖 | | `ProjectKnowledgeBindingV1` | 绑定唯一 repo/root、inventory Merkle、配置、解析器、测试路线与 Profile 身份 | | `ImpactGraphV1` | 依赖 / 消费者 / 配置 / 契约边 | | `AnalysisLensRecordV1` | 分析视角覆盖（lens / questionFingerprint） | | `IncrementalAnalysisPlanV2` | 本轮只读集合：binding + changed + impact + lens-gap + deterministic sample | | `IncrementalAnalysisReceiptV2` | 复用/重算/失效分类、抽样复证与 accepted pointer 结果 | | `BatchProgressCard` | 每 accepted 批用户可见交付 | | `GlobalOptimizationBacklogV1` | 全批后唯一高/中/低优先级清单 | | `ValidationPlanV1` / `BatchValidationResultV1` / `GlobalValidationResultV1` | 双层验证 |

落盘建议：`<active-root>/reports/analysis/<agent>/YYYYMMDD/deep/` 或任务目录 `artifacts/knowledge-snapshot/`；**禁止**写入 Agent SUMMARY 正文。

源仓 runtime Owner 为 `scripts/lib/project-knowledge-store.js`，内部 CLI 为 `scripts/project-analysis-state.js status|plan|observe|bootstrap|accept`。accepted runtime 固定落到 `<active-root>/.runtime-state/project-knowledge/v2/<repoId>/snapshot.json`；`status`、`plan`、`observe` 必须零写入，`bootstrap` 只生成可复证的 `content-structured` 首轮基线，只有 `BatchValidationResultV1=pass` 且 sample oracle=pass 的 bootstrap/accept 才可在所有批次内存验收后推进一次 runtime pointer 并写任务证据。

V1 只读兼容：`v1/<repoId>/snapshot.json` 仅用于返回 `compatibility-v1 + migrationRequired` 导航信息，禁止作为 V2 reuse/accept 基线；下一次 `bootstrap` 必须走 full-required 并生成独立 V2 accepted snapshot。禁止迁移时原地改写 V1。

当 execution optimization 为 `full-only`，或 `project-knowledge-reuse` 的 `ExecutionOptimizationFeatureDecisionV1` 为 `off / shadow / rolled-back / sunset`，或 state/snapshot schema/identity 无效、oracle 失败时，`plan` 必须返回 `full-project-analysis`，不得复用 snapshot records；status 同时公开 `executionOptimizationMode`、feature decision 与 `reuseAllowed=false`。kill switch 只关闭加速，不跳过 inventory、智能分批、逐批验证、最终全局验证或高/中/低 backlog。

---

Gate 索引（执行正文）

ProjectKnowledgeSnapshotGate（ABS-01）

1. 首次分析冻结：repo/base tree（或等价）、排除边界、文件 contentDigest、coverageLevel、依赖边、policyVersion。 2. 首次无快照时执行 deterministic `observe → batch validate → bootstrap`；只保存从当前字节可重建的结构声明，不得把 bootstrap 宣称为人工深读。 3. 稳定事实层（symbols、imports、配置锚点）按 content identity + rangeDigest 复用；职责、风险、建议只能以 `agent-semantic` authority 单独接受。 4. 判断层绑定 `analysisLens / dependsOn / policyVersion`；代码未变但目标变时只补 lens-gap。 5. `ProjectKnowledgeBindingV1` 的 repo/root、配置、解析器、测试路线或 Profile 身份错配时强制 full-required；inventory 内容差异走 delta/impact，不因正常小变化误判为环境错配。 6. **禁止**仅保存 Markdown 自然语言总结当作可复用知识。

生产 CLI 必须从当前 bounded inventory 的真实字节构建 `ImpactGraphV1`：首期至少解析 JS/TS 静态相对 `require/import/export/dynamic import literal` 与 Markdown 本地链接，记录 typed edge、source、evidenceStrength、覆盖率、未解析引用和 `unknownConsumerPaths`。图必须带 `builderVersion`；旧/未知 builder 首次迁移 full-required，之后普通图拓扑变化使用当前图重新计算影响闭包，不得仅因 graph identity 改变就无条件全文重读。

SemanticClaimBoundaryGate

1. 每条可复用声明必须是 `SemanticClaimV1`，至少包含 `type / statement / authority / sourceRange / rangeIdentity / sourceContentDigest / lensId / policyVersion / dependsOn / claimDigest / status`。 2. `inventory-only` 只能声明文件存在与内容身份；`content-structured` 只能声明文本中直接可解析的 heading、symbol、import、config/test 结构；只有 `agent-semantic` 可声明职责、风险或建议。 3. rangeDigest 必须从当前文件精确行范围重算；path、content、range、lens 或 claim digest 任一不一致即拒绝该批，禁止“修补后继续复用”。 4. accepted snapshot 只持久化 `status=accepted` 声明；candidate/provisional/invalid 只能留在当轮候选输出，不得推进 runtime pointer。

SelectiveInvalidationGate

1. 变化集优先 `git diff --name-status`，并用当前 digest 覆盖未提交/未跟踪/rename。 2. 直接变化扩展到依赖、消费者、公共契约、配置、生成链、测试与文档闭包。 3. 状态：`fresh / stale / coverage-gap / incompatible / full-required`。 4. 强制升级：快照损坏、base 不可达、schema/builder 不兼容、高风险变更、闭包过大、抽样复证失败；动态依赖消费者自身发生变化时 full-required，其他文件变化时必须把全部 unknown consumer 注入 affected closure 并显式重读，禁止静默复用。

`mtime/size` 只能做候选加速；fresh 必须由 current bytes content identity 证明。rename 必须同时写旧 path tombstone 与新 path identity，delete 写 tombstone；配置变化保守扩到受影响全域。ImpactGraph 每条边必须含 type/source/evidenceStrength，图覆盖不足时不得声称 selective complete；`unknownConsumerPaths` 与 builder/stats 必须进入 graph identity。graph identity 变化会使未完成旧 plan 失效，但只在 builder 迁移或其他升级条件命中时触发全文；正常拓扑变化应以新图计算 changed/impact closure。

AdaptiveBatchDeliveryGate（ABS-02）

1. 按模块 / namespace / 消费者 / 风险分批；每批有 budget 与 checkpoint。 2. **每个 accepted 批次**必须立即输出并持久化：`BatchProgressCard` + 本批发现 + checkpoint + snapshot delta。 3. **禁止**等待全量完成才首次交付用户可见结果。 4. 恢复只从最后一个 `accepted` 批次继续；`invalid/blocked` 不得推进指针。

复用抽样必须按 contentId/path 稳定排序选择 5%，最少 3、最多 20，不足 3 全抽。任一 content/fact mismatch 使本批 `invalid + full-required`；历史 runtime 只标 stale，不自动删除。

`observe` 与 `bootstrap` 的候选选择、结构提取、claimId、rangeDigest、Merkle root 和 sample 必须确定性；同一 repo/root、字节、环境身份与 lens 重跑必须得到相同 identity。持久化顺序为“先验证全部身份与任务证据，最后单次原子替换 runtime pointer”；任务证据写入失败时 pointer 不得推进。

GlobalPrioritySynthesisGate（ABS-03）

1. 全部计划批次 `accepted` 且 CRS/PCV 收敛后，跨批去重合并，输出唯一 `GlobalOptimizationBacklogV1`（高/中/低 + 推荐顺序）。 2. 未