| 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）
- 首次分析冻结：repo/base tree（或等价）、排除边界、文件 contentDigest、coverageLevel、依赖边、policyVersion。
- 首次无快照时执行 deterministic
observe → batch validate → bootstrap；只保存从当前字节可重建的结构声明，不得把 bootstrap 宣称为人工深读。
- 稳定事实层（symbols、imports、配置锚点）按 content identity + rangeDigest 复用；职责、风险、建议只能以
agent-semantic authority 单独接受。
- 判断层绑定
analysisLens / dependsOn / policyVersion；代码未变但目标变时只补 lens-gap。
ProjectKnowledgeBindingV1 的 repo/root、配置、解析器、测试路线或 Profile 身份错配时强制 full-required；inventory 内容差异走 delta/impact，不因正常小变化误判为环境错配。- 禁止仅保存 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
- 每条可复用声明必须是
SemanticClaimV1，至少包含 type / statement / authority / sourceRange / rangeIdentity / sourceContentDigest / lensId / policyVersion / dependsOn / claimDigest / status。
inventory-only 只能声明文件存在与内容身份；content-structured 只能声明文本中直接可解析的 heading、symbol、import、config/test 结构；只有 agent-semantic 可声明职责、风险或建议。- rangeDigest 必须从当前文件精确行范围重算；path、content、range、lens 或 claim digest 任一不一致即拒绝该批，禁止“修补后继续复用”。
- accepted snapshot 只持久化
status=accepted 声明；candidate/provisional/invalid 只能留在当轮候选输出，不得推进 runtime pointer。
SelectiveInvalidationGate
- 变化集优先
git diff --name-status，并用当前 digest 覆盖未提交/未跟踪/rename。
- 直接变化扩展到依赖、消费者、公共契约、配置、生成链、测试与文档闭包。
- 状态：
fresh / stale / coverage-gap / incompatible / full-required。
- 强制升级：快照损坏、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）
- 按模块 / namespace / 消费者 / 风险分批；每批有 budget 与 checkpoint。
- 每个 accepted 批次必须立即输出并持久化：
BatchProgressCard + 本批发现 + checkpoint + snapshot delta。
- 禁止等待全量完成才首次交付用户可见结果。
- 恢复只从最后一个
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）
- 全部计划批次
accepted 且 CRS/PCV 收敛后，跨批去重合并，输出唯一 GlobalOptimizationBacklogV1（高/中/低 + 推荐顺序）。
- 未完成 / invalid / blocked → 只能
partial/provisional，禁止 final/completed 宣称。
findingId 与 priority 分字段（ABS-05），禁止用 P1 编号冒充 P0 优先级。
AnalysisPrecisionContractGate（ABS-04）
- 开批前冻结
depthTier：deep | standard | light。
- 每文件笔记必有
evidenceStrength：agent-semantic | content-structured | inventory-only。
- 交付必须 ThemePriorityBacklog + FindingDetailLedger（去噪 high/medium；默认排除纯归档 low）。
- claimBoundary：inventory/content-structured 不得宣称「人工长文精读」；主题 N 条 不得宣称「仅有 N 个问题」。
DualLayerValidationGate
生命周期：
plan → execute → batch validate → accept/deliver → synthesize → global validate → final
| 规则 | 说明 |
|---|
| 执行前 | 冻结 ValidationPlanV1（风险、声明、消费者、证据、升级路线） |
| 批次 | 仅 BatchValidationResult=pass 可 accepted / 写 checkpoint / snapshot delta |
| 全局 | 仅 GlobalValidationResult=pass 可 final backlog / completed |
| 失败 | fail/inconclusive 隔离候选输出；按 targeted→related→full 扩大或重做；全局失败保持 provisional |
执行清单（最小）
- 确认 ScaleDecision（委托
skill-gap-analysis）。
- 加载 V2 snapshot；若仅有 V1，标记只读兼容并规划 full-required bootstrap。
- 冻结 depthTier + lens + ValidationPlan。
- 构建
ProjectKnowledgeBindingV1，计算 changed / impact / lens-gap → IncrementalAnalysisPlanV2。
- 分批执行：observe/语义补充 → claim range 复证 → batch validate → accepted ProgressCard；首次基线用 bootstrap，后续按差量 accept。
- 全批后 CRS/PCV → GlobalBacklog → global validate。
- 报告双产物 + CoverageMatrix（确认清单场景）+ TimingCard（长任务）。
反模式
- 每轮全文重读却不更新 digest / 失效图。
- 只交付主题 8 条，隐瞒 high/medium 明细。
- 把 waiting-user 时间算进「分析执行慢」且无 TimingCard。
- 在 SUMMARY 粘贴快照正文。
- 未 batch validate 就写 accepted checkpoint。
- 把 V1 snapshot 静默升级、继续复用或写回原路径。
- 把结构提取结果描述成“逐文件人工深读完成”或“问题只有 N 个”。
验证路线
正负向至少覆盖：首轮 observe/bootstrap 确定性；单文件变更只重算闭包；配置变更使未改源码失效；新 lens 触发 coverage-gap；rename/tombstone；repo/root/config/parser/test/Profile/content/range identity 错配；V1 只读兼容；5% sample 确定性；candidate/provisional 不持久化；accepted 缺 ProgressCard 失败；global 未完成不得 final；findingId/priority 混用失败；claim authority 越界失败。
