---
name: knowledge-index-verify
description: Verify docs/features feature frontmatter, test attribution, docIndexLinks, code-facts tool evidence, and produce a candidate knowledge index under .nucleus/runs only.
---

# knowledge-index-verify

本 Skill 是 Nucleus V2 Knowledge Index / llm-wiki approved-write 的只读 verify gate。它只生成 candidate、diff、report 和 result package，不同步生产索引。

## 边界

- 不覆盖 `docs/knowledge-index.json`。
- 不生成、更新或补写 `docs/features/**/code-facts.md`。
- 不从 LLM prompt、人工摘要或检索结果直接推断代码事实。
- 不写 `docs/requirement/**`、`docs/features/**`、`tests/**`、`.nucleus/tests/**` 或源码。
- Runtime 只允许写 `.nucleus/runs/<workflowRunId>/knowledge/**` 与 `.nucleus/runs/<workflowRunId>/result.json`。
- 失败默认 `ALERT_AND_BLOCK`，不得静默降级。

## 使用

```bash
python3 skills/knowledge-index-verify/scripts/knowledge_index_verify.py verify \
  --repo-root /path/to/target-repo \
  --context /path/to/target-repo/.nucleus/context/<workflowRunId>.json \
  --tool-evidence /path/to/target-repo/.nucleus/runs/<workflowRunId>/knowledge/tool-evidence/gitnexus-search-report.json
```

`--tool-evidence` 必须是显式 adapter evidence JSON。GitNexus、Serena、Yog 或 static analyzer readiness 只能来自该 evidence、capabilityStatus 或工具注册报告，不能凭宿主环境猜测。

## Code Facts Strict

当以下任一条件成立时，code-facts 证据缺失必须 `FAILED_BLOCKED`：

- `docIndexLinks` 引用 `docs/features/**/code-facts.md`。
- scanner 发现同 feature 目录下存在 `code-facts.md`。
- context 明确要求 code facts。

没有 code-facts 的普通 feature 只能进入 candidate-only 与人工 review，不能生成 prompt-only facts。

## 人审前子代理预审

到达 `candidate-index-review` 前，必须按 workflow 的 `subagentPreReview` 调度独立 reviewer 子代理；未取得“材料可提交人工审查”预审结论时，不得请求人工评审通过。

## 输出

- `.nucleus/runs/<workflowRunId>/knowledge/feature-scan-report.json`
- `.nucleus/runs/<workflowRunId>/knowledge/candidate-knowledge-index.json`
- `.nucleus/runs/<workflowRunId>/knowledge/index-diff.md`
- `.nucleus/runs/<workflowRunId>/knowledge/verify-report.json`
- `.nucleus/runs/<workflowRunId>/knowledge/verify-report.md`
- `.nucleus/runs/<workflowRunId>/knowledge/blockers.json`
- `.nucleus/runs/<workflowRunId>/result.json`