@hunter-harness/workflow-harness 0.2.0 → 0.2.2

package/harness/bundles/general/claude-code/scripts/harness_service.py

@@ -125,7 +125,14 @@ def read_json(path: Path) -> Any:
 def write_json(path: Path, data: Any) -> None:
     path.parent.mkdir(parents=True, exist_ok=True)
     text = json.dumps(data, ensure_ascii=False, indent=2) + "\n"
-    path.write_text(text, encoding="utf-8", newline="\n")
+    # 原子写 temp+os.replace：崩溃后不留半写文件（与 runtime-helpers.mjs writeJsonUtf8NoBom 一致）。
+    tmp = path.with_name(f".{path.name}.{os.getpid()}.tmp")
+    try:
+        tmp.write_text(text, encoding="utf-8", newline="\n")
+        os.replace(tmp, path)
+    except BaseException:
+        tmp.unlink(missing_ok=True)
+        raise
 
 
 def load_build_profile(project: Path) -> dict[str, Any]:
@@ -153,6 +160,72 @@ def get_service_start(profile: dict[str, Any]) -> dict[str, Any]:
     return svc
 
 
+# Worktree/change 路径标记：持久 profile 的 serviceStart 不得含这些具体路径。
+# runtime resolve 把具体 overlay/profile 注入到 session，不写回持久 profile
+# （spec §3.1 持久 profile 只保存模板；§3.4 修复输入端陈旧 profile）。
+STALE_WORKTREE_MARKERS: tuple[str, ...] = (
+    ".claude/worktrees/",
+    ".cursor/worktrees/",
+    ".codeium/worktrees/",
+)
+
+
+def _detect_stale_persistent_values(service_start: dict[str, Any]) -> list[str]:
+    """检测 serviceStart 是否含具体旧 worktree/change 持久路径。
+
+    持久 profile 只保存模板；command/overlayPath/profile 嵌入 worktree 路径
+    说明是 v1 残留或被错误写回的已解析 overlay，必须拒绝（spec §3.4）。
+    """
+    stale: list[str] = []
+    for field in ("command", "overlayPath", "profile"):
+        val = service_start.get(field)
+        if not isinstance(val, str) or not val:
+            continue
+        for marker in STALE_WORKTREE_MARKERS:
+            if marker in val:
+                stale.append(f"{field} contains stale worktree path: {marker}")
+                break
+    return stale
+
+
+def resolve_service_start(
+    profile: dict[str, Any],
+    *,
+    change_name: str | None = None,
+    worktree_root: Path | None = None,
+    overlay_path: str | None = None,
+) -> dict[str, Any]:
+    """从模板 serviceStart + runtime context 生成 resolved serviceStart。
+
+    spec §3.1：持久 profile 的 serviceStart 是模板（profile/overlayPath 留空）；
+    runtime 注入具体 overlay/profile 到返回值，写入 session，**不写回持久 profile**。
+    spec §3.4：含 worktree/change 陈旧持久值时拒绝（修复输入端陈旧 profile）。
+
+    向后兼容：持久 profile.profile 非空（如 v1 残留 "local-dev"）→ 保留；
+    overlay_path 未提供 → 保留持久 overlayPath（可能为空）。
+    """
+    service_start = get_service_start(profile)  # 校验 command 非空
+
+    stale = _detect_stale_persistent_values(service_start)
+    if stale:
+        raise ValueError(
+            "serviceStart contains stale persistent worktree/change values; "
+            "run harness_profile.py migrate to clear: " + "; ".join(stale)
+        )
+
+    resolved = dict(service_start)
+    # runtime overlay 注入：显式 overlay_path 覆盖；否则保留持久模板值
+    if overlay_path is not None:
+        resolved["overlayPath"] = overlay_path
+    # runtime profile 注入：持久 profile 留空时用 change_name；非空则保留
+    if not str(resolved.get("profile") or "").strip():
+        resolved["profile"] = change_name or "local-dev"
+    # worktree_root 预留给未来相对 overlay 路径解析（spec §3.6 state snapshot）；
+    # 不写入返回值，避免污染 session。
+    _ = worktree_root
+    return resolved
+
+
 def resolve_service_input_files(
     project: Path,
     service_start: dict[str, Any],
@@ -934,10 +1007,24 @@ def cmd_ensure(args: argparse.Namespace) -> int:
 
     try:
         profile = load_build_profile(project)
-        service_start = get_service_start(profile)
     except (OSError, ValueError, FileNotFoundError, json.JSONDecodeError) as exc:
         return emit_error(str(exc), as_json=as_json)
 
+    # cluster 3 (spec §3.1/§3.4): resolve 模板 serviceStart + runtime context。
+    # 持久 profile 只保存模板；runtime overlay/profile 注入到 session，不写回持久 profile。
+    # 含 worktree/change 陈旧持久值时拒绝（修复输入端陈旧 profile）。
+    change_name = getattr(args, "change_name", None) or change_dir.name
+    overlay = getattr(args, "overlay", None)
+    try:
+        service_start = resolve_service_start(
+            profile,
+            change_name=change_name,
+            worktree_root=project,
+            overlay_path=overlay,
+        )
+    except ValueError as exc:
+        return emit_error(str(exc), as_json=as_json)
+
     command = str(service_start["command"]).strip()
     port = extract_port(service_start)
 
@@ -1292,6 +1379,16 @@ def build_parser() -> argparse.ArgumentParser:
         default=None,
         help="comma-separated service module source files for inputsHash",
     )
+    p_ensure.add_argument(
+        "--change-name",
+        default=None,
+        help="change-name for runtime profile resolve (default: change-dir name)",
+    )
+    p_ensure.add_argument(
+        "--overlay",
+        default=None,
+        help="runtime overlay path injected into resolved serviceStart",
+    )
     p_ensure.add_argument("--json", action="store_true")
     p_ensure.set_defaults(func=cmd_ensure)
 

package/harness/bundles/general/claude-code/scripts/harness_state.py

@@ -0,0 +1,179 @@
+#!/usr/bin/env python3
+"""Harness state/context snapshot (cluster 3, spec §3.6).
+
+Per-segment fingerprints for project/worktree/git/profile/rules/map/knowledge/
+diff. Each segment fails independently; cache miss re-captures only the affected
+segment. plan/run/test/review/submit read this snapshot; stale segments are
+re-captured by the script. Never skip code or verification gates on cache alone.
+
+Python 3.10+ stdlib only. UTF-8 without BOM. Windows path friendly.
+"""
+
+from __future__ import annotations
+
+import datetime as dt
+import hashlib
+import json
+import os
+import sys
+from pathlib import Path
+from typing import Any
+
+
+SCRIPTS_DIR = Path(__file__).resolve().parent
+if str(SCRIPTS_DIR) not in sys.path:
+    sys.path.insert(0, str(SCRIPTS_DIR))
+
+from harness_ledger import compute_inputs_hash  # noqa: E402
+
+
+if hasattr(sys.stdout, "reconfigure"):
+    sys.stdout.reconfigure(encoding="utf-8")
+if hasattr(sys.stderr, "reconfigure"):
+    sys.stderr.reconfigure(encoding="utf-8")
+
+
+SNAPSHOT_SCHEMA_VERSION = 1
+SNAPSHOT_REL = Path("meta") / "state-snapshot.json"
+
+
+def now_iso() -> str:
+    return dt.datetime.now().astimezone().isoformat(timespec="seconds")
+
+
+def read_json(path: Path) -> Any:
+    # utf-8-sig 兼容可能残留的 BOM（与 harness_ledger.py 保持一致）。
+    return json.loads(path.read_text(encoding="utf-8-sig"))
+
+
+def write_json(path: Path, data: Any) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    text = json.dumps(data, ensure_ascii=False, indent=2) + "\n"
+    # 强制 LF，UTF-8 无 BOM（与 harness_ledger/harness_profile 保持一致）。
+    # 原子写 temp+os.replace：崩溃后不留半写文件（与 runtime-helpers.mjs writeJsonUtf8NoBom 一致）。
+    tmp = path.with_name(f".{path.name}.{os.getpid()}.tmp")
+    try:
+        tmp.write_text(text, encoding="utf-8", newline="\n")
+        os.replace(tmp, path)
+    except BaseException:
+        tmp.unlink(missing_ok=True)
+        raise
+
+
+def snapshot_path(change_dir: Path) -> Path:
+    return change_dir / SNAPSHOT_REL
+
+
+def _empty_segment_fingerprint() -> str:
+    return "sha256:" + hashlib.sha256(b"").hexdigest()
+
+
+def capture_file_segment(
+    files: list[str], *, captured_at: str | None = None
+) -> dict[str, Any]:
+    """对一组文件算指纹（compute_inputs_hash，order-independent），返回 segment dict。
+
+    空文件集 → 稳定空指纹 + 空 files（段存在但无输入，不算失效）。
+    缺失文件由 compute_inputs_hash 抛 FileNotFoundError（调用方应保证文件存在）。
+    """
+    if files:
+        fp, resolved = compute_inputs_hash(files)
+        return {
+            "fingerprint": fp,
+            "files": resolved,
+            "capturedAt": captured_at or now_iso(),
+        }
+    return {
+        "fingerprint": _empty_segment_fingerprint(),
+        "files": [],
+        "capturedAt": captured_at or now_iso(),
+    }
+
+
+def capture_snapshot(
+    change_dir: Path,
+    *,
+    change_name: str,
+    project: Path,
+    worktree_root: Path,
+    base: str | None = None,
+    head: str | None = None,
+    segment_files: dict[str, list[str]] | None = None,
+) -> dict[str, Any]:
+    """采集全段 state snapshot。
+
+    segment_files 指定每段（profile/rules/map/knowledge/...）的文件集；调用方
+    （各 skill）决定每段采什么文件，snapshot 只负责采集 + 比对 + 失效。
+    git 段记录 base/head；diff 指纹由调用方按需用 harness_ledger.compute_diff_hash
+    采后填入 segment_files（spec §3.6）。
+    """
+    _ = change_dir  # 预留给未来 write-back；当前 capture 只返回 dict
+    segment_files = segment_files or {}
+    segments: dict[str, Any] = {}
+    for name, files in segment_files.items():
+        segments[name] = capture_file_segment(files)
+
+    return {
+        "schemaVersion": SNAPSHOT_SCHEMA_VERSION,
+        "generatedAt": now_iso(),
+        "changeName": change_name,
+        "project": {"root": str(project.resolve())},
+        "worktree": {"root": str(Path(worktree_root).resolve())},
+        "git": {"base": base or "", "head": head or ""},
+        "segments": segments,
+    }
+
+
+def write_snapshot(change_dir: Path, snapshot: dict[str, Any]) -> Path:
+    path = snapshot_path(change_dir)
+    write_json(path, snapshot)
+    return path
+
+
+def load_snapshot(change_dir: Path) -> dict[str, Any] | None:
+    path = snapshot_path(change_dir)
+    if not path.is_file():
+        return None
+    try:
+        data = read_json(path)
+    except (OSError, json.JSONDecodeError):
+        return None
+    return data if isinstance(data, dict) else None
+
+
+def is_segment_stale(
+    snapshot: dict[str, Any], segment: str, current_fingerprint: str
+) -> bool:
+    """某段指纹是否变化。段不存在 → True（需采集）。"""
+    segs = snapshot.get("segments") or {}
+    seg = segs.get(segment)
+    if not isinstance(seg, dict):
+        return True
+    return seg.get("fingerprint") != current_fingerprint
+
+
+def refresh_segments(
+    change_dir: Path,
+    snapshot: dict[str, Any],
+    *,
+    project: Path,
+    worktree_root: Path,
+    segment_files: dict[str, list[str]],
+    segments: list[str],
+) -> dict[str, Any]:
+    """只重采指定段；其他段保留原 capturedAt/fingerprint。
+
+    spec §3.6：缓存失效只重采受影响段，不得仅凭缓存跳过代码或验证门禁。
+    返回 refreshed snapshot（不写盘；调用方按需 write_snapshot）。
+    """
+    _ = change_dir  # 预留给未来 write-back
+    refreshed = dict(snapshot)
+    refreshed["project"] = {"root": str(project.resolve())}
+    refreshed["worktree"] = {"root": str(Path(worktree_root).resolve())}
+    refreshed_segments = dict(snapshot.get("segments") or {})
+    for name in segments:
+        files = segment_files.get(name, [])
+        refreshed_segments[name] = capture_file_segment(files)
+    refreshed["segments"] = refreshed_segments
+    refreshed["generatedAt"] = now_iso()
+    return refreshed

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

@@ -2,5 +2,5 @@
   "schemaVersion": 1,
   "overlay": "none",
   "agent": "codebuddy",
-  "coreHash": "3797d93d2cf363a9"
+  "coreHash": "0e63599ac74b7033"
 }

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=3797d93d2cf363a9; overlay=none; agent=codebuddy; do not edit -->
+<!-- generated by harness_deploy.py; core=0e63599ac74b7033; overlay=none; agent=codebuddy; do not edit -->
 # harness-archive — 变更归档
 
 ## Purpose

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

@@ -41,7 +41,7 @@ powershell.exe -NoProfile -ExecutionPolicy Bypass -File "harness-skills/harness-
 
 ## summary-data.json 与 harness_archive.py
 
-默认由 `harness_archive.py finalize`（或 `replay`）生成/校验 `reports/final/summary-data.json`；CLI 不可用时按 `../protocols/report-pipeline-protocol.md` 与 `templates/summary-data-template.json`（schemaVersion 2.2）生成等价数据。必须保留原 final report 维度。必须包含：
+`reports/final/summary-data.json` 只能由 `harness_archive.py finalize`（归档时）或 `replay`（回放时）生成/校验；**禁止 agent 临场手写或拼装等价数据**，也不存在独立的 `report collect`/`report validate` CLI（参见 `../protocols/report-pipeline-protocol.md` 与 `templates/summary-data-template.json` schemaVersion 2.2）。必须保留原 final report 维度。必须包含：
 
 - `businessGoal`：本次变更为了做什么；
 - `stageStatus`：plan/run/test/review/submit/archive；
@@ -68,13 +68,7 @@ powershell.exe -NoProfile -Command "& '<node-path>' 'harness-skills/harness-arch
 
 禁止模型临场手写大段 HTML。确需临时修 HTML，只能修模板，不得让统计数字脱离 `summary-data.json`。
 
-渲染后必须执行：
-
-```powershell
-powershell.exe -NoProfile -Command "npx hunter-harness report validate --change-id '<date-change>' --json"
-```
-
-存在 validate error 时，不得删除原 `.harness/changes/<change>` 目录。
+`validate` 是 `harness_archive.py finalize` 的内嵌同进程步骤（不再作为独立 `report validate` CLI 调用）。finalize 在 validate error 存在时恢复原 `.harness/changes/<change>` 目录并 exit 非 0，绝不归档未通过校验的变更。
 
 ## archive-meta.md 模板
 

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=3797d93d2cf363a9; overlay=none; agent=codebuddy; do not edit -->
+<!-- generated by harness_deploy.py; core=0e63599ac74b7033; overlay=none; agent=codebuddy; do not edit -->
 # harness-codebase-map — 代码库地图
 
 ## Purpose
@@ -67,6 +67,7 @@ description: 分析现有代码库并生成 .harness/codebase/map/
 | 4 | 不管理 CodeGraph |
 | 5 | 敏感信息脱敏 → `sensitive-info-protocol` |
 | 6 | 证据化输出 → `evidence-based-reporting-protocol` |
+| 7 | 扫描复用 `harness_profile` 的 `excludedRoots`（`DEFAULT_EXCLUDED_ROOTS`：node_modules/target/build/dist/cache 等）与 state snapshot 输入，不重复定义排除集；sync 只建议刷新，不自动触发全量 map（design §3.7） |
 
 ## Output Format
 

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=3797d93d2cf363a9; overlay=none; agent=codebuddy; do not edit -->
+<!-- generated by harness_deploy.py; core=0e63599ac74b7033; overlay=none; agent=codebuddy; do not edit -->
 # harness-knowledge-ingest
 
 从 `.harness/archive/**/reports/final/summary-data.json` 抽取项目知识，生成并维护本地 `.harness/knowledge/` 索引。
@@ -34,7 +34,7 @@ description: 从 .harness/archive 归档整理、同步和维护项目知识索
 解决两个问题：
 
 1. **整理知识库内容**：把归档里的 `businessGoal`、`changedFiles`、`maintenanceNotes`、`knownRisks`、`manualActions`、`verification`、`reviewSummary` 抽成知识条目。
-2. **维护知识生命周期**：检查索引是否过期，保留 active 条目；高价值 candidate 可经人工确认提升，也可由 `auto` 首次写入的 `autoPromote` 配置按置信度门槛自动提升。
+2. **维护知识生命周期**：检查索引是否过期，保留 active 条目；高置信 candidate 由 `autoPromote` 自动提升；其余 candidate/conflicted 由 **Agent judge** 闭环裁决，不再默认输出人工待办清单。
 
 ## Outputs
 
@@ -67,11 +67,11 @@ description: 从 .harness/archive 归档整理、同步和维护项目知识索
 
 | 命令 | 用途 |
 |---|---|
-| `auto` | 一键防腐：首建 config、sync --update、suggest-validators、verify、audit；首次自动写 autoPromote 配置并提升高 confidence 条目 |
+| `auto` | 一键防腐：首建 config、sync --update、**默认**写回 validator 建议、verify、audit；随后由 **Agent** 执行 judge 闭环 |
 | `ingest` | 重建/刷新知识索引，抽取 candidate；`--no-incremental` 强制全量重抽取 |
 | `sync` | 检查 index 与 archive/HEAD 一致性；`--update` 自动刷新 |
-| `promote` | candidate→active（人工确认或 autoPromote 触发） |
-| `demote` | active→stale/candidate（人工复核后） |
+| `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 |
@@ -103,29 +103,40 @@ powershell.exe -Command "python '<skill-dir>\scripts\harness_knowledge.py' inges
 - `views/`：Obsidian 友好的浏览视图。
 - `reports/`：本次 ingest 报告。
 
-### Phase 2：同步检查
+### Phase 2：一键 auto（推荐入口）
 
 ```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' auto --project '<project-root>'"
 ```
 
-当 `upToDate=false` 时，应优先运行 `sync --update` 或 `ingest`，再交给 `harness-knowledge-query` 查询。
+`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` 时：
+
+1. `judge export`（或读 maintain 产出的 pending judgements）
+2. Agent 读取 export JSON，按 `reference.md`「Agent judge 启发式」批量写 `reports/judge-decisions-<ts>.json`
+3. `judge apply --apply <decisions.json>`（`knowledge.manualReview=true` 时需用户显式 `--force`）
+4. 向用户输出 **已处理报告**（promoted/dropped/superseded/kept/skipped 计数 + 报告路径）
+
+**禁止**默认输出「请人工确认 N 条 candidate」类五步待办清单。拿不准的 candidate 保持 `candidate` 状态留待下轮，记入 `skippedCandidates` 即可。
 
-### Phase 3：人工确认高价值知识
+裁决体量：`config.judge.maxCandidatesPerRun`（默认 100）；conflicted 优先全量裁决。
 
-如果某条 candidate 已确认仍然有效，并且会反复影响后续需求，可运行 `promote` 将其提升为 active。
+### Phase 4：同步检查（可选）
+
+```powershell
+powershell.exe -Command "python '<skill-dir>\scripts\harness_knowledge.py' sync --project '<project-root>'"
+```
 
-active 条目适合保存：
+当 `upToDate=false` 时，运行 `sync --update` 或重新 `auto`，再交给 `harness-knowledge-query` 查询。
 
-- 需求约束
-- 架构决策
-- API contract
-- 反复踩坑点
-- 测试或发布前置条件
+### Phase 5：显式 promote/demote（例外路径）
 
-不要把一次性实现细节、过期临时方案、未验证结论提升为 active。
+仅在用户点名单条、或 `manualReview=true` 需人工确认时使用 `promote` / `demote`。日常归档后不要逐条人工复核。
 
-### Phase 4：解释同步结果
+### Phase 6：解释同步结果
 
 回复用户或交给后续 skill 前，应说明：
 
@@ -146,8 +157,8 @@ active 条目适合保存：
 
 ## Lifecycle rules
 
-- `candidate`：自动抽取但未人工确认。
-- `active`：人工确认、显式 promote，或配置允许的高置信度 autoPromote 后可用。
+- `candidate`：自动抽取；高置信 + 白名单类型可由 autoPromote 提升；其余由 Agent judge 裁决或保持 candidate。
+- `active`：autoPromote、judge promote，或显式 promote 后可用。
 - `stale`：来源 commit 缺失、来源 commit 后相关文件变化，或当前代码无法证明旧结论仍有效。
 - `superseded`：被后续归档/决策取代。
 - `conflicted`：与另一条 active/candidate 知识冲突。
@@ -169,6 +180,7 @@ active 条目适合保存：
 - write_active_knowledge_after_manual_confirmation
 - write_confidence_scores
 - auto_promote_high_confidence_knowledge_when_configured
+- agent_judge_knowledge_lifecycle
 - write_knowledge_index
 - write_obsidian_views
 
@@ -206,7 +218,9 @@ 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/`）。
-- 下一步建议（`upToDate=false` → `sync --update`；有 candidate → 人工确认后 `promote`，或项目启用 `autoPromote` 后让高置信度长期知识自动提升；查询历史 → `/harness-knowledge-query`）。
+- `lifecycle` 摘要：`validatorsApplied`、`candidateAutoPromoted`、`pendingAgentJudge` 等。
+- **已处理报告**（auto + judge 后）：promoted/dropped/superseded/kept/skipped 计数与 `reports/judge-decisions-*.json`、`judgements-*.json` 路径。
+- 仅当 `upToDate=false` 时建议 `sync --update`；查询历史 → `/harness-knowledge-query`。**禁止**默认列出「请人工确认 N 条 candidate」待办。
 
 ## 渐进披露
 

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

@@ -10,16 +10,36 @@ description: harness-knowledge-ingest 的命令详细示例、config.json 配置
 
 ### Auto maintenance
 
-如果只是想让 skill 自己完成常规知识库防腐，优先跑 `auto`：
+如果只是想让 skill 自己完成常规知识库防腐，优先跑 `auto`，再执行 **Agent judge 闭环**（见下文）：
 
 ```powershell
 powershell.exe -Command "python '<skill-dir>\scripts\harness_knowledge.py' auto --project '<project-root>'"
 ```
 
-`auto` 会按默认维护顺序执行：首建 `config.json`（若缺失）、`sync --update`、只读 `suggest-validators`、`verify`、`audit`。首次发现 `.harness/knowledge/config.json` 不存在时，`auto` 会自动写入启用版 `autoPromote` 配置，并让本次运行立刻按 confidence 规则提升满足门槛的长期知识。默认不会把 validator 建议写回条目；确认要把建议写入后再执行：
+`auto` 会按默认维护顺序执行：首建 `config.json`（若缺失）、`sync --update`、**默认写回** validator 建议、`verify`、`audit`。首次发现 `.harness/knowledge/config.json` 不存在时，会写入启用版 `autoPromote` + `activeLifecycle.autoDemote` + `knowledgeValidation.autoDemoteActive` + `judge.maxCandidatesPerRun` 配置。
+
+关闭 validator 写回：
+
+```powershell
+powershell.exe -Command "python '<skill-dir>\scripts\harness_knowledge.py' auto --project '<project-root>' --no-apply-suggestions"
+```
+
+### Agent judge 闭环（auto 之后）
+
+1. `judge export`（或 maintain 产出的 pending judgements）
+2. Agent 读 export，写 `reports/judge-decisions-<ts>.json`（schema 对齐 `judge apply`）
+3. `judge apply --apply <decisions.json>`
+4. 输出已处理报告，不列人工待办
+
+**启发式**（Agent 侧，非脚本硬编码）：
+
+- **conflicted**：优先 `supersede` 较旧/较弱证据方；对称难判 → `keep-conflict` + reason
+- **candidate**：`decision|api-contract|requirement|pitfall` 且 confidence 高 → `promote`；`implementation|test-evidence` 倾向 `drop` 或保持 candidate
+- 超过 `judge.maxCandidatesPerRun`（默认 100）的低分 candidate：跳过，记入 `skippedCandidates`
 
 ```powershell
-powershell.exe -Command "python '<skill-dir>\scripts\harness_knowledge.py' auto --project '<project-root>' --apply-suggestions --suggest-status candidate"
+powershell.exe -Command "python '<skill-dir>\scripts\harness_knowledge.py' judge --project '<project-root>' --export '<export.json>'"
+powershell.exe -Command "python '<skill-dir>\scripts\harness_knowledge.py' judge --project '<project-root>' --apply '<decisions.json>'"
 ```
 
 常用参数：
@@ -147,20 +167,25 @@ powershell.exe -Command "python '<skill-dir>\scripts\harness_knowledge.py' demot
 
 `demote` 只处理人工确认后的 `active` 条目，可降级到 `stale` 或 `candidate`。降级到 `stale` 时会写入 `manual demotion` stale reason，并在后续 ingest 中保留该人工维护条目。
 
-### Optional active auto-demotion
+### activeLifecycle 与 validator auto-demotion
 
-默认不会自动改写 `active`。如明确希望脚本根据 `Active Review` 自动降级 active，可在 `.harness/knowledge/config.json` 中启用：
+`auto` 首建的 `config.json` **默认已启用** `activeLifecycle.autoDemote` 与 `knowledgeValidation.autoDemoteActive`。已有项目不会强制覆盖。手动启用示例：
 
 ```json
 {
   "activeLifecycle": {
     "autoDemote": true,
     "targetStatus": "stale"
+  },
+  "knowledgeValidation": {
+    "enabled": true,
+    "autoDemoteActive": true,
+    "defaultTargetStatus": "stale"
   }
 }
 ```
 
-启用后，ingest 会把需要复核的 active 自动移动到 `targetStatus`（`stale` 或 `candidate`），记录 `lifecycle.autoDemoted=true` 和 `activeLifecycle auto-demotion` 原因。该能力只应在项目团队确认接受自动降级策略后启用。
+启用后，ingest/verify 会把需复核或 validator 失败的 active 自动降级，并写入 `lifecycle` 审计字段。
 
 ### Optional confidence scoring and autoPromote
 
@@ -199,13 +224,27 @@ confidence 不是“绝对正确率”，只表示当前证据强弱。分数会
     "validatorFailPenalty": 0.5,
     "supersededPenalty": 0.8,
     "conflictPenalty": 0.8
+  },
+  "activeLifecycle": {
+    "autoDemote": true,
+    "targetStatus": "stale"
+  },
+  "knowledgeValidation": {
+    "enabled": true,
+    "autoDemoteActive": true,
+    "defaultTargetStatus": "stale",
+    "allowCommandValidators": false,
+    "commandTimeoutSeconds": 60
+  },
+  "judge": {
+    "maxCandidatesPerRun": 100
   }
 }
 ```
 
 自动提升只处理配置允许的类型，默认排除 stale/conflicted/superseded，且会写入 `lifecycle.autoPromoted=true`、`promotionNote` 和 `promotedAt`。一次性实现细节、测试证据、风险提醒仍不应自动提升为长期事实。
 
-### Optional validator auto-demotion
+### Optional validator auto-demotion（旧文档兼容）
 
 默认不会因为 validator 失败自动改写 `active`。如明确希望确定性 validator 失败时自动降级 active，可在 `.harness/knowledge/config.json` 中启用：
 
@@ -307,3 +346,10 @@ powershell.exe -Command "python '<skill-dir>\scripts\harness_knowledge_mcp.py'"
 - `auto` JSON 输出新增 `config` 摘要：`path`、`created`、`autoPromoteEnabled`、`appliedBy`、`candidateAutoPromoted`。
 - `ingest` 单独命令仍不首建 config；项目策略的自动首建只发生在 `auto` 维护入口。
 - 单测扩展到 35 个，覆盖“已有最新 index 但缺 config 时，auto 首建启用配置并立即提升”的路径。
+
+## v1.14 补充能力（knowledge-auto-close-loop）
+
+- `auto` **默认写回** validator 建议（`--no-apply-suggestions` 可关闭）；JSON 新增 `lifecycle` 摘要。
+- 首建 `config.json` 默认含 `activeLifecycle.autoDemote`、`knowledgeValidation.autoDemoteActive`、`judge.maxCandidatesPerRun=100`。
+- SKILL 工作流：`auto` 后由 **Agent** 执行 `judge export` → 裁决 → `judge apply`；禁止默认输出人工待办清单。
+- `harness-sync` 明确知识闭环主入口为 `/harness-knowledge-ingest auto`。