Incremental Project Analysis

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 分界

核心产物

落盘建议：<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。