@hunter-harness/workflow-harness 0.2.41 → 0.2.42

package/harness/bundles/general/claude-code/harness-knowledge-query/SKILL.md

@@ -20,7 +20,7 @@ disallowed-tools:
   - Bash(awk *)
   - Bash(curl *)
 ---
-<!-- generated by harness_deploy.py; core=23e4a1b1c35dd556; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=433205be6e827dd9; overlay=none; agent=claude-code; do not edit -->
 # harness-knowledge-query
 
 并行 change 中查询必须传 `--change <change-id>`；成功后以该 change 的 `meta/knowledge-context.json` 为稳定指针。全局 `context-packs/latest.json` 仅向后兼容，不得用于判断多个 active change 的上下文归属。

package/harness/bundles/general/claude-code/harness-plan/SKILL.md

@@ -20,7 +20,7 @@ disallowed-tools:
   - Bash(awk *)
   - Bash(curl *)
 ---
-<!-- generated by harness_deploy.py; core=23e4a1b1c35dd556; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=433205be6e827dd9; overlay=none; agent=claude-code; do not edit -->
 # harness-plan — 需求规划
 
 ## Purpose

package/harness/bundles/general/claude-code/harness-review/SKILL.md

@@ -21,7 +21,7 @@ disallowed-tools:
   - Bash(curl *)
   - Bash(codegraph *)
 ---
-<!-- generated by harness_deploy.py; core=23e4a1b1c35dd556; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=433205be6e827dd9; overlay=none; agent=claude-code; do not edit -->
 # harness-review — 代码审查
 
 ## Purpose

package/harness/bundles/general/claude-code/harness-run/SKILL.md

@@ -21,7 +21,7 @@ disallowed-tools:
   - Bash(curl *)
   - Bash(codegraph *)
 ---
-<!-- generated by harness_deploy.py; core=23e4a1b1c35dd556; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=433205be6e827dd9; overlay=none; agent=claude-code; do not edit -->
 # harness-run — 需求编码
 
 ## Purpose

package/harness/bundles/general/claude-code/harness-submit/SKILL.md

@@ -20,7 +20,7 @@ disallowed-tools:
   - Bash(awk *)
   - Bash(curl *)
 ---
-<!-- generated by harness_deploy.py; core=23e4a1b1c35dd556; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=433205be6e827dd9; overlay=none; agent=claude-code; do not edit -->
 # harness-submit — 最终提交（含 worktree 合并）
 
 ## Purpose

package/harness/bundles/general/claude-code/harness-sync/SKILL.md

@@ -19,7 +19,7 @@ disallowed-tools:
   - Bash(awk *)
   - Bash(curl *)
 ---
-<!-- generated by harness_deploy.py; core=23e4a1b1c35dd556; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=433205be6e827dd9; overlay=none; agent=claude-code; do not edit -->
 # harness-sync
 
 ## Purpose
@@ -28,13 +28,10 @@ disallowed-tools:
 
 ## Before running
 
-读取 `reference.md`。先执行只读能力握手；若最低 CLI 版本或任一必需能力不满足，立即停止，不得先运行 knowledge、refresh 或其他重操作：
-
-```powershell
-npx hunter-harness capabilities --json
-```
-
-工作流要求 `sync@1`、`rules-sync@1`、`rules-review@1`、`knowledge-sync@2`。`BLOCKED_CAPABILITY_MISMATCH` 属环境阻塞，不得降级为手工拼接旧流程。
+读取 `reference.md`。`sync` 自身会在任何重操作之前完成能力握手；不要另起一个
+`capabilities` 进程。工作流要求 `sync@2`、`rules-sync@1`、`rules-review@1`、
+`knowledge-sync@3`、`codegraph-status@2`。`BLOCKED_CAPABILITY_MISMATCH` 属环境阻塞，
+不得降级为手工拼接旧流程。
 
 ## Run
 
@@ -44,17 +41,26 @@ npx hunter-harness sync --project <项目路径> --profile interactive --progres
 
 CLI 负责 Python runtime 解析、投影事务、knowledge、rules、map、指令图、配置来源、change 状态及 CodeGraph 证据汇总。禁止直接调用内部 Python 脚本，禁止使用固定 `HEAD~5`，禁止自动全量重建 CodeGraph。
 
-长阶段的 heartbeat 写 stderr；stdout 只保留紧凑摘要。完整报告写入摘要中的 `reportPath`，并带 `reportSha256`。不得把完整 JSON 报告直接回显到对话。
+只读诊断使用 `--check`（`--dry-run` 为兼容别名）；它不得写报告、receipt 或投影。
+长阶段的 heartbeat 写 stderr；stdout 只保留紧凑摘要。完整报告写入摘要中的
+`reportPath`，并带 `reportSha256`。需要组件级证据时显式加 `--verbose`，不得默认把完整
+JSON 报告回显到对话。
+
+摘要中的 `remediations[]` 是稳定修复契约。先用对应 `previewCommand` 预览；低风险修复用
+`--apply safe`，指定修复用 `--fix <id>`。需覆盖受管投影的修复必须同时提供 `--yes`，
+并依赖 refresh 事务留下的 before snapshot；不允许绕过确认或无备份覆盖。指定修复时，
+无关组件只做只读评估，不得顺带写入。
 
 ## Interpret
 
 - `OK`：所有可验证组件通过。
+- `ADVISORY`：索引最新，但有待评审候选等非阻塞健康提示；退出码仍为 0。
 - `WARN`：存在过期、冲突、待评审或 `UNKNOWN` 证据；按 `reportPath` 中的 `nextAction` 处理。
 - `FAIL`：组件执行失败；不得宣称同步完成。
 - `BLOCKED`：runtime、项目状态或能力契约阻塞；先修复阻塞条件。
 - `UNKNOWN`：证据不足，不等于成功，也不触发无界重建。
 
-非交互或 CI 使用 `--profile general --progress jsonl --json`，不得等待规则候选确认。交互式运行若报告规则待评审，再按 `reference.md` 的显式入口处理。
+非交互或 CI 使用 `--check --profile general --progress jsonl --json`，不得等待规则候选确认。交互式运行若报告规则待评审，再按 `reference.md` 的显式入口处理。
 
 ## Safety
 

package/harness/bundles/general/claude-code/harness-sync/reference.md

@@ -6,13 +6,8 @@ description: harness-sync 的能力契约、统一状态模型、报告收据和
 
 ## 1. 能力握手
 
-统一入口执行前读取：
-
-```powershell
-npx hunter-harness capabilities --json
-```
-
-工作流 family manifest 声明 `minimumCliVersion` 和 `capabilities`。CLI 在任何高成本阶段之前核对版本与能力；缺失时返回：
+工作流 family manifest 声明 `minimumCliVersion` 和 `capabilities`。`sync` 在任何高成本
+阶段之前自行核对版本与能力；Skill 不要再运行独立的 `capabilities` 子进程。缺失时返回：
 
 ```json
 {
@@ -47,22 +42,41 @@ npx hunter-harness sync --project <项目路径> --profile interactive --progres
 CI/非交互式：
 
 ```powershell
-npx hunter-harness sync --project <项目路径> --profile general --progress jsonl --json
+npx hunter-harness sync --check --project <项目路径> --profile general --progress jsonl --json
 ```
 
-`--dry-run` 只做只读检查或事务预览，不应生成持久报告、receipt 或投影。每个长阶段通过 stderr 输出受限 heartbeat；stdout 只输出：
+`--check` 是严格只读检查；`--dry-run` 是兼容别名。两者都不生成持久报告、receipt 或
+投影。每个长阶段通过 stderr 输出受限 heartbeat；stdout 默认只输出：
 
 ```json
 {
   "status": "WARN",
   "runId": "<run-id>",
-  "components": {"ok": 7, "warn": 1, "fail": 0, "blocked": 0, "unknown": 1},
+  "components": {"ok": 7, "advisory": 1, "warn": 0, "fail": 0, "blocked": 0, "unknown": 0},
+  "versions": {
+    "cliVersion": "0.0.0",
+    "workflowBundleVersion": "0.0.0",
+    "adapterBundleVersions": {}
+  },
+  "remediations": [],
   "reportPath": ".harness/runtime/sync/<run-id>/reports/sync-report.json",
   "reportSha256": "<sha256>"
 }
 ```
 
-详细报告必须受大小限制，并包含每个组件的 `status`、`reasonCode`、`observedAt`、`durationMs`、输入/输出 hash、证据、是否自动修复及 `nextAction`。
+只读检查的 `reportPath/reportSha256` 为 `null`。详细报告必须受大小限制，并包含每个组件
+的 `status`、`reasonCode`、`observedAt`、`durationMs`、输入/输出 hash、证据、是否自动
+修复及 `nextAction`；只有显式 `--verbose` 才把组件级详情写到 stdout。
+
+### 结构化修复
+
+- `remediations[]` 含稳定 `id`、风险、写入范围、备份/回滚说明、预计耗时、是否需确认、
+  `previewCommand` 与 `applyCommand`。
+- `--apply safe` 只执行低风险、无需确认的修复。
+- `--fix <id>` 只执行该项；需要覆盖受管 Adapter 时必须加 `--yes`。
+- 指定修复时，其他组件仍参与诊断但保持只读。
+- Adapter 覆盖由 refresh 事务执行，before snapshot 位于最新 committed refresh
+  transaction；事务失败会自动回滚。预览永远不得产生写入。
 
 ## 4. 组件状态
 
@@ -77,15 +91,21 @@ npx hunter-harness sync --project <项目路径> --profile general --progress js
 | instruction graph | 入口、include 边、环、主题可达性 | 缺失引用或循环为 `FAIL` |
 | config origins | canonical/projection 路径与 hash | 漂移 `WARN`，不静默覆盖 |
 | changes | 五态分类及归档收据 | `INVALID`/`ORPHAN` 不自动删除 |
-| CodeGraph | 索引文件、守护进程管道、watcher 日志、pending、watcher lag | 输出 `CURRENT/PENDING/STALE/INDEX_PRESENT_UNVERIFIED/MISSING/UNKNOWN`；不自动全量 reindex |
+| CodeGraph | `codegraph status --json` 的 pending、数据库观察时间、watcher 可达性 | 输出 `CURRENT/PENDING/STALE/INDEX_PRESENT_UNVERIFIED/MISSING/UNKNOWN`；日志 mtime 只证明 watcher 活动，不证明索引完成；不自动全量 reindex |
 
-全局状态优先级：`BLOCKED` → `FAIL` → `WARN` → `OK`。任一 `UNKNOWN` 至少使全局结果为 `WARN`。
+全局状态优先级：`BLOCKED` → `FAIL` → `WARN` → `ADVISORY` → `OK`。任一 `UNKNOWN`
+至少使全局结果为 `WARN`。knowledge freshness 与 health 分开：索引一致但仍有待裁决候选时
+为 `ADVISORY`，不得误报为过期。
 
 ## 5. Git 与 CodeGraph
 
 增量基线来自上次成功 sync receipt 的 `headCommit`。首次运行或 receipt 不可用时，仅收集当前 HEAD 和有界文件统计；禁止固定 `HEAD~5`。
 
-CodeGraph 状态探测读取 `.codegraph/codegraph.db`、daemon receipt/log，尝试有界管道连接，并比较项目文件与最近索引观察时间。只有服务可达、watcher 已启用且 `pendingFileCount=0` 时为 `CURRENT`；此时才可将当前 HEAD 记录为推断的 `indexedCommit`。不可用、待同步或证据不足时分别报告 `STALE/PENDING/INDEX_PRESENT_UNVERIFIED/UNKNOWN` 与明确后续动作。不要在 sync 内执行全量索引，不使用依赖 shell 连接符的跨平台命令。
+CodeGraph 状态探测优先读取 `codegraph status --json` 的权威 pending 列表；只有该 API
+不可用时才退回受限文件扫描，并把来源标成 `database-scan` 或 `unverified`。`.agents/`、
+`.cursor/`、`.claude/` 等 Adapter 投影和 Markdown 文档不计入源码 pending。daemon log
+mtime 只写入 `watcherObservedAt`，不能冒充 `indexObservedAt`。只有服务可达、watcher 已
+启用且权威 `pendingFileCount=0` 时为 `CURRENT`。不要在 sync 内执行全量索引。
 
 ## 6. Instruction graph
 

package/harness/bundles/general/claude-code/harness-test/SKILL.md

@@ -22,7 +22,7 @@ disallowed-tools:
   - Bash(node *)
   - Bash(codegraph *)
 ---
-<!-- generated by harness_deploy.py; core=23e4a1b1c35dd556; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=433205be6e827dd9; overlay=none; agent=claude-code; do not edit -->
 # harness-test — 测试执行
 
 ## Purpose

package/harness/bundles/general/codebuddy/.harness-build.json

@@ -2,5 +2,5 @@
   "schemaVersion": 1,
   "overlay": "none",
   "agent": "codebuddy",
-  "coreHash": "23e4a1b1c35dd556"
+  "coreHash": "433205be6e827dd9"
 }

package/harness/bundles/general/codebuddy/harness-archive/SKILL.md

@@ -3,7 +3,7 @@ name: harness-archive
 description: 归档所有变更产出（计划/测试报告/审查/SQL/API文档）到
   .harness/archive/，含归档元数据和可视化最终总结。使用场景：归档、完成归档、收尾、打包产出物
 ---
-<!-- generated by harness_deploy.py; core=23e4a1b1c35dd556; overlay=none; agent=codebuddy; do not edit -->
+<!-- generated by harness_deploy.py; core=433205be6e827dd9; overlay=none; agent=codebuddy; do not edit -->
 # harness-archive — 变更归档
 
 ## Purpose

package/harness/bundles/general/codebuddy/harness-codebase-map/SKILL.md

@@ -3,7 +3,7 @@ name: harness-codebase-map
 description: 分析现有代码库并生成 .harness/codebase/map/
   下的结构化代码库地图。用于陌生项目理解、重大改造前梳理、harness-sync 提示 map 过期后的人工刷新。
 ---
-<!-- generated by harness_deploy.py; core=23e4a1b1c35dd556; overlay=none; agent=codebuddy; do not edit -->
+<!-- generated by harness_deploy.py; core=433205be6e827dd9; overlay=none; agent=codebuddy; do not edit -->
 # harness-codebase-map — 代码库地图
 
 ## Purpose

package/harness/bundles/general/codebuddy/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=23e4a1b1c35dd556; overlay=none; agent=codebuddy; do not edit -->
+<!-- generated by harness_deploy.py; core=433205be6e827dd9; overlay=none; agent=codebuddy; 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/codebuddy/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 补充能力
 
 当前脚本额外支持：