@hunter-harness/workflow-harness 0.2.12 → 0.2.14

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

@@ -506,6 +506,81 @@ def new_event_id(existing: list[dict[str, Any]] | None = None) -> str:
     return f"evt-{uuid.uuid4().hex}"
 
 
+def append_event(
+    change_dir: Path,
+    *,
+    phase: str,
+    type_: str,
+    note: str = "",
+    kind: str | None = None,
+    path: str | None = None,
+    run_id: str | None = None,
+    executor_tool: str | None = None,
+) -> dict[str, Any]:
+    """Programmatic append API (retro §5.31 C5/T16).
+
+    Validates and appends an event without going through argparse. Returns
+    a payload dict with ``ok``/``code``/``event``.
+    """
+    args = argparse.Namespace(
+        change_dir=str(change_dir),
+        phase=phase,
+        type=type_,
+        note=note,
+        kind=kind,
+        path=path,
+        run_id=run_id,
+        executor_tool=executor_tool,
+        command=None,
+        exit_code=None,
+        duration_ms=None,
+        status=None,
+        name=None,
+        code=None,
+        severity=None,
+        message=None,
+        decision=None,
+        reason=None,
+        issue_id=None,
+        scope=None,
+        target_event_id=None,
+        target_field=None,
+        old_value_hash=None,
+        new_value_json=None,
+        attempt=None,
+        executor_agent=None,
+        executor_model=None,
+        handoff_from_tool=None,
+        handoff_reason=None,
+        trace_id=None,
+        span_id=None,
+        parent_span_id=None,
+        runner_ms=None,
+        orchestration_active_ms=None,
+        wall_clock_ms=None,
+        user_wait_ms=None,
+        legacy_lenient=False,
+        json=True,
+    )
+    as_json = True
+    if type_ not in EVENT_TYPES:
+        return {"ok": False, "code": "EVENT_TYPE_INVALID", "message": f"unsupported type: {type_}"}
+    validation = validate_append_event(args)
+    if validation:
+        error_code, message = validation
+        return {"ok": False, "code": error_code, "message": message}
+    archived = archived_change_dir(change_dir)
+    if archived is not None:
+        return {"ok": False, "code": "ARCHIVED_CHANGE_IMMUTABLE", "message": str(archived)}
+    events_path_obj = events_path(change_dir)
+    lock_path = events_path_obj.with_name(events_path_obj.name + ".lock")
+    existing = []
+    event = build_event(args, existing)
+    with event_file_lock(lock_path):
+        atomic_append_line(events_path_obj, json.dumps(event, ensure_ascii=False))
+    return {"ok": True, "event": event, "events_path": str(events_path_obj), "rendered": False}
+
+
 def build_event(args: argparse.Namespace, existing: list[dict[str, Any]]) -> dict[str, Any]:
     event: dict[str, Any] = {
         "schema_version": SCHEMA_VERSION,
@@ -588,8 +663,31 @@ def validate_append_event(args: argparse.Namespace) -> tuple[str, str] | None:
         except json.JSONDecodeError as exc:
             return (
                 "CORRECTION_VALUE_INVALID_JSON",
-                f"CORRECTION_VALUE_INVALID_JSON: {exc.msg}",
+                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.
+    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:
+            return (
+                "ARTIFACT_PATH_REQUIRED",
+                "ARTIFACT_PATH_REQUIRED: artifact without --kind or --path is ambiguous; "
+                "use --kind informational for previews or --path for file artifacts",
             )
+        # If no kind is provided, infer from path presence: a path implies
+        # file-backed, absence implies informational (legacy compatibility).
     return None
 
 

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

@@ -329,6 +329,12 @@ def validate_ledger_entry_v2(entry: dict[str, Any], verification: str) -> tuple[
 
     Returns ``(missing_fields, degraded_ok)`` where ``degraded_ok`` is True only when
     the entry is a valid DEGRADED NOT_RUN record with no other missing fields.
+
+    Retro §5.14: ``status=OK``/``status=NOT_RUN``/``status=FAIL`` in the
+    missing list is a *status value* hint, not a field-completeness defect.
+    Callers consuming this under ``phase_status=FAIL`` must filter out
+    ``status=*`` entries from the missing list before treating them as
+    blocking problems.
     """
     missing: list[str] = []
     degraded = is_degraded_ledger_entry(entry)
@@ -341,7 +347,7 @@ def validate_ledger_entry_v2(entry: dict[str, Any], verification: str) -> tuple[
                 missing.append("inputsFiles(non-empty)")
         elif field == "status":
             if value != "OK" and not degraded:
-                missing.append("status=OK")
+                missing.append(f"status={value}")
         elif not (isinstance(value, str) and value.strip()):
             missing.append(field)
         elif field == "coverage" and str(value).strip() not in hl.COVERAGE_RANK:
@@ -357,8 +363,16 @@ def validate_ledger_for_phase_close(
     policy: dict[str, Any],
     *,
     execution_root: Path | None = None,
+    phase_status: str = "OK",
 ) -> dict[str, Any]:
-    """Validate ledger v2 fields required for phase close (UT-026)."""
+    """Validate ledger v2 fields required for phase close (UT-026).
+
+    Retro §5.14: ``phase_status`` separates phase outcome from promotion gate.
+    ``phase_status=OK`` (default) requires all required validations to be OK;
+    ``phase_status=FAIL`` validates field completeness and identity but allows
+    individual validation status to be FAIL/NOT_RUN, so a failing phase can
+    close honestly without polluting evidence or blocking lease release.
+    """
     required = policy.get("requiredValidations", {}).get(phase, [])
     if not required:
         return {"ok": True, "code": "LEDGER_NOT_REQUIRED", "phase": phase}
@@ -443,6 +457,7 @@ def validate_ledger_for_phase_close(
 
     problems: list[dict[str, Any]] = []
     degraded: list[str] = []
+    fail_status: list[str] = []
     for verification in required:
         entry = validations.get(verification)
         if not isinstance(entry, dict):
@@ -455,6 +470,12 @@ def validate_ledger_for_phase_close(
             )
             continue
         missing, is_degraded = validate_ledger_entry_v2(entry, verification)
+        # Retro §5.14: under phase_status=FAIL/WARN, status value hints
+        # (status=FAIL, status=NOT_RUN) are acceptable; only real field-
+        # completeness defects block close. Under phase_status=OK, status
+        # value hints are blocking.
+        if phase_status.upper() in {"FAIL", "WARN"}:
+            missing = [m for m in missing if not m.startswith("status=")]
         if missing:
             code = (
                 "MISSING_V2_FIELDS"
@@ -476,8 +497,21 @@ def validate_ledger_for_phase_close(
                     "code": code,
                 }
             )
-        elif is_degraded:
+            continue
+        if is_degraded:
             degraded.append(verification)
+            continue
+        # Under phase_status=FAIL/WARN, a FAIL/NOT_RUN status is acceptable.
+        entry_status = str(entry.get("status") or "").upper()
+        if entry_status in {"FAIL", "NOT_RUN"}:
+            if phase_status.upper() in {"FAIL", "WARN"}:
+                fail_status.append(verification)
+            else:
+                problems.append({
+                    "verification": verification,
+                    "missing": [f"status={entry_status}"],
+                    "code": "VALIDATION_NOT_OK",
+                })
 
     if problems:
         return {
@@ -489,6 +523,16 @@ def validate_ledger_for_phase_close(
             "ledgerPath": str(ledger_path) if ledger_path else None,
             "detail": "natural-language override is not permitted",
         }
+    if fail_status:
+        return {
+            "ok": True,
+            "code": "LEDGER_OK_FAIL",
+            "phase": phase,
+            "validated": required,
+            "failed": fail_status,
+            "degraded": degraded,
+            "ledgerPath": str(ledger_path) if ledger_path else None,
+        }
     if degraded:
         return {
             "ok": True,
@@ -1169,6 +1213,14 @@ def cmd_begin(args: argparse.Namespace) -> int:
             extra={k: v for k, v in resolved.items() if k not in {"ok", "message"}},
         )
     change_dir = Path(resolved["changeDir"])
+    concurrency_block = hc.check_concurrency_block(project, resolved["changeId"])
+    if concurrency_block is not None:
+        return emit_error(
+            str(concurrency_block.get("code", "CONCURRENCY_BLOCKED")),
+            str(concurrency_block.get("message", "concurrency mode blocked begin")),
+            as_json=as_json,
+            extra={k: v for k, v in concurrency_block.items() if k not in {"ok", "message"}},
+        )
     blocked = foundation_gate_blocks(getattr(args, "task", None), change_dir)
     if blocked:
         return emit_error(
@@ -1407,7 +1459,8 @@ def cmd_close(args: argparse.Namespace) -> int:
             return emit_error("PHASE_CAPSULE_MISMATCH", str(exc), as_json=as_json)
 
     ledger_result = validate_ledger_for_phase_close(
-        change_dir, args.phase, policy, execution_root=execution_root
+        change_dir, args.phase, policy, execution_root=execution_root,
+        phase_status=args.status,
     )
     if not ledger_result.get("ok") and args.phase in {"run", "test", "package"}:
         return emit_error(

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

@@ -422,6 +422,9 @@ class IntegrationTransaction:
         else:
             result = hl.record_integration_hashes(
                 ledger_path,
+                change_dir=(
+                    self.project_root / ".harness" / "changes" / self.change_id
+                ),
                 repository_id=str(journal["repositoryId"]),
                 merge_final_hash=merge_commit,
                 ci_expected_head=merge_commit,

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

@@ -621,12 +621,13 @@ def validate_ledger_identity(ledger: dict[str, Any]) -> list[str]:
 def record_integration_hashes(
     ledger_path: Path,
     *,
+    change_dir: Path | None = None,
     repository_id: str,
     merge_final_hash: str,
     ci_expected_head: str,
     remote_head: str,
 ) -> dict[str, Any]:
-    """Atomically attach post-push identity to an existing ledger v3."""
+    """Atomically attach post-push hashes using the change contract's ledger rules."""
     path = Path(ledger_path).resolve()
     if not path.is_file():
         return {"ok": False, "code": "LEDGER_MISSING", "ledgerPath": str(path)}
@@ -637,15 +638,26 @@ def record_integration_hashes(
             "ok": False, "code": "LEDGER_INVALID", "ledgerPath": str(path),
             "message": str(exc),
         }
+    legacy_contract = False
+    if change_dir is not None:
+        resolved_change_dir = Path(change_dir).resolve()
+        if ledger.get("changeName") != resolved_change_dir.name:
+            return {
+                "ok": False,
+                "code": "LEDGER_CHANGE_MISMATCH",
+                "ledgerPath": str(path),
+            }
+        legacy_contract = not _contract_is_v2(resolved_change_dir)
+
     missing = validate_ledger_identity(ledger)
-    if missing:
+    if missing and not legacy_contract:
         return {
             "ok": False,
             "code": "LEDGER_IDENTITY_INVALID",
             "ledgerPath": str(path),
             "missing": missing,
         }
-    if ledger.get("repositoryId") != repository_id:
+    if not missing and ledger.get("repositoryId") != repository_id:
         return {
             "ok": False,
             "code": "LEDGER_REPOSITORY_MISMATCH",

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

@@ -29,6 +29,7 @@ if hasattr(sys.stderr, "reconfigure"):
     sys.stderr.reconfigure(encoding="utf-8")
 
 
+import harness_change as hc  # noqa: E402
 import harness_profile as hprof  # noqa: E402
 
 
@@ -69,6 +70,52 @@ def cmd_check(project: Path) -> dict[str, Any]:
     return result
 
 
+def check_concurrency(project: Path) -> dict[str, Any]:
+    """Report the configured concurrency mode and active Change landscape.
+
+    Retro §5.2: preflight must surface concurrencyMode, activeChanges, and
+    allowedParallelLevels so agents don't have to guess whether parallel
+    Changes are supported.
+    """
+    mode = hc.read_concurrency_mode(project)
+    active = hc.list_active_changes(project)
+    shared_conflicts: list[dict[str, Any]] = []
+    # In isolated-multi-active, surface any shared-state conflicts (e.g. same
+    # worktree path) so callers know isolation is incomplete.
+    if mode == "isolated-multi-active" and len(active) > 1:
+        seen_worktrees: dict[str, str] = {}
+        for entry in active:
+            change_dir = Path(entry["path"])
+            worktree_meta = change_dir / "meta" / "worktree.json"
+            if not worktree_meta.is_file():
+                continue
+            try:
+                meta = json.loads(worktree_meta.read_text(encoding="utf-8"))
+            except (OSError, json.JSONDecodeError):
+                continue
+            wt = meta.get("path") if isinstance(meta, dict) else None
+            if isinstance(wt, str) and wt:
+                if wt in seen_worktrees:
+                    shared_conflicts.append({
+                        "kind": "worktree",
+                        "path": wt,
+                        "changes": [seen_worktrees[wt], entry["changeId"]],
+                    })
+                else:
+                    seen_worktrees[wt] = entry["changeId"]
+    levels = ["change-internal"] if mode == "single-active" else [
+        "change-internal",
+        "multi-change",
+    ]
+    return {
+        "ok": True,
+        "concurrencyMode": mode,
+        "activeChanges": active,
+        "sharedStateConflicts": shared_conflicts,
+        "allowedParallelLevels": levels,
+    }
+
+
 # ---------------------------------------------------------------------------
 # record-quirk — 适配 v2 commands（source=user override）
 # ---------------------------------------------------------------------------

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

@@ -448,9 +448,18 @@ def _validate_existing_manifest(
         tracked_now = _git(
             project, "ls-files", "--error-unmatch", "--", rel
         ).returncode == 0
-        if item["ignored"] != ignored_now or item["trackedBefore"] != tracked_now:
+        checkpointed = not item["trackedBefore"] and tracked_now
+        if (
+            item["trackedBefore"] != tracked_now and not checkpointed
+        ) or (
+            item["ignored"] != ignored_now and not checkpointed
+        ):
             return "MANIFEST_INVALID", {}
-        validated[rel] = dict(item)
+        normalized_item = dict(item)
+        if checkpointed:
+            normalized_item["trackedBefore"] = True
+            normalized_item["ignored"] = ignored_now
+        validated[rel] = normalized_item
     return None, validated
 
 
@@ -734,11 +743,26 @@ def _stage_locked(
     error, entries = validator(project_root, manifest, require_files=True)
     if error:
         return _result(False, action, error, [])
-    rels = [
-        rel
-        for rel, entry in entries.items()
-        if not is_v2 or entry.get("commitScope") == "current-change"
-    ]
+    rels: list[str] = []
+    for rel, entry in entries.items():
+        if is_v2:
+            if entry.get("commitScope") == "current-change":
+                rels.append(rel)
+            continue
+        if not entry["trackedBefore"]:
+            rels.append(rel)
+            continue
+        changed = _git(project_root, "diff", "--quiet", "HEAD", "--", rel)
+        if changed.returncode == 1:
+            rels.append(rel)
+        elif changed.returncode != 0:
+            return _result(
+                False,
+                action,
+                "GIT_DIFF_FAILED",
+                [rel],
+                error=changed.stderr.strip(),
+            )
     if not rels:
         return _result(True, action, "STAGED", [])
 
@@ -925,9 +949,22 @@ def close(project: Path | str, change_dir: Path | str) -> dict[str, Any]:
     if (
         not isinstance(snapshot, dict)
         or snapshot.get("schemaVersion") != SCHEMA_VERSION
-        or snapshot.get("projectRoot") != str(project_root)
     ):
         return _result(False, action, "SNAPSHOT_INVALID", [])
+    # Execution-root contract (retro §5.10): a snapshot captured against a
+    # different project root must fail with EXECUTION_ROOT_MISMATCH before
+    # the generic SNAPSHOT_INVALID, so callers can distinguish "wrong root"
+    # from "corrupt snapshot".
+    snapshot_root = snapshot.get("projectRoot")
+    if snapshot_root is not None and snapshot_root != str(project_root):
+        return _result(
+            False,
+            action,
+            "EXECUTION_ROOT_MISMATCH",
+            [],
+            expectedRoot=snapshot_root,
+            actualRoot=str(project_root),
+        )
 
     before_entries = snapshot.get("files")
     if not isinstance(before_entries, list):
@@ -963,15 +1000,51 @@ def close(project: Path | str, change_dir: Path | str) -> dict[str, Any]:
         if before[rel]["sha256"] != digest:
             touched.append((rel, "test-updated"))
 
-    recorded: list[str] = []
-    for rel, reason in touched:
-        result = record(project_root, change_root, [str(project_root / rel)], reason)
+    for reason in ("tdd-created", "test-updated"):
+        rels = [rel for rel, item_reason in touched if item_reason == reason]
+        if not rels:
+            continue
+        result = record(
+            project_root,
+            change_root,
+            [str(project_root / rel) for rel in rels],
+            reason,
+        )
         if not result.get("ok"):
             code = result.get("code", "RECORD_FAILED")
             if code == "TEST_PATH_NOT_ALLOWED":
-                return _result(False, action, "UNCLASSIFIABLE_TEST", [rel])
+                return _result(False, action, "UNCLASSIFIABLE_TEST", rels)
             return result
-        recorded.append(rel)
+
+    recorded = [rel for rel, _ in touched]
+
+    # Cross-check (retro §5.10): if the manifest has active entries for this
+    # change but close computed recordedCount=0, the snapshot/manifest/diff
+    # are inconsistent. Fail closed instead of silently returning success.
+    manifest_path = _manifest_path(change_root)
+    if manifest_path is not None and manifest_path.is_file():
+        try:
+            manifest = _read_json(manifest_path)
+        except (OSError, json.JSONDecodeError):
+            manifest = None
+        if isinstance(manifest, dict):
+            manifest_files = manifest.get("files")
+            if isinstance(manifest_files, list):
+                active_entries = [
+                    f for f in manifest_files
+                    if isinstance(f, dict)
+                    and f.get("reason") in ("tdd-created", "test-updated", "stale-test-repair")
+                ]
+                if active_entries and not recorded:
+                    return _result(
+                        False,
+                        action,
+                        "MANIFEST_DIFF_HASH_MISMATCH",
+                        [],
+                        manifestEntries=len(active_entries),
+                        recordedCount=0,
+                        detail="manifest has active entries but close computed 0 recorded tests",
+                    )
 
     return _result(
         True,

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

@@ -2,5 +2,5 @@
   "schemaVersion": 1,
   "overlay": "none",
   "agent": "codebuddy",
-  "coreHash": "8dd8ce9aa1ac47f5"
+  "coreHash": "50a141f3d56ac500"
 }

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

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

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

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

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

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

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

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

package/harness/bundles/general/codebuddy/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=8dd8ce9aa1ac47f5; overlay=none; agent=codebuddy; do not edit -->
+<!-- generated by harness_deploy.py; core=50a141f3d56ac500; overlay=none; agent=codebuddy; 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/codebuddy/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/codebuddy/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=8dd8ce9aa1ac47f5; overlay=none; agent=codebuddy; do not edit -->
+<!-- generated by harness_deploy.py; core=50a141f3d56ac500; overlay=none; agent=codebuddy; do not edit -->
 # harness-sync — 元数据同步
 
 ## Purpose
@@ -39,7 +39,7 @@ python <skills-root>/scripts/harness_sync.py finalize --project . --run-id <run-
 | 3.5 | `harness_knowledge.py sync`；可 `sync --update`；失败不得假装可用。**知识闭环主入口**是 `/harness-knowledge-ingest auto`（含 Agent judge），sync 不重复列人工知识待办 |
 | 3.6 | 单次运行 `harness_knowledge.py maintain --project . --drain --json`，有界推进全部 `.harness/knowledge/maintenance-outbox/{pending,failed}`；不得为每个条目重复启动 Python/重建索引（§8.2：archive close 只 enqueue，sync 异步推进 outbox 到 completed/pending-judge） |
 | 4 | CLAUDE.md 完整性/行数 → 超限 AskUserQuestion 瘦身 |
-| 5 | AGENTS.md 与 CLAUDE.md 一致 |
+| 5 | AGENTS.md 与各 Agent 指令入口一致；Claude Code 启用时验证 CLAUDE.md 引用 AGENTS.md，禁止反向循环引用 |
 | 6 | `.harness/` 结构（init 规程 → `reference.md` 第 6 步）；已装 skill 新鲜度只经 `hunter-harness refresh --dry-run --json` 的 post-adaptation freshness 判断，禁止 raw build 字节比较 |
 | 7–9 | `项目规则（见 .harness/context-index.json）/`、构建配置、测试目录 — **只提示不自动修复** |