@hunter-harness/workflow-harness 0.2.14 → 0.2.15

package/harness/bundles/general/codebuddy/scripts/harness_preflight.py

@@ -367,10 +367,41 @@ def _resolve_agents_root(skills_root: Path, agents_root: Path | None) -> tuple[P
     if skills_root.name == "skills" and skills_root.parent.name in (".claude", ".codebuddy"):
         return (skills_root.parent / "agents").resolve(), None
     if skills_root.name == "skills" and skills_root.parent.name in (".agents", ".cursor"):
-        return None, "CUSTOM_AGENTS_UNSUPPORTED"
+        # These adapters (Codex/Cursor) may provide agent roles via host
+        # capability manifest rather than local .md files. Return None without
+        # a hard error; the caller checks runtime.json for host capabilities.
+        return None, None
     return (skills_root / "agents").resolve(), None
 
 
+def _read_host_capabilities(skills_root: Path) -> set[str]:
+    """Read agent capabilities declared by the host adapter (retro §5.3).
+
+    Adapter installs may declare available agent roles in
+    `meta/runtime.json` under `agentCapabilities` (list of role names).
+    Returns an empty set if the file or field is absent.
+    """
+    # runtime.json lives in the change's meta/ dir, but agent capabilities are
+    # project-level. Check the adapter's runtime.json at the project root.
+    candidates = [
+        skills_root.parent / "runtime.json",
+        skills_root / "runtime.json",
+    ]
+    for path in candidates:
+        if not path.is_file():
+            continue
+        try:
+            data = json.loads(path.read_text(encoding="utf-8-sig"))
+        except (OSError, json.JSONDecodeError):
+            continue
+        if not isinstance(data, dict):
+            continue
+        caps = data.get("agentCapabilities")
+        if isinstance(caps, list):
+            return {str(c) for c in caps if isinstance(c, str)}
+    return set()
+
+
 def cmd_check_agents(
     skills_root: Path,
     agent: str,
@@ -388,98 +419,136 @@ def cmd_check_agents(
             "reason": "agent name is empty",
         }
 
-    resolved_agents_root, capability_error = _resolve_agents_root(skills_root, agents_root)
-    if capability_error is not None:
-        return {
-            "ok": True,
-            "action": "check-agents",
-            "agent": agent_name,
-            "usable": False,
-            "definitionValid": False,
-            "runtimeSupported": False,
-            "reasonCode": capability_error,
-            "reason": "current adapter runtime does not support custom agent definitions; use main-session fallback",
-        }
-
-    assert resolved_agents_root is not None
-    # Accept bare name or with .md
-    filename = agent_name if agent_name.endswith(".md") else f"{agent_name}.md"
-    agent_path = resolved_agents_root / filename
-
-    if not agent_path.is_file():
+    resolved_agents_root, _ = _resolve_agents_root(skills_root, agents_root)
+    host_capabilities = _read_host_capabilities(skills_root)
+    host_callable = agent_name in host_capabilities
+
+    # Three independent fields (retro §5.3):
+    # - definitionPresent: local .md file exists
+    # - hostCallable: host adapter declares this agent role
+    # - toolContractValid: tools declaration is valid (non-empty list)
+    definition_present = False
+    tool_contract_valid = False
+    agent_path: Path | None = None
+    meta: dict[str, Any] | None = None
+
+    if resolved_agents_root is not None:
+        filename = agent_name if agent_name.endswith(".md") else f"{agent_name}.md"
+        agent_path = resolved_agents_root / filename
+        definition_present = agent_path.is_file()
+
+    # If no local definition and host doesn't declare the role, we can't
+    # determine usability. Distinguish "host says no" from "unknown".
+    if not definition_present and not host_callable:
+        # Check if this adapter is known to not support custom agents
+        adapter_name = skills_root.parent.name
+        if adapter_name in (".agents", ".cursor"):
+            # Codex/Cursor: may support via host manifest. If runtime.json
+            # has agentCapabilities but this role isn't listed, it's a
+            # genuine "not available". If no agentCapabilities field at all,
+            # we can't know — return UNKNOWN.
+            runtime_path = skills_root.parent / "runtime.json"
+            if not runtime_path.is_file():
+                return {
+                    "ok": True,
+                    "action": "check-agents",
+                    "agent": agent_name,
+                    "usable": False,
+                    "definitionPresent": False,
+                    "hostCallable": False,
+                    "toolContractValid": False,
+                    "reasonCode": "UNKNOWN",
+                    "reason": (
+                        "no local agent definition and no host capability manifest; "
+                        "cannot determine agent availability"
+                    ),
+                }
         return {
             "ok": False,
             "action": "check-agents",
             "agent": agent_name,
-            "path": str(agent_path),
-            "agentsRoot": str(resolved_agents_root),
+            "path": str(agent_path) if agent_path else None,
+            "agentsRoot": str(resolved_agents_root) if resolved_agents_root else None,
             "usable": False,
-            "definitionValid": False,
-            "runtimeSupported": True,
+            "definitionPresent": False,
+            "hostCallable": False,
+            "toolContractValid": False,
             "reasonCode": "AGENT_DEFINITION_NOT_FOUND",
-            "reason": f"agent file not found: {agent_path}",
+            "reason": f"agent file not found and host does not declare role: {agent_name}",
         }
 
-    try:
-        text = agent_path.read_text(encoding="utf-8")
-    except OSError as exc:
-        return {
-            "ok": False,
-            "action": "check-agents",
-            "agent": agent_name,
-            "path": str(agent_path),
-            "usable": False,
-            "reason": f"cannot read agent file: {exc}",
-        }
+    # If definition present, validate frontmatter and tools
+    if definition_present and agent_path is not None:
+        try:
+            text = agent_path.read_text(encoding="utf-8")
+        except OSError as exc:
+            return {
+                "ok": False,
+                "action": "check-agents",
+                "agent": agent_name,
+                "path": str(agent_path),
+                "usable": False,
+                "definitionPresent": True,
+                "hostCallable": host_callable,
+                "toolContractValid": False,
+                "reason": f"cannot read agent file: {exc}",
+            }
+
+        meta, err = parse_frontmatter(text)
+        if err or meta is None:
+            return {
+                "ok": False,
+                "action": "check-agents",
+                "agent": agent_name,
+                "path": str(agent_path),
+                "usable": False,
+                "definitionPresent": True,
+                "hostCallable": host_callable,
+                "toolContractValid": False,
+                "reason": f"frontmatter parse failed: {err or 'unknown'}",
+            }
+
+        tools = meta.get("tools")
+        if tools is None:
+            tool_contract_valid = False
+        elif isinstance(tools, list) and len(tools) > 0:
+            tool_contract_valid = True
+        else:
+            tool_contract_valid = False
 
-    meta, err = parse_frontmatter(text)
-    if err or meta is None:
-        return {
-            "ok": False,
-            "action": "check-agents",
-            "agent": agent_name,
-            "path": str(agent_path),
-            "usable": False,
-            "reason": f"frontmatter parse failed: {err or 'unknown'}",
-        }
+    # usable = hostCallable (host provides the agent role, tools validated by host)
+    # OR definitionPresent AND toolContractValid (definition-based adapters)
+    usable = host_callable or (
+        definition_present and tool_contract_valid
+    )
 
-    tools = meta.get("tools")
-    if tools is None:
-        return {
-            "ok": False,
-            "action": "check-agents",
-            "agent": agent_name,
-            "path": str(agent_path),
-            "usable": False,
-            "reason": "tools declaration missing",
-            "frontmatter": meta,
-        }
-    if not isinstance(tools, list) or len(tools) == 0:
-        return {
-            "ok": False,
-            "action": "check-agents",
-            "agent": agent_name,
-            "path": str(agent_path),
-            "usable": False,
-            "reason": "tools declaration empty or invalid",
-            "frontmatter": meta,
-        }
+    name_field = meta.get("name") if meta else None
+    tools_field = meta.get("tools") if meta else None
+
+    reason_code = "READY" if usable else "AGENT_DEFINITION_NOT_FOUND"
+    if not definition_present and host_callable:
+        reason_code = "DEFINITION_NOT_FOUND_HOST_CAPABLE"
 
-    name_field = meta.get("name")
     return {
         "ok": True,
         "action": "check-agents",
         "agent": agent_name,
-        "path": str(agent_path),
-        "agentsRoot": str(resolved_agents_root),
-        "usable": True,
-        "definitionValid": True,
-        "runtimeSupported": True,
-        "reasonCode": "READY",
-        "reason": "agent file exists; frontmatter parsed; tools declared",
+        "path": str(agent_path) if agent_path else None,
+        "agentsRoot": str(resolved_agents_root) if resolved_agents_root else None,
+        "usable": usable,
+        "definitionPresent": definition_present,
+        "hostCallable": host_callable,
+        "toolContractValid": tool_contract_valid,
+        "reasonCode": reason_code,
+        "reason": (
+            "agent available; "
+            f"definition={'present' if definition_present else 'absent'}, "
+            f"hostCallable={host_callable}, "
+            f"tools={'valid' if tool_contract_valid else 'invalid'}"
+        ),
         "name": name_field,
-        "tools": tools,
-        "frontmatterKeys": sorted(meta.keys()),
+        "tools": tools_field,
+        "frontmatterKeys": sorted(meta.keys()) if meta else [],
     }
 
 

package/harness/bundles/general/codebuddy/scripts/harness_state.py

@@ -268,6 +268,7 @@ def capture_current_state(
     changed: list[str] = []
     baseline_created = previous is None
     unresolved: list[str] = []
+    unresolved_reasons: list[dict[str, str]] = []
     if previous:
         old_segments = previous.get("segments") or {}
         for name, segment in fresh["segments"].items():
@@ -276,13 +277,17 @@ def capture_current_state(
                 segment["capturedAt"] = old.get("capturedAt", segment["capturedAt"])
             else:
                 changed.append(name)
-    else:
-        # A first observation establishes the baseline; it is not evidence
-        # that every segment changed during the current phase.
-        unresolved = sorted(fresh["segments"])
+    # First observation establishes the baseline; it is not evidence that
+    # segments changed, nor that they are "unresolved". Segments are only
+    # unresolved when they genuinely fail to read/compute (retro §5.6).
+    # On first capture, all successfully-captured segments are baseline,
+    # not unresolved.
     fresh["baselineCreated"] = baseline_created
     fresh["changedSegments"] = sorted(changed)
     fresh["unresolvedSegments"] = unresolved
+    fresh["unresolvedReasons"] = unresolved_reasons
+    fresh["comparisonAvailable"] = not baseline_created
+    fresh["baselineStatus"] = "created" if baseline_created else "reused"
     write_snapshot(change_dir, fresh)
     return fresh, changed
 
@@ -325,7 +330,10 @@ def main(argv: list[str] | None = None) -> int:
             - set(snapshot.get("unresolvedSegments") or [])
         ),
         "baselineCreated": bool(snapshot.get("baselineCreated")),
+        "baselineStatus": snapshot.get("baselineStatus", "reused"),
+        "comparisonAvailable": bool(snapshot.get("comparisonAvailable", True)),
         "unresolvedSegments": list(snapshot.get("unresolvedSegments") or []),
+        "unresolvedReasons": list(snapshot.get("unresolvedReasons") or []),
         "git": snapshot["git"],
     }
     if args.json:

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

@@ -2,5 +2,5 @@
   "schemaVersion": 1,
   "overlay": "none",
   "agent": "codex",
-  "coreHash": "e05be8d336ff5e7b"
+  "coreHash": "30342f0368faa261"
 }

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

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

package/harness/bundles/general/codex/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=e05be8d336ff5e7b; overlay=none; agent=codex; do not edit -->
+<!-- generated by harness_deploy.py; core=30342f0368faa261; overlay=none; agent=codex; do not edit -->
 # harness-codebase-map — 代码库地图
 
 ## Purpose

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=e05be8d336ff5e7b; overlay=none; agent=codex; do not edit -->
+<!-- generated by harness_deploy.py; core=30342f0368faa261; overlay=none; agent=codex; do not edit -->
 # harness-knowledge-ingest
 
 从 `.harness/archive/**/reports/final/summary-data.json` 抽取项目知识，生成并维护本地 `.harness/knowledge/` 索引。

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

@@ -3,7 +3,7 @@ name: harness-knowledge-query
 description: 根据新需求、设计任务、代码修改请求或问题排查，在规划和编码前查询 .harness/knowledge
   历史上下文。适用场景：query knowledge、查找历史需求、根据归档理解需求、继续之前类似开发、生成需求上下文包。
 ---
-<!-- generated by harness_deploy.py; core=e05be8d336ff5e7b; overlay=none; agent=codex; do not edit -->
+<!-- generated by harness_deploy.py; core=30342f0368faa261; overlay=none; agent=codex; 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/codex/harness-plan/SKILL.md

@@ -2,7 +2,7 @@
 name: harness-plan
 description: 将需求转化为设计文档+实施计划+完整测试场景表，必须在编码前完成。使用场景：需求分析、feature plan、技术方案设计、实现方案规划
 ---
-<!-- generated by harness_deploy.py; core=e05be8d336ff5e7b; overlay=none; agent=codex; do not edit -->
+<!-- generated by harness_deploy.py; core=30342f0368faa261; overlay=none; agent=codex; do not edit -->
 # harness-plan — 需求规划
 
 ## Purpose

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

@@ -3,7 +3,7 @@ name: harness-review
 description: 6维度代码审查（架构/安全/规范/兼容/测试/性能），对照项目规则（见
   .harness/context-index.json）和测试场景表，在隔离上下文运行。使用场景：代码审查、提交前检查、合并评审
 ---
-<!-- generated by harness_deploy.py; core=e05be8d336ff5e7b; overlay=none; agent=codex; do not edit -->
+<!-- generated by harness_deploy.py; core=30342f0368faa261; overlay=none; agent=codex; do not edit -->
 # harness-review — 代码审查
 
 ## Purpose

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=e05be8d336ff5e7b; 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=e05be8d336ff5e7b; 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

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=e05be8d336ff5e7b; 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=e05be8d336ff5e7b; 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,
@@ -3231,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
@@ -3293,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