@hunter-harness/workflow-harness 0.2.18 → 0.2.19

package/harness/bundles/general/claude-code/.harness-build.json

@@ -2,5 +2,5 @@
   "schemaVersion": 1,
   "overlay": "none",
   "agent": "claude-code",
-  "coreHash": "d5b51ad56d4d4535"
+  "coreHash": "71f31413c45ca599"
 }

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

@@ -20,7 +20,7 @@ disallowed-tools:
   - Bash(awk *)
   - Bash(curl *)
 ---
-<!-- generated by harness_deploy.py; core=d5b51ad56d4d4535; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=71f31413c45ca599; overlay=none; agent=claude-code; do not edit -->
 # harness-archive — 变更归档
 
 ## Purpose
@@ -50,6 +50,12 @@ disallowed-tools:
 - commit 已 push（`git log @{u}..HEAD` 输出为空）
 - **最终 hash 来源**：worktree 模式（`meta/worktree.json` requested=true）下读 ledger 的 `mergeFinalHash`（由 `/harness-submit` 合并段写入）；主目录模式读 submit 的 `final pushed hash`。当前 `git rev-parse HEAD` 须一致
 - test 报告存在或标记"跳过"；review 报告存在或标记"未运行 review"（review 不阻塞归档）
+- **最小必备集（H-4 / `harness_archive.py status` blockers）**：
+  - `plans/*-plan.md`
+  - 非空 `events.ndjson`
+  - `evidence/verification-ledger.json`
+  - 至少一个 test 或 review 报告/证据
+  - 缺失任一项 → `archivable=false`；可从 `.harness/cache/change-snapshots/<change>/` 恢复正式层后再重试
 
 ## Inputs
 

package/harness/bundles/general/claude-code/harness-archive/checklist.md

@@ -20,6 +20,12 @@ description: harness-archive 的归档前检查项和归档后验证项。仅在
 
 - [ ] 未在调用 finalize 前手工追加 archive 阶段边界
 - [ ] 只有一个未归档变更目录（多个时终止或让用户选择）
+- [ ] **最小必备集 blockers**（`harness_archive.py status`）：
+  - [ ] `plans/*-plan.md` 存在
+  - [ ] `events.ndjson` 存在且非空
+  - [ ] `evidence/verification-ledger.json` 存在
+  - [ ] 至少一个 test 或 review 报告/证据
+  - [ ] 若缺失：优先从 `.harness/cache/change-snapshots/<change>/` 恢复，禁止空壳归档
 - [ ] 变更目录下有 plans/ 子目录（至少有计划文件）
 - [ ] `events.ndjson` 存在；执行日志允许由 finalize 从事件流重新渲染（旧 archive 才兼容根目录 `execution-log.md`）
 - [ ] 准备生成 `archive-manifest-before.json`（path/size/sha256）

package/harness/bundles/general/claude-code/harness-codebase-map/SKILL.md

@@ -20,7 +20,7 @@ disallowed-tools:
   - Bash(awk *)
   - Bash(curl *)
 ---
-<!-- generated by harness_deploy.py; core=d5b51ad56d4d4535; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=71f31413c45ca599; overlay=none; agent=claude-code; do not edit -->
 # harness-codebase-map — 代码库地图
 
 ## Purpose

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

@@ -20,7 +20,7 @@ disallowed-tools:
   - Bash(awk *)
   - Bash(curl *)
 ---
-<!-- generated by harness_deploy.py; core=d5b51ad56d4d4535; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=71f31413c45ca599; overlay=none; agent=claude-code; do not edit -->
 # harness-knowledge-ingest
 
 从 `.harness/archive/**/reports/final/summary-data.json` 抽取项目知识，生成并维护本地 `.harness/knowledge/` 索引。

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=d5b51ad56d4d4535; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=71f31413c45ca599; 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=d5b51ad56d4d4535; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=71f31413c45ca599; 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=d5b51ad56d4d4535; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=71f31413c45ca599; 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=d5b51ad56d4d4535; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=71f31413c45ca599; 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=d5b51ad56d4d4535; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=71f31413c45ca599; overlay=none; agent=claude-code; do not edit -->
 # harness-submit — 最终提交（含 worktree 合并）
 
 ## Purpose
@@ -96,12 +96,17 @@ M3. **merge** — `--no-ff` 合并 feature 分支；merge diff 出现其他 Chan
 M4. **verify** — 在 integration worktree 内执行组合态验证；他人提交引入或 ledger 不可复用时必跑
 M5. **push** — 仅在验证身份与远端基线仍匹配时 push；远端漂移 → `TARGET_MOVED` 结构化失败，不继续
 M6. **cleanup** — `git worktree remove --force` 精确路径 + 临时分支 + （push 成功后）保护 ref；释放 integration lock；失败保留 journal 与诊断证据；更新 `worktree.json`（`created=false` + removedAt）
+M6.5. **formal snapshot** — mergeFinalHash 写入后调用 `harness_paths.snapshot_change_formal_layer(projectRoot, changeId)`，备份到主仓 `.harness/cache/change-snapshots/<change>/`（不得写在 feature worktree 内）
 M7. **ledger + 收尾** — 经 `harness_ledger.py record` 写入 `mergeFinalHash`（= journal `pushedHead`）；**`harness_gate.py close --phase merge`**（禁止手工 phase.end）；提示 `/harness-archive`
 
-> Ledger v3（v2 契约 / split-v1 布局起）：`record` 强制顶层身份（`schemaVersion=3/repositoryId/baseCommit/currentHead/diffHash/ownershipHash`，缺失非零退出、不写账本）与 typed metrics；legacy 契约行为不变。详见 `../protocols/ledger-protocol.md` 第十节。
+> Ledger v3（v2 契约 / split-v1 布局起）：`record` 强制顶层身份（`schemaVersion=3/repositoryId/baseCommit/currentHead/diffHash/ownershipHash`，缺失非零退出、`LEDGER_IDENTITY_INVALID`，不写账本）与 typed metrics；legacy 契约行为不变。详见 `../protocols/ledger-protocol.md` 第十节。
 
 正常路径**禁止创建、应用或删除仓库级 stash**。中断恢复：`harness_integration.py status` 读 journal，`recover` 从首个未完成步骤续跑；protection refs 只在 push 成功后的 cleanup 删除。
 
+**失败 txn 回收（abandon）**：verify/push 未成功且 remote 不含 mergeCommit 时，运行 `harness_integration.py abandon --change … --run-id …`：清理 integrationRoot / temp branch / protection refs / lock；**绝不删除 feature worktree**。push 已成功或 remote 已含 merge → `ABANDON_REFUSED`，改走 cleanup。
+
+**清 feature worktree 迁根硬门槛（H-1/H-2）**：删除 feature worktree 前，若 Agent root / cwd 落在待删路径内，必须先 `move_agent_to_root(projectRoot)`（目标为主仓已存在的 `main`/`master`；**禁止**为迁根去 fetch 已删除的 feature 分支）。迁根失败 → **拒绝删除**。清理前调用 `harness_paths.assert_cleanup_safe(cleanupRoot, stateRoots, archiveRoots)`；state/archive（含 junction/symlink 解析后）落在 cleanup 内 → `CLEANUP_TOPOLOGY_REFUSED`。
+
 ## P0 执行可信度规则
 
 - 命令结果不得靠猜测；普通 Bash 被拒 → 立即改用等价 PowerShell 重试一次
@@ -133,6 +138,10 @@ test-tracking manifest 是 ignored test 的唯一强制暂存授权：只允许
 - **`git merge --no-ff` 固定**；禁止 fast-forward
 - **冲突不自动解** → 停下 → 用户手动解 → 确认后继续
 - **`mergeFinalHash`** = 主分支 push 后 HEAD；archive 优先读此字段
+- **迁根后再删 feature WT**：Agent 仍在待删 root 内则拒绝删除；目标分支已删时切主仓 `main`/`master`，禁止强行 fetch
+- **snapshot 后再清**：正式层已写入 `.harness/cache/change-snapshots/<change>/`
+- **拓扑安全**：`assert_cleanup_safe` 拒绝 state/archive ⊆ cleanup（含 junction）
+- **abandon ≠ cleanup**：仅失败 txn；永不删 feature worktree
 
 ### 五、Shell 安全 / 敏感信息 / 证据化
 

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

@@ -386,11 +386,26 @@ python harness/scripts/harness_integration.py cleanup --change <change-name> --r
 - 失败保留 journal 与诊断证据，状态 🟡WARN，不得宣称清理完成
 - 若存在 test-tracking manifest，确认其路径已由合并后的目标分支跟踪（`git ls-files --error-unmatch -- <exact-path>`），缺失即停止
 
+**失败 txn 改走 abandon（勿强行 cleanup）**：
+
+```powershell
+python harness/scripts/harness_integration.py abandon --change <change-name> --run-id <run-id> --feature-branch harness/<change-name> --target-branch <主分支> --temp-root <task-temp>
+```
+
+仅当 push ≠ DONE 且 remote 不含 mergeCommit；清理 integration 产物后可换新 run-id 重开。push 成功 → `ABANDON_REFUSED`。
+
 更新 `meta/worktree.json`：`created=false` + `removedAt`/`removedBy`/`removalNote`。
 
+**删除 feature worktree 前（硬门槛）**：
+
+1. 若 Agent root / cwd 落在待删 worktree → 先 `move_agent_to_root(<projectRoot>)`；目标为主仓，feature 分支已删则切 `main`/`master`，禁止 fetch 已不存在分支
+2. 迁根失败 → **停止删除**
+3. `assert_cleanup_safe(cleanupRoot, [.harness/changes/<id>, .harness/state/...], [.harness/archive])`；`CLEANUP_TOPOLOGY_REFUSED` → 停止
+4. mergeFinalHash 已写后先 `snapshot_change_formal_layer`，再清 feature WT
+
 ### 步骤 M7：更新 ledger + 收尾
 
-ledger 顶层写入 `"mergeFinalHash": "<journal pushedHead>"`；经 `harness_gate.py close --phase merge` 关闭（禁止手工 phase.end）。
+ledger 顶层写入 `"mergeFinalHash": "<journal pushedHead>"`；经 `harness_gate.py close --phase merge` 关闭（禁止手工 phase.end）。正式层快照确认存在于 `.harness/cache/change-snapshots/<change-name>/`。
 
 ```markdown
 ## 合并完成 — <change-name>
@@ -399,6 +414,7 @@ ledger 顶层写入 `"mergeFinalHash": "<journal pushedHead>"`；经 `harness_ga
 - 主分支 push: ✅（<old>..<new> → origin/<主分支>）
 - mergeFinalHash: `<merge-final-hash>`
 - 验证策略: 🔁REUSED / 🔄已重跑
-- worktree: 已清理
+- snapshot: `.harness/cache/change-snapshots/<change-name>/`
+- worktree: 已清理（迁根后）
 - 下一步: `/harness-archive`
 ```

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=d5b51ad56d4d4535; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=71f31413c45ca599; overlay=none; agent=claude-code; do not edit -->
 # harness-sync — 元数据同步
 
 ## Purpose

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=d5b51ad56d4d4535; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=71f31413c45ca599; overlay=none; agent=claude-code; do not edit -->
 # harness-test — 测试执行
 
 ## Purpose

package/harness/bundles/general/claude-code/protocols/report-pipeline-protocol.md

@@ -43,6 +43,8 @@ python <skills-root>/scripts/harness_events.py append --change-dir ".harness/cha
 
 `append` 写入契约（Task 4 §6.1）：普通 append = 加锁 -> 追加一行 -> fsync -> 解锁，**不 load 历史、不渲染**（O(1)，跨进程锁 `events.ndjson.lock`，UUID 用完整 `uuid4().hex`）；仅 `--type phase.end` append 成功后渲染一次 `logs/execution-log.md`；显式 `harness_events.py render` 随时从完整 events 重建；`harness_archive.py finalize` 在 collect 前强制 render 一次。人类可读摘要（触发指令、降级原因、阶段结论）写入事件的 `note` 字段；阶段开始/结束、命令、验证、artifact、问题、决策各写对应 `type` 事件。旧 archive 缺少 events 可回放兼容；新变更不得以 execution-log 已存在为理由跳过 events。
 
+**artifact 硬门禁（H-8）**：`--type artifact` **必须**带非空 `--path`（change 相对路径）。知识探索/预览类说明改用 `--type issue` 或 `--type decision`，禁止再用 `--kind informational` 伪装无 path 的 artifact。
+
 基础事件结构（schema_version 3；兼容读取 v1/v2）：
 
 ```json

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

@@ -520,6 +520,41 @@ def check_status(
             }
         )
 
+    # --- H-4 formal-layer minimum set ---
+    plans_dir = change_dir / "plans"
+    plan_files = (
+        sorted(plans_dir.glob("*-plan.md")) if plans_dir.is_dir() else []
+    )
+    checks["plan_files"] = [str(p.relative_to(change_dir)) for p in plan_files]
+    if not plan_files:
+        blockers.append(
+            {
+                "code": "missing-plan",
+                "message": "plans/*-plan.md is required before archive",
+            }
+        )
+
+    events_path = change_dir / "events.ndjson"
+    events_present = events_path.is_file() and events_path.stat().st_size > 0
+    checks["events_ndjson"] = events_present
+    if not events_present:
+        blockers.append(
+            {
+                "code": "missing-events",
+                "message": "events.ndjson is required and must be non-empty",
+            }
+        )
+
+    ledger = load_ledger(change_dir)
+    checks["verification_ledger"] = ledger is not None
+    if ledger is None:
+        blockers.append(
+            {
+                "code": "missing-verification-ledger",
+                "message": "evidence/verification-ledger.json is required before archive",
+            }
+        )
+
     # --- commit pushed ---
     code, out, err = git_run(project, "rev-parse", "--is-inside-work-tree")
     if code != 0:
@@ -559,7 +594,8 @@ def check_status(
 
     expected_hash: str | None = None
     hash_source: str | None = None
-    ledger = load_ledger(change_dir)
+    if ledger is None:
+        ledger = load_ledger(change_dir)
     if worktree_requested(change_dir) and ledger:
         merge_hash = ledger.get("mergeFinalHash") or (
             ledger.get("merge") or {}
@@ -625,13 +661,25 @@ def check_status(
     # --- test / review reports ---
     test_reports = find_test_reports(change_dir)
     review_reports = find_review_reports(change_dir)
-    events_path = change_dir / "events.ndjson"
     events = he.load_events(events_path) if events_path.is_file() else []
     review_ran = review_evidence_present(change_dir, events)
 
     checks["test_reports"] = [str(p.relative_to(change_dir)) for p in test_reports]
     checks["review_reports"] = [str(p.relative_to(change_dir)) for p in review_reports]
 
+    # H-4 min blockers are plan/events/ledger only. Missing test/review evidence
+    # remains a warning so archive-before-review stays possible (advisory).
+    if not test_reports and not review_reports and not review_ran:
+        warnings.append(
+            {
+                "code": "missing-test-or-review-report",
+                "message": (
+                    "no test report or review evidence yet; prefer completing "
+                    "test/review before archive (not a hard blocker)"
+                ),
+            }
+        )
+
     if test_reports:
         checks["test_report_status"] = "present"
     else:
@@ -842,15 +890,18 @@ def _ledger_unit_tests(ledger: dict[str, Any] | None) -> dict[str, Any]:
     elif str(unit.get("reused") or "").lower() in {"true", "1"} or "REUSED" in status:
         source = "committed"
 
-    if pass_rate is None and run > 0:
+    if pass_rate is None:
         passed = (
             passed_count
             if passed_count is not None
-            else max(run - failures - errors - skipped, 0)
+            else max(int(run or 0) - int(failures or 0) - int(errors or 0) - int(skipped or 0), 0)
         )
-        pass_rate = f"{passed / run:.0%}"
-    elif pass_rate is None:
-        pass_rate = NOT_AVAILABLE
+        # H-13: passRate denominator excludes skipped.
+        denom = int(passed) + int(failures or 0) + int(errors or 0)
+        if denom > 0:
+            pass_rate = f"{passed / denom:.0%}"
+        else:
+            pass_rate = NOT_AVAILABLE
 
     result = {
         "run": int(run or 0),
@@ -1332,7 +1383,19 @@ def _stage_status_from_sources(
         elif raw in {"SKIP", "SKIPPED"}:
             raw = "USER_SKIPPED"
         status[phase] = raw
-    # Issues in events can downgrade
+    # Issues in events can downgrade. H-14: informational / hygiene / agent-preflight
+    # notes must not downgrade an already-OK phase.end.
+    _informational_markers = (
+        "[archive-hygiene]",
+        "informational",
+        "custom_agents_unsupported",
+        "definition_not_found_host_capable",
+        "知识查询",
+        "knowledge query",
+        "harness-explorer",
+        "harness-evaluator",
+        "委派",
+    )
     for e in he.current_issues(events):
         sev = str(e.get("severity") or "").lower()
         issue_text = " ".join(str(e.get(key) or "") for key in ("message", "note", "code")).lower()
@@ -1341,6 +1404,10 @@ def _stage_status_from_sources(
                 sev = "error"
             elif any(token in issue_text for token in ("warn", "skip", "风险", "警告")):
                 sev = "warn"
+        if sev in {"warn", "warning"} and any(m in issue_text for m in _informational_markers):
+            continue
+        if sev in {"", "info", "note", "informational"}:
+            continue
         phase = str(e.get("phase") or "").lower()
         if phase in status and sev in {"error", "fail", "failed", "critical"}:
             status[phase] = "FAIL"
@@ -1651,6 +1718,51 @@ def _review_summary(
     return base
 
 
+def _resolve_base_commit(
+    ledger: dict[str, Any] | None,
+    change_dir: Path,
+    project: Path,
+    final: str | None,
+) -> str:
+    """Resolve baseCommit: ledger → latest phase-context → merge first parent → merge-base."""
+    if ledger:
+        base = str(ledger.get("baseCommit") or "").strip()
+        if base and base != NOT_AVAILABLE:
+            return base
+
+    ctx_dir = change_dir / "runtime" / "phase-context"
+    if ctx_dir.is_dir():
+        candidates = sorted(
+            (p for p in ctx_dir.glob("*.json") if p.is_file()),
+            key=lambda p: p.stat().st_mtime,
+            reverse=True,
+        )
+        for path in candidates:
+            try:
+                payload = read_json(path)
+            except (OSError, json.JSONDecodeError, TypeError):
+                continue
+            if not isinstance(payload, dict):
+                continue
+            base = str(payload.get("baseCommit") or "").strip()
+            if base and base != NOT_AVAILABLE:
+                return base
+
+    final_commit = str(final or "").strip()
+    if final_commit and final_commit != NOT_AVAILABLE:
+        code, parents_line, _ = git_run(
+            project, "rev-list", "--parents", "-n", "1", final_commit
+        )
+        if code == 0 and parents_line:
+            parts = parents_line.split()
+            if len(parts) >= 2:
+                return parts[1]
+        code, merge_base, _ = git_run(project, "merge-base", final_commit, "HEAD")
+        if code == 0 and merge_base and merge_base != final_commit:
+            return merge_base
+    return ""
+
+
 def _final_commit_from_sources(
     ledger: dict[str, Any] | None,
     events: list[dict[str, Any]],
@@ -1864,12 +1976,21 @@ def collect_summary_data(
         data["finalCommit"] = final_commit or (NOT_AVAILABLE if for_replay else "")
 
     if not data.get("baseCommit") or str(data.get("baseCommit")).startswith("<"):
-        if ledger and ledger.get("baseCommit"):
-            data["baseCommit"] = ledger["baseCommit"]
-        elif existing and existing.get("baseCommit"):
+        if for_replay and existing and existing.get("baseCommit"):
             data["baseCommit"] = existing["baseCommit"]
         else:
-            data["baseCommit"] = NOT_AVAILABLE if for_replay else ""
+            resolved_base = _resolve_base_commit(
+                ledger,
+                change_dir,
+                project,
+                str(data.get("finalCommit") or "") or None,
+            )
+            if resolved_base:
+                data["baseCommit"] = resolved_base
+            elif existing and existing.get("baseCommit"):
+                data["baseCommit"] = existing["baseCommit"]
+            else:
+                data["baseCommit"] = NOT_AVAILABLE if for_replay else ""
 
     if not data.get("finalCommitBranch") or str(data.get("finalCommitBranch")).startswith("<"):
         code, branch, _ = git_run(project, "rev-parse", "--abbrev-ref", "--symbolic-full-name", "@{u}")
@@ -2002,6 +2123,16 @@ def collect_summary_data(
             }
             data["changedFiles"] = []
 
+    # H-11: surface identity + diff facts for adequacy (top-level + gitFacts).
+    diff_for_facts = data.get("diffStat") if isinstance(data.get("diffStat"), dict) else {}
+    data["gitFacts"] = {
+        "baseCommit": data.get("baseCommit") or "",
+        "finalCommit": data.get("finalCommit") or "",
+        "filesChanged": int(diff_for_facts.get("filesChanged") or 0),
+        "insertions": int(diff_for_facts.get("insertions") or 0),
+        "deletions": int(diff_for_facts.get("deletions") or 0),
+    }
+
     data.setdefault(
         "ownershipDiff",
         {
@@ -2837,18 +2968,52 @@ def validate_report_adequacy(summary: dict[str, Any]) -> dict[str, Any]:
     """
     issues: list[dict[str, str]] = []
 
+    # H-12: prefer top-level baseCommit + diffStat; gitFacts is a mirror.
+    base = str(summary.get("baseCommit") or "").strip()
+    final = str(summary.get("finalCommit") or "").strip()
+    merge_final = str(summary.get("mergeFinalHash") or "").strip()
+    diff_stat = summary.get("diffStat") if isinstance(summary.get("diffStat"), dict) else {}
+    files_changed = int(diff_stat.get("filesChanged") or 0)
+
     git_facts = summary.get("gitFacts") or {}
     if isinstance(git_facts, dict):
-        base = str(git_facts.get("baseCommit") or "").strip()
-        final = str(git_facts.get("finalCommit") or "").strip()
-        files_changed = int(git_facts.get("filesChanged") or 0)
-        # base != final but diff=0 → factually incomplete.
-        if base and final and base != final and files_changed == 0:
-            issues.append({
-                "code": "DIFF_ZERO_WITH_NONEMPTY_COMMIT",
-                "severity": "error",
-                "message": f"final commit {final} differs from base {base} but filesChanged=0",
-            })
+        if not base or base == NOT_AVAILABLE:
+            base = str(git_facts.get("baseCommit") or "").strip() or base
+        if not final or final == NOT_AVAILABLE:
+            final = str(git_facts.get("finalCommit") or "").strip() or final
+        if "filesChanged" in git_facts and files_changed == 0:
+            try:
+                files_changed = int(git_facts.get("filesChanged") or 0)
+            except (TypeError, ValueError):
+                files_changed = 0
+
+    base_missing = not base or base == NOT_AVAILABLE
+    final_present = bool(
+        (final and final != NOT_AVAILABLE) or (merge_final and merge_final != NOT_AVAILABLE)
+    )
+    if final_present and base_missing:
+        issues.append({
+            "code": "IDENTITY_BASE_MISSING",
+            "severity": "error",
+            "message": (
+                "final/merge identity present but baseCommit is empty; "
+                "refuse CONDITIONAL_OK+ without a resolved base"
+            ),
+        })
+
+    if (
+        base
+        and final
+        and base != NOT_AVAILABLE
+        and final != NOT_AVAILABLE
+        and base != final
+        and files_changed == 0
+    ):
+        issues.append({
+            "code": "DIFF_ZERO_WITH_NONEMPTY_COMMIT",
+            "severity": "error",
+            "message": f"final commit {final} differs from base {base} but filesChanged=0",
+        })
 
     # Typed metrics missing despite test report artifacts present.
     verification = summary.get("verification") or {}
@@ -2886,11 +3051,11 @@ def validate_report_adequacy(summary: dict[str, Any]) -> dict[str, Any]:
 
 
 def artifact_preflight(change_dir: Path) -> dict[str, Any]:
-    """Classify artifact events before destructive finalize (retro §5.31).
+    """Classify artifact events before destructive finalize (retro §5.31 / H-8).
 
-    Returns per-artifact classification: informational (no path, OK),
-    canonicalizable (same-change repo-relative path, auto-normalize), or
-    blocking (cross-change/absolute/escaping path, fail closed).
+    Returns per-artifact classification: blocking (missing / escaping /
+    cross-change path), canonicalizable (same-change repo-relative path),
+    or file-backed (change-relative path). Pathless legacy rows fail closed.
     """
     change_dir = change_dir.resolve()
     events_p = change_dir / "events.ndjson"
@@ -2910,12 +3075,16 @@ def artifact_preflight(change_dir: Path) -> dict[str, Any]:
         kind = str(event.get("kind") or "").strip()
         event_id = str(event.get("id") or "")
         if not path:
-            items.append({
+            item = {
                 "eventId": event_id,
-                "category": "informational",
-                "kind": kind or "informational",
+                "category": "blocking",
+                "path": "",
+                "kind": kind or "",
+                "reason": "artifact path missing",
                 "note": str(event.get("note") or "")[:80],
-            })
+            }
+            items.append(item)
+            blocking.append(item)
             continue
         # Check for escaping/cross-change paths.
         parts = path.replace("\\", "/").split("/")

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

@@ -679,29 +679,16 @@ def validate_append_event(args: argparse.Namespace) -> tuple[str, str] | None:
                 "CORRECTION_VALUE_INVALID_JSON",
                 f"CORRECTION_VALUE_INVALID_JSON: {exc}",
             )
-    # Retro §5.31: artifact events must distinguish file-backed from
-    # informational. file-backed requires a change-relative path; informational
-    # (preview/summary) must not masquerade as a file artifact. Legacy kind
-    # values (ledger, report, etc.) are treated as file-backed aliases.
+    # Retro 2026-07-21 H-8: artifact events always require a non-empty path.
+    # Knowledge/exploration notes must use issue/decision, not pathless artifacts.
     if event_type == "artifact":
-        kind = str(getattr(args, "kind", "") or "").strip()
         path = str(getattr(args, "path", "") or "").strip()
-        is_informational = kind == "informational"
-        if kind == "file-backed" and not path:
-            return (
-                "ARTIFACT_PATH_REQUIRED",
-                "ARTIFACT_PATH_REQUIRED: file-backed artifact requires --path",
-            )
-        # If kind is explicitly informational, path is optional. If kind is
-        # absent and path is absent, reject (can't infer file-backed without path).
-        if not kind and not path:
+        if not path:
             return (
                 "ARTIFACT_PATH_REQUIRED",
-                "ARTIFACT_PATH_REQUIRED: artifact without --kind or --path is ambiguous; "
-                "use --kind informational for previews or --path for file artifacts",
+                "ARTIFACT_PATH_REQUIRED: artifact requires --path "
+                "(use issue/decision for informational notes)",
             )
-        # If no kind is provided, infer from path presence: a path implies
-        # file-backed, absence implies informational (legacy compatibility).
     return None