@hunter-harness/workflow-harness 0.2.13 → 0.2.15

package/harness/bundles/general/codex/harness-run/SKILL.md

@@ -2,7 +2,7 @@
 name: harness-run
 description: 按变更簇执行 TDD 编码循环（RED→GREEN→REFACTOR→编译验证），逐变更簇实现计划中的任务。使用场景：开始编码、实现功能、写代码、TDD 编码
 ---
-<!-- generated by harness_deploy.py; core=c9ed924110321931; overlay=none; agent=codex; do not edit -->
+<!-- generated by harness_deploy.py; core=30342f0368faa261; overlay=none; agent=codex; do not edit -->
 # harness-run — 需求编码
 
 ## Purpose

package/harness/bundles/general/codex/harness-run/reference.md

@@ -52,7 +52,7 @@ requested=true + path missing
 先执行 runtime doctor，并从 `meta/runtime.json` 读取 adapter 的 `path`、`branch` 以及 PowerShell `argvPrefix`；不要依赖裸 `python`/`powershell.exe`，也不要硬编码 Claude 路径。
 
 ```powershell
-& <powershell-argv-prefix> -Command "git worktree add -- '<adapter-worktree-path>' -b '<adapter-branch>'"
+& <powershell-argv-prefix> -Command "git worktree add -b '<adapter-branch>' -- '<adapter-worktree-path>'"
 ```
 
 如果分支已存在：
@@ -61,6 +61,8 @@ requested=true + path missing
 & <powershell-argv-prefix> -Command "git worktree add -- '<adapter-worktree-path>' '<adapter-branch>'"
 ```
 
+> ⚠️ **argv 顺序**（复盘 §5.11）：`-b <branch>` 必须在 `--` 之前；`git worktree add -- <path> -b <branch>` 中 `--` 后的 `-b` 会被 Git 视为位置参数，命令直接失败。等价 argv 数组：`["git","worktree","add","-b",branch,"--",path]`。
+
 验证：
 
 ```powershell

package/harness/bundles/general/codex/harness-submit/SKILL.md

@@ -3,7 +3,7 @@ name: harness-submit
 description: 最终提交封装：验证→中文 commit→提交/推送；worktree 模式含 --no-ff
   合并回主分支。使用场景：提交代码、commit、push、合并分支、merge to main、完成开发
 ---
-<!-- generated by harness_deploy.py; core=c9ed924110321931; overlay=none; agent=codex; do not edit -->
+<!-- generated by harness_deploy.py; core=30342f0368faa261; overlay=none; agent=codex; do not edit -->
 # harness-submit — 最终提交（含 worktree 合并）
 
 ## Purpose
@@ -106,7 +106,7 @@ commit+push / 仅本地 commit / 取消；**不调用 Superpowers 呈现 PR/丢
 
 见 `checklist.md` 与 `../protocols/ledger-protocol.md`、`../protocols/submit-protocol.md`。
 
-test-tracking manifest 是 ignored test 的唯一强制暂存授权：只允许 `harness_test_guard.py stage` 暂存 manifest 中已校验路径，禁止 `git add -f .`、目录级 `git add -f` 或全局修改 `.gitignore`。worktree commit 前须确认 manifest 路径全部进入 cached diff；合并回主分支后、删除 worktree 前须确认这些路径已由目标 commit 跟踪，否则停止清理。
+test-tracking manifest 是 ignored test 的唯一强制暂存授权：只允许 `harness_test_guard.py stage` 暂存 manifest 中已校验且相对 `HEAD` 仍有差异的路径，禁止 `git add -f .`、目录级 `git add -f` 或全局修改 `.gitignore`。worktree commit 前须确认 guard 返回的 `files` 全部进入 cached diff；manifest 中已由 `HEAD` 跟踪且未变化的历史条目允许保留而不进入本次 cached diff。合并回主分支后、删除 worktree 前仍须确认 manifest 路径已由目标 commit 跟踪，否则停止清理。
 
 ### 四、worktree 合并硬规则
 

package/harness/bundles/general/codex/harness-submit/checklist.md

@@ -119,7 +119,7 @@ python <skills-root>/scripts/harness_ledger.py can-reuse `
 
 - [ ] 检查 `.harness/changes/<change-name>/evidence/test-tracking.json` 是否存在
 - [ ] 存在时先执行 `python <skills-root>/scripts/harness_test_guard.py stage --project . --change-dir ".harness/changes/<change-name>" --json`；任一 manifest/path/hash/index 校验失败立即停止
-- [ ] 用 `git diff --cached --name-only` 验证 manifest 中每个精确路径均已暂存，且没有 guard 引入的额外路径
+- [ ] 用 `git diff --cached --name-only` 验证 guard 响应 `files` 中的每个精确路径均已暂存，且没有 guard 引入的额外路径；manifest 中已由 `HEAD` 跟踪且未变化的历史条目无需进入本次 cached diff
 - [ ] 无 manifest 时禁止使用 `git add -f`；有 manifest 时也只允许 guard 内部的 exact force-add，**禁止全局 force-add**、目录级 force-add 和全局修改 `.gitignore`
 
 提交前**强制检查 `.gitignore`** 是否包含 `.harness/`：

package/harness/bundles/general/codex/harness-sync/SKILL.md

@@ -2,7 +2,7 @@
 name: harness-sync
 description: 检查并更新项目AI元数据（CodeGraph索引、harness-codebase-map分析、CLAUDE.md、AGENTS.md、.harness/完整性），确保Claude对代码库的理解与最新代码一致。当用户说'同步/更新索引/刷新元数据/检查一致性'时使用
 ---
-<!-- generated by harness_deploy.py; core=c9ed924110321931; overlay=none; agent=codex; do not edit -->
+<!-- generated by harness_deploy.py; core=30342f0368faa261; overlay=none; agent=codex; do not edit -->
 # harness-sync — 元数据同步
 
 ## Purpose

package/harness/bundles/general/codex/harness-test/SKILL.md

@@ -2,7 +2,7 @@
 name: harness-test
 description: 测试执行：读取场景表，执行单元测试+API接口测试+数据兼容验证，输出测试报告。当用户说'跑测试/验证/跑用例/接口测试/单元测试'时使用
 ---
-<!-- generated by harness_deploy.py; core=c9ed924110321931; overlay=none; agent=codex; do not edit -->
+<!-- generated by harness_deploy.py; core=30342f0368faa261; overlay=none; agent=codex; do not edit -->
 # harness-test — 测试执行
 
 ## Purpose

package/harness/bundles/general/codex/scripts/harness_archive.py

@@ -683,6 +683,34 @@ def check_status(
             else:
                 blockers.append(tier_issue)
 
+    # --- artifact preflight (retro §5.31) ---
+    # Classify artifact events before destructive finalize: informational (OK),
+    # canonicalizable (same-change repo-relative path, warning), or blocking
+    # (cross-change/absolute/escaping path, fail closed).
+    try:
+        preflight = artifact_preflight(change_dir)
+    except Exception as exc:  # noqa: BLE001 — preflight must not crash status
+        preflight = {"ok": False, "items": [], "blocking": [], "error": str(exc)}
+    checks["artifact_preflight"] = preflight
+    for item in preflight.get("blocking") or []:
+        blockers.append({
+            "code": "artifact-path-blocking",
+            "message": (
+                f"artifact event {item.get('eventId', '')} path "
+                f"{item.get('path', '')}: {item.get('reason', 'blocking')}"
+            ),
+        })
+    for item in preflight.get("items") or []:
+        if item.get("category") == "canonicalizable":
+            warnings.append({
+                "code": "artifact-path-canonicalizable",
+                "message": (
+                    f"artifact event {item.get('eventId', '')} path "
+                    f"{item.get('path', '')} is repo-relative; "
+                    f"canonical={item.get('canonicalPath', '')}"
+                ),
+            })
+
     archivable = len(blockers) == 0
     return {
         "ok": True,
@@ -2799,6 +2827,130 @@ def _html_escape(text: str) -> str:
 # ---------------------------------------------------------------------------
 
 
+def validate_report_adequacy(summary: dict[str, Any]) -> dict[str, Any]:
+    """Validate that final summary is factually complete (retro §5.32).
+
+    The archive validator must not return all-green when the summary is
+    factually incomplete. This gate checks independent sources (git facts,
+    typed metrics, stage status) rather than comparing the summary against
+    a lossy projection of itself.
+    """
+    issues: list[dict[str, str]] = []
+
+    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",
+            })
+
+    # Typed metrics missing despite test report artifacts present.
+    verification = summary.get("verification") or {}
+    if isinstance(verification, dict):
+        unit = verification.get("unitTests") or {}
+        api = verification.get("apiTests") or {}
+        artifacts = summary.get("artifacts") or []
+        has_test_report = any(
+            isinstance(a, dict) and "test" in str(a.get("path") or "").lower()
+            for a in artifacts
+        ) if isinstance(artifacts, list) else False
+        unit_pass = int(unit.get("passed") or 0) if isinstance(unit, dict) else 0
+        api_status = str(api.get("status") or "") if isinstance(api, dict) else ""
+        if has_test_report and unit_pass == 0 and api_status in {"", "not_available"}:
+            issues.append({
+                "code": "TYPED_METRICS_MISSING",
+                "severity": "error",
+                "message": "test report artifacts present but unitTests/apiTests typed metrics are empty",
+            })
+
+    # stageStatus contradicts event reducer.
+    stage = summary.get("stageStatus") or {}
+    stage_from_events = summary.get("stageStatusFromEvents") or {}
+    if isinstance(stage, dict) and isinstance(stage_from_events, dict):
+        for phase, status in stage.items():
+            event_status = stage_from_events.get(phase)
+            if event_status is not None and str(status) != str(event_status):
+                issues.append({
+                    "code": "STAGE_STATUS_CONTRADICTION",
+                    "severity": "error",
+                    "message": f"stageStatus.{phase}={status} but event reducer says {event_status}",
+                })
+
+    return {"ok": not issues, "issues": issues}
+
+
+def artifact_preflight(change_dir: Path) -> dict[str, Any]:
+    """Classify artifact events before destructive finalize (retro §5.31).
+
+    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).
+    """
+    change_dir = change_dir.resolve()
+    events_p = change_dir / "events.ndjson"
+    items: list[dict[str, Any]] = []
+    blocking: list[dict[str, Any]] = []
+    if not events_p.is_file():
+        return {"ok": True, "items": [], "blocking": []}
+    change_id = change_dir.name
+    for line in events_p.read_text(encoding="utf-8").splitlines():
+        try:
+            event = json.loads(line)
+        except json.JSONDecodeError:
+            continue
+        if not isinstance(event, dict) or event.get("type") != "artifact":
+            continue
+        path = str(event.get("path") or "").strip()
+        kind = str(event.get("kind") or "").strip()
+        event_id = str(event.get("id") or "")
+        if not path:
+            items.append({
+                "eventId": event_id,
+                "category": "informational",
+                "kind": kind or "informational",
+                "note": str(event.get("note") or "")[:80],
+            })
+            continue
+        # Check for escaping/cross-change paths.
+        parts = path.replace("\\", "/").split("/")
+        if ".." in parts or path.startswith("/") or re.match(r"^[A-Za-z]:", path):
+            item = {
+                "eventId": event_id,
+                "category": "blocking",
+                "path": path,
+                "reason": "absolute or escaping path",
+            }
+            items.append(item)
+            blocking.append(item)
+            continue
+        # Same-change repo-relative path: canonicalizable.
+        prefix = f".harness/changes/{change_id}/"
+        if path.startswith(prefix):
+            canonical = path[len(prefix):]
+            items.append({
+                "eventId": event_id,
+                "category": "canonicalizable",
+                "path": path,
+                "canonicalPath": canonical,
+                "correction": f"append correction --target-event-id {event_id} --target-field path --new-value-json \"{canonical}\"",
+            })
+            continue
+        # Change-relative path: OK.
+        items.append({
+            "eventId": event_id,
+            "category": "file-backed",
+            "path": path,
+            "exists": (change_dir / path).is_file(),
+        })
+    return {"ok": not blocking, "items": items, "blocking": blocking}
+
+
 def run_knowledge_poststeps(project_root: Path) -> dict[str, Any]:
     results: dict[str, Any] = {"ran": False, "steps": [], "warnings": []}
     if not KNOWLEDGE_SCRIPT.is_file():
@@ -3107,6 +3259,36 @@ def cmd_finalize(
             note="review missing on full tier (allowed by user)",
         )
 
+    # --- 2c. artifact preflight (retro §5.31) ---
+    # Classify artifact events before freeze: blocking paths must fail closed
+    # before the staged operation commits a phase.end.
+    try:
+        preflight = artifact_preflight(work_dir)
+    except Exception as exc:  # noqa: BLE001 — preflight must not crash finalize
+        preflight = {"ok": False, "items": [], "blocking": [], "error": str(exc)}
+    payload["steps"]["artifact_preflight"] = {
+        "ok": bool(preflight.get("ok")),
+        "blockingCount": len(preflight.get("blocking") or []),
+        "itemsCount": len(preflight.get("items") or []),
+    }
+    if preflight.get("blocking"):
+        payload["error"] = (
+            f"artifact preflight blocking: "
+            f"{len(preflight['blocking'])} path(s) cannot be archived"
+        )
+        payload["issues"] = [
+            {
+                "code": "ARTIFACT_PATH_BLOCKING",
+                "severity": "error",
+                "message": f"{item.get('path', '')}: {item.get('reason', 'blocking')}",
+            }
+            for item in preflight["blocking"]
+        ]
+        _restore_finalize_failure()
+        payload["warnings"] = warnings
+        payload["ok"] = False
+        return 1, payload
+
     # --- 3. candidate phase.end + freeze cutoff (RET-19 freeze-first) ---
     # This terminal exists only inside the isolated operation staging tree. It
     # becomes authoritative atomically at publish; validation failure discards
@@ -3169,6 +3351,28 @@ def cmd_finalize(
         payload["ok"] = False
         return 1, payload
 
+    # --- 5b. report adequacy (retro §5.32) ---
+    # Validate that the summary is factually complete: no diff=0 with non-empty
+    # commit, no missing typed metrics despite test reports, no stageStatus
+    # contradictions. Fail closed rather than archiving an incomplete summary.
+    adequacy_result = validate_report_adequacy(summary)
+    payload["steps"]["report_adequacy"] = adequacy_result
+    summary.setdefault("reportPipeline", {})["reportAdequacy"] = {
+        "ok": bool(adequacy_result.get("ok")),
+        "issues": adequacy_result.get("issues") or [],
+    }
+    try:
+        write_json(summary_path, summary)
+    except OSError as exc:
+        warnings.append(f"could not write reportAdequacy: {exc}")
+    if not adequacy_result.get("ok"):
+        payload["issues"] = adequacy_result.get("issues") or []
+        payload["error"] = "report adequacy failed; staged operation discarded"
+        _restore_finalize_failure()
+        payload["warnings"] = warnings
+        payload["ok"] = False
+        return 1, payload
+
     # --- 6. render (Node, else Python fallback) ---
     render_result = render_final_summary(work_dir, summary_path)
     payload["steps"]["render"] = render_result