@hunter-harness/workflow-harness 0.2.41 → 0.2.43

package/harness/bundles/general/codex/harness-knowledge-ingest/SKILL.md

@@ -3,7 +3,7 @@ name: harness-knowledge-ingest
 description: 从 .harness/archive 归档整理、同步和维护项目知识索引。适用场景：ingest knowledge、sync
   knowledge、rebuild knowledge index、promote knowledge、确认知识条目、检查知识库是否过期。
 ---
-<!-- generated by harness_deploy.py; core=79326ada58817556; overlay=none; agent=codex; do not edit -->
+<!-- generated by harness_deploy.py; core=3b9f8916e29a59bb; overlay=none; agent=codex; do not edit -->
 # harness-knowledge-ingest
 
 从 `.harness/archive/**/reports/final/summary-data.json` 抽取项目知识，生成并维护本地 `.harness/knowledge/` 索引。
@@ -47,10 +47,12 @@ description: 从 .harness/archive 归档整理、同步和维护项目知识索
 .harness/knowledge/entries/superseded/*.json
 .harness/knowledge/entries/conflicted/*.json
 .harness/knowledge/cache/archive-entries/*.json
-.harness/knowledge/reports/ingest-report-YYYYMMDD-HHmmss.md
-.harness/knowledge/reports/verification-report-YYYYMMDD-HHmmss.md
-.harness/knowledge/reports/validator-suggestions-YYYYMMDD-HHmmss.md
-.harness/knowledge/reports/audit-report-YYYYMMDD-HHmmss.md
+.harness/knowledge/reports/ingest-report-*.md
+.harness/knowledge/reports/verification-report-*.md
+.harness/knowledge/reports/audit-report-*.md
+.harness/knowledge/reports/judge-export-<content-sha256>.json
+.harness/knowledge/reports/judgements-<content-sha256>.json
+.harness/knowledge/reports/latest.json
 .harness/knowledge/views/knowledge-dashboard.md
 .harness/knowledge/views/by-file.md
 .harness/knowledge/views/stale-items.md
@@ -67,14 +69,17 @@ description: 从 .harness/archive 归档整理、同步和维护项目知识索
 
 | 命令 | 用途 |
 |---|---|
-| `auto` | 一键防腐：首建 config、sync --update、**默认**写回 validator 建议、verify、audit；随后由 **Agent** 执行 judge 闭环 |
+| 无参数 / `auto` | 一键防腐：首建 config、sync --update、**默认**写回 validator 建议、verify、audit；随后由 **Agent** 执行 judge 闭环 |
+| `status` | 严格只读地返回 freshness 与 health |
+| `repair all` | 修复可证明的 legacy gate、归一化重复、冲突与报告保留；不确定项返回 `needsConfirmation` |
 | `ingest` | 重建/刷新知识索引，抽取 candidate；`--no-incremental` 强制全量重抽取 |
-| `sync` | 检查 index 与 archive/HEAD 一致性；`--update` 自动刷新 |
+| `sync --check` | 只读检查 index 与 archive/HEAD 一致性；`--update` 自动刷新 |
 | `promote` | candidate→active（显式 promote 或 autoPromote / judge 触发） |
 | `demote` | active→stale/candidate（显式 demote 或自动降级策略触发） |
 | `audit` | 生成 Candidate/Stale/Superseded/Conflict/Active Review 报告 |
 | `verify` | 执行 entry validators，刷新 lifecycle.validation，生成 verification-report |
 | `suggest-validators` | 生成 file_exists/file_contains validator 建议；`--apply` 写回 entry |
+| `admin <旧命令>` | 旧管理命令兼容入口 |
 | `mcp` | FastMCP stdio 入口，暴露 9 个工具（见 reference.md） |
 
 config.json 配置项（autoPromote / confidence / activeLifecycle / knowledgeValidation）详见 `reference.md`「Commands 详细」。
@@ -109,11 +114,17 @@ powershell.exe -Command "python '<skill-dir>\scripts\harness_knowledge.py' inges
 powershell.exe -Command "python '<skill-dir>\scripts\harness_knowledge.py' auto --project '<project-root>'"
 ```
 
+不传子命令时等价于 `auto`。`auto` 输出必须分别报告：
+
+- `freshness`：archive、HEAD、manifest、entry、SQLite 是否一致。
+- `health`：各 lifecycle、publication、validation 与待裁决工作量。
+
 `auto` 默认会写回确定性 validator 建议（`--no-apply-suggestions` 可关闭）。JSON 返回含 `lifecycle` 摘要（validatorsApplied、autoPromote、pendingAgentJudge 等）。
 
 ### Phase 3：Agent judge 闭环（auto 之后必须执行）
 
-当 `lifecycle.pendingAgentJudge > 0`、存在 `pending-judge` outbox，或 `judge export` 的 `counts.pending > 0` 时：
+当 `lifecycle.pendingAgentJudge > 0`、存在 `pending-judge` outbox，或 `judge export` 的
+`counts.requiredDecisionCount > 0` 时：
 
 1. `judge export`（或读 maintain 产出的 pending judgements）
 2. Agent 读取 export JSON，按 `reference.md`「Agent judge 启发式」批量写 `reports/judge-decisions-<ts>.json`
@@ -122,12 +133,15 @@ powershell.exe -Command "python '<skill-dir>\scripts\harness_knowledge.py' auto
 
 **禁止**默认输出「请人工确认 N 条 candidate」类五步待办清单。拿不准的 candidate 保持 `candidate` 状态留待下轮，记入 `skippedCandidates` 即可。
 
-裁决体量：`config.judge.maxCandidatesPerRun`（默认 100）；conflicted 优先全量裁决。
+`pendingAgentJudge`/`requiredDecisionCount` 是完整待裁决总量；`previewCount` 才受
+`config.judge.maxCandidatesPerRun`（默认 100）限制。已被 publication gate 阻断的条目
+只进入 `quarantinedCount`，不得混入 judge export。`defer` 必须保存证据指纹；来源、
+validator、冲突关系或 publication 证据变化后即使未到 `reviewAfter` 也重新进入裁决。
 
 ### Phase 4：同步检查（可选）
 
 ```powershell
-powershell.exe -Command "python '<skill-dir>\scripts\harness_knowledge.py' sync --project '<project-root>'"
+powershell.exe -Command "python '<skill-dir>\scripts\harness_knowledge.py' status --project '<project-root>'"
 ```
 
 当 `upToDate=false` 时，运行 `sync --update` 或重新 `auto`，再交给 `harness-knowledge-query` 查询。
@@ -136,7 +150,11 @@ powershell.exe -Command "python '<skill-dir>\scripts\harness_knowledge.py' sync
 
 仅在用户点名单条、或 `manualReview=true` 需人工确认时使用 `promote` / `demote`。日常归档后不要逐条人工复核。
 
-**发布门禁**：promote / judge apply / autoPromote 会校验来源归档——`reportPipeline.sourceConsistency` 缺失或失败、authoritative pointer /hash 不通过的归档，其条目带 `lifecycle.publishBlocked`，只能停留在 quarantined candidate。先 `harness_archive.py repair` 修复并重新 ingest，再 promote（详见 `reference.md`「发布门禁」）。
+**发布门禁**：knowledge publication 与 archive release status 独立。promote / judge apply /
+autoPromote 校验 authoritative pointer/hash 与 `reportPipeline.sourceConsistency`；即使归档
+最终状态为 WARN，只要知识来源一致也可发布，但保留 release advisory。旧归档只有在
+summary/hash/source commit 可独立证明时才自动生成 attestation；否则保持 quarantined 并
+返回 `needsConfirmation`（详见 `reference.md`「发布门禁」）。
 
 ### Phase 6：解释同步结果
 
@@ -146,10 +164,15 @@ powershell.exe -Command "python '<skill-dir>\scripts\harness_knowledge.py' sync
 - 如需刷新，具体原因是 archive 增删、checksum 变化、sqlite 缺失，还是 HEAD 改变。
 - 本次是否自动刷新。
 - 当前 `active` / `candidate` / `stale` 的数量。
+- 分别报告 `freshness` 与 `health`，不要用一个 `status` 覆盖
+  lifecycle/review/publication/validation 四个正交维度。
 
 ## Knowledge extraction rules
 
-- Detect duplicate IDs, duplicate content, and conflicting active facts.
+- 优先读取归档显式 `knowledgeCandidates[]`；维护流水线、测试计数等
+  `category=process-observation` 不进入长期知识。
+- Duplicate content 使用 Unicode、空白、标点与大小写归一化指纹，并在全量重建时迁移。
+- 冲突必须同时有相同实体、共享来源范围和双方证据；仅关键词相反不得判为冲突。
 - Keep project-local entries excluded from any global index unless explicitly selected.
 - Validate lifecycle relationships.
 - Default generated entries are `candidate`; only config-gated `autoPromote` may promote high-confidence long-lived entries to `active`.
@@ -191,7 +214,7 @@ powershell.exe -Command "python '<skill-dir>\scripts\harness_knowledge.py' sync
 本 skill 自带最小测试：
 
 ```powershell
-powershell.exe -Command "python -m unittest '<skill-dir>\tests\test_harness_knowledge.py'"
+powershell.exe -Command "python 'harness\scripts\harness_test_runner.py' unittest --profile safe --tests-dir '<skill-dir>\tests' --timeout-seconds 300 --verbosity 1"
 ```
 
 完成脚本修改后必须至少运行该测试。若在真实项目中验证，还应运行：
@@ -221,13 +244,16 @@ powershell.exe -Command "python '<skill-dir>\scripts\harness_knowledge.py' sync
 - `upToDate` 及 `reasons`（sync）或新增/覆盖条目数（ingest/promote）。
 - 当前 `active` / `candidate` / `stale` 数量统计。
 - 产物路径（`index.json`、`index.sqlite`、`views/`、`reports/`）。
-- `lifecycle` 摘要：`validatorsApplied`、`candidateAutoPromoted`、`pendingAgentJudge` 等。
+- `lifecycle` 摘要：`validatorsApplied`、`candidateAutoPromoted`、兼容整数
+  `pendingAgentJudge`，以及
+  `pendingAgentJudgeSummary.requiredDecisionCount/previewCount/quarantinedCount` 等。
+- validator 摘要：`eligible/selected/applied/remaining/unavailable`，不得只报告本轮抽样数。
 - **已处理报告**（auto + judge 后）：promoted/dropped/superseded/kept/deferred/skipped 计数与 `reports/judge-decisions-*.json`、`judgements-*.json` 路径；人工判断还会追加到 `judgements/decisions.json`，后续 ingest 不得抹除。`defer` 必须带 `reviewAfter`，到期前不重复进入待判断清单。
 - 仅当 `upToDate=false` 时建议 `sync --update`；查询历史 → `/harness-knowledge-query`。**禁止**默认列出「请人工确认 N 条 candidate」待办。
 
 ## 渐进披露
 
-- **Read `reference.md`** 仅在执行命令或查阅 config.json 配置时 — 含 Commands 详细示例（9 命令的 powershell 示例 + config.json 配置）与变更日志（v1.7–v1.13 补充能力）。
+- **Read `reference.md`** 仅在执行命令或查阅 config.json 配置时 — 含 Commands 详细示例、config.json 配置与兼容说明。
 
 ## 交互白名单
 

package/harness/bundles/general/codex/harness-knowledge-ingest/reference.md

@@ -16,6 +16,9 @@ description: harness-knowledge-ingest 的命令详细示例、config.json 配置
 powershell.exe -Command "python '<skill-dir>\scripts\harness_knowledge.py' auto --project '<project-root>'"
 ```
 
+省略子命令时也进入 `auto`；旧命令可放在 `admin` 后继续调用，例如
+`admin audit --project <root>`。
+
 `auto` 会按默认维护顺序执行：首建 `config.json`（若缺失）、`sync --update`、**默认写回** validator 建议、`verify`、`audit`。首次发现 `.harness/knowledge/config.json` 不存在时，会写入启用版 `autoPromote` + `activeLifecycle.autoDemote` + `knowledgeValidation.autoDemoteActive` + `judge.maxCandidatesPerRun` 配置。
 
 关闭 validator 写回：
@@ -35,7 +38,11 @@ powershell.exe -Command "python '<skill-dir>\scripts\harness_knowledge.py' auto
 
 - **conflicted**：优先 `supersede` 较旧/较弱证据方；对称难判 → `keep-conflict` + reason
 - **candidate**：`decision|api-contract|requirement|pitfall` 且 confidence 高 → `promote`；`implementation|test-evidence` 倾向 `drop` 或保持 candidate
-- 超过 `judge.maxCandidatesPerRun`（默认 100）的低分 candidate：跳过，记入 `skippedCandidates`
+- `requiredDecisionCount` 是完整总量，`previewCount` 才受
+  `judge.maxCandidatesPerRun`（默认 100）限制。
+- publication gate 阻断项计入 `quarantinedCount`，不进入待裁决单位。
+- 超出预览窗口的 candidate 计入 `deferredByLimitCount`，不能让
+  `pendingAgentJudge` 误报为窗口大小。
 
 ```powershell
 powershell.exe -Command "python '<skill-dir>\scripts\harness_knowledge.py' judge --project '<project-root>' --export '<export.json>'"
@@ -65,15 +72,18 @@ powershell.exe -Command "python '<skill-dir>\scripts\harness_knowledge.py' inges
 ### Sync knowledge
 
 ```powershell
-powershell.exe -Command "python '<skill-dir>\scripts\harness_knowledge.py' sync --project '<project-root>'"
+powershell.exe -Command "python '<skill-dir>\scripts\harness_knowledge.py' status --project '<project-root>'"
 ```
 
-检查 `.harness/knowledge` 是否与 `.harness/archive` 和当前 HEAD 一致。输出 JSON 包含：
+严格只读地检查 `.harness/knowledge` 是否与 `.harness/archive` 和当前 HEAD 一致。也可用
+兼容命令 `sync --check`。输出 JSON 包含：
 
 - `upToDate`
 - `reasons`
 - `archiveCount`
 - `paths`
+- `freshness`
+- `health`（lifecycle/review/publication/validation 四个独立维度）
 
 如果希望发现过期后自动刷新：
 
@@ -87,6 +97,24 @@ powershell.exe -Command "python '<skill-dir>\scripts\harness_knowledge.py' sync
 powershell.exe -Command "python '<skill-dir>\scripts\harness_knowledge.py' sync --project '<project-root>' --update --no-incremental"
 ```
 
+### Repair
+
+先诊断、不写入：
+
+```powershell
+powershell.exe -Command "python '<skill-dir>\scripts\harness_knowledge.py' repair all --project '<project-root>' --no-apply"
+```
+
+执行可证明的修复：
+
+```powershell
+powershell.exe -Command "python '<skill-dir>\scripts\harness_knowledge.py' repair all --project '<project-root>'"
+```
+
+repair 处理归一化重复、冲突重算、旧 publication gate attestation 与报告保留。旧归档只有在
+authoritative summary/hash 和 source commit 均可独立验证时自动修复；其余项进入
+`needsConfirmation`，不得猜测或静默放行。
+
 ### Verify knowledge validators
 
 ```powershell
@@ -129,7 +157,10 @@ powershell.exe -Command "python '<skill-dir>\scripts\harness_knowledge.py' verif
 powershell.exe -Command "python '<skill-dir>\scripts\harness_knowledge.py' suggest-validators --project '<project-root>' --limit 20"
 ```
 
-默认只生成建议和 `reports/validator-suggestions-*.md`，不会改写 entries。建议来源是当前 entry 的 `scope.sourceFiles`、正文/标题/关键词中的稳定 token，以及项目文件中的实际内容。当前只生成安全的 `file_exists` / `file_contains` 建议。
+默认只生成建议和 content-addressed report，不会改写 entries。结果分别报告
+`eligible/selected/suggested/applied/remaining/unavailable`。建议来源是当前 entry 的
+`scope.sourceFiles`、正文/标题/关键词中的稳定 token，以及项目文件中的实际内容。
+当前只生成安全的 `file_exists` / `file_contains` 建议。
 
 如需把建议写入 entry JSON：
 
@@ -145,12 +176,18 @@ powershell.exe -Command "python '<skill-dir>\scripts\harness_knowledge.py' sugge
 powershell.exe -Command "python '<skill-dir>\scripts\harness_knowledge.py' promote --project '<project-root>' --id '<entry-id>' --note '<人工确认说明>'"
 ```
 
-**发布门禁（archive publication gate）**：promote / judge apply / autoPromote 只处理来自**已验证归档**的条目。以下来源归档会被阻断并在条目上标记 `lifecycle.publishBlocked`（ingest 仍可生成 quarantined candidate，但不得 active/promote）：
+**发布门禁（archive publication gate）**：promote / judge apply / autoPromote 只处理
+knowledge publication 证据通过的条目。它与归档 release status 独立：归档为 WARN 但
+source consistency 与 authoritative pointer/hash 均通过时，知识可以发布，同时保留
+`archiveReleaseEligibility` advisory。以下来源归档会被阻断并在条目上标记
+`lifecycle.publishBlocked`：
 
 - 归档 summary 缺少 `reportPipeline.sourceConsistency`（source consistency 未运行）或 `ok=false`；
 - `derived/authoritative.json` pointer 缺失、版本目录不可读，或 repair record / pointer 的 summary hash 不匹配（DEGRADED）。
 
-修复路径：先运行 `harness_archive.py repair` 生成通过两层 validator 的新 derived version，再重新 ingest（旧错误条目标记 superseded），之后 promote 才放行。
+修复路径：优先运行本 skill 的 `repair legacy-publication-gates`。只有 summary/hash/source
+commit 都可证明时才生成 attestation；否则输出 `needsConfirmation`。也可由 archive repair
+生成通过 validator 的新 derived version，再重新 ingest。
 
 将一条 `candidate` 提升为 `active`，写入：
 
@@ -289,6 +326,20 @@ powershell.exe -Command "python '<skill-dir>\scripts\harness_knowledge_mcp.py'"
 
 ## 变更日志
 
+## v1.15 补充能力（sync/knowledge retrospective hardening）
+
+- 默认无参数进入 `auto`；新增严格只读 `status`、`sync --check`、`repair all` 与
+  `admin <legacy-command>` 兼容入口。
+- 显式 `knowledgeCandidates[]` 为首选来源，process observation 不再进入长期知识。
+- 内容去重改为归一化指纹；冲突要求共同实体、来源范围与双方 evidence。
+- freshness 与 health 分离，health 按 lifecycle/review/publication/validation 正交报告。
+- judge 输出完整 `requiredDecisionCount`、有界 `previewCount` 和 `quarantinedCount`；
+  blocked 条目不进入 judge；defer 绑定证据指纹。
+- knowledge publication gate 与 archive release status 解耦，legacy gate 仅在可证明时修复。
+- judge/rollback 等 JSON 报告采用 content-addressed 文件、`latest-*` 指针与有界保留；
+  rollback snapshot 使用 gzip。
+- validator 建议输出 `eligible/selected/applied/remaining/unavailable`。
+
 ## v1.7 补充能力
 
 当前脚本额外支持：