@hunter-harness/workflow-harness 0.2.13 → 0.2.14

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

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

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=8dd8ce9aa1ac47f5; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=50a141f3d56ac500; overlay=none; agent=claude-code; do not edit -->
 # harness-archive — 变更归档
 
 ## Purpose

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=8dd8ce9aa1ac47f5; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=50a141f3d56ac500; 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=8dd8ce9aa1ac47f5; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=50a141f3d56ac500; 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=8dd8ce9aa1ac47f5; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=50a141f3d56ac500; 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=8dd8ce9aa1ac47f5; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=50a141f3d56ac500; 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=8dd8ce9aa1ac47f5; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=50a141f3d56ac500; 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=8dd8ce9aa1ac47f5; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=50a141f3d56ac500; 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=8dd8ce9aa1ac47f5; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=50a141f3d56ac500; overlay=none; agent=claude-code; do not edit -->
 # harness-submit — 最终提交（含 worktree 合并）
 
 ## Purpose
@@ -123,7 +123,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/claude-code/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/claude-code/harness-sync/SKILL.md

@@ -19,7 +19,7 @@ disallowed-tools:
   - Bash(awk *)
   - Bash(curl *)
 ---
-<!-- generated by harness_deploy.py; core=8dd8ce9aa1ac47f5; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=50a141f3d56ac500; 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=8dd8ce9aa1ac47f5; overlay=none; agent=claude-code; do not edit -->
+<!-- generated by harness_deploy.py; core=50a141f3d56ac500; overlay=none; agent=claude-code; do not edit -->
 # harness-test — 测试执行
 
 ## Purpose

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

@@ -2799,6 +2799,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():

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

@@ -224,6 +224,60 @@ def _layout_fields(project_root: Path, change_id: str) -> dict[str, Any]:
     }
 
 
+def read_concurrency_mode(project_root: Path) -> str:
+    """Return the configured concurrency mode (retro §5.2).
+
+    Defaults to ``single-active`` when no config declares a mode. Supported
+    values: ``single-active`` (default, blocks a second active Change),
+    ``isolated-multi-active`` (allows multiple active Changes but all
+    Change-scoped commands require ``--change``).
+    """
+    cfg = project_root / ".harness" / "config.json"
+    if cfg.is_file():
+        try:
+            data = json.loads(cfg.read_text(encoding="utf-8"))
+            if isinstance(data, dict):
+                mode = data.get("concurrencyMode")
+                if isinstance(mode, str) and mode in {
+                    "single-active",
+                    "isolated-multi-active",
+                }:
+                    return mode
+        except (OSError, json.JSONDecodeError):
+            pass
+    return "single-active"
+
+
+def check_concurrency_block(
+    project_root: Path, change_id: str
+) -> dict[str, Any] | None:
+    """Return a blocking payload when a second active Change is forbidden.
+
+    Returns ``None`` when the begin may proceed. In ``single-active`` mode a
+    second active Change (any other than ``change_id``) blocks begin; in
+    ``isolated-multi-active`` mode multiple active Changes are allowed.
+    """
+    mode = read_concurrency_mode(project_root)
+    if mode == "isolated-multi-active":
+        return None
+    active = list_active_changes(project_root)
+    others = [entry for entry in active if entry.get("changeId") != change_id]
+    if not others:
+        return None
+    return {
+        "ok": False,
+        "code": "SINGLE_ACTIVE_BLOCKED",
+        "message": (
+            "single-active concurrency mode: another active Change exists; "
+            "use portfolio/decompose to sequence multiple Changes, or switch "
+            "to isolated-multi-active after ensuring full Change-scoped isolation"
+        ),
+        "concurrencyMode": mode,
+        "activeChanges": active,
+        "blockingChanges": others,
+    }
+
+
 def resolve_change(
     project_root: Path,
     change_id: str | None,

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

@@ -623,6 +623,107 @@ def collect_files(root: Path) -> dict[str, str]:
     return files
 
 
+# --- Per-file bundle manifest (retro 2026-07-20 §5.1/5.25) -----------------
+#
+# registry_version + bundle_hash alone cannot prove every installed file
+# belongs to the declared bundle. The bundle therefore ships a per-file
+# manifest (relpath/sha256/size/mode/adapterTransformationId); install
+# verifies staging content against it BEFORE the atomic switch and never
+# updates metadata on partial failure.
+
+BUNDLE_MANIFEST_NAME = "bundle-manifest.json"
+_MANIFEST_EXCLUDED = frozenset(
+    {BUILD_MARKER, MANIFEST_NAME, AGENTS_MANAGED_NAME, BUNDLE_MANIFEST_NAME}
+)
+
+
+def build_manifest(root: Path, transformation_id: str = "raw") -> list[dict[str, Any]]:
+    """Return per-file manifest entries for every bundle file under ``root``.
+
+    Install metadata (build marker, managed manifests, the manifest itself)
+    is excluded. Entries are sorted by relpath for deterministic output.
+    """
+    root = root.resolve()
+    entries: list[dict[str, Any]] = []
+    for path in sorted(root.rglob("*")):
+        if not path.is_file() or "__pycache__" in path.parts:
+            continue
+        rel = path.relative_to(root).as_posix()
+        if rel in _MANIFEST_EXCLUDED:
+            continue
+        stat = path.stat()
+        entries.append(
+            {
+                "relpath": rel,
+                "sha256": sha256_file(path),
+                "size": stat.st_size,
+                "mode": stat.st_mode,
+                "adapterTransformationId": transformation_id,
+            }
+        )
+    return entries
+
+
+def compute_bundle_manifest_hash(entries: list[dict[str, Any]]) -> str:
+    """Deterministic aggregate hash over manifest entries (order-independent).
+
+    Must match packages/contracts/src/bundle-manifest.ts computeBundleManifestHash.
+    """
+    ordered = sorted(entries, key=lambda entry: entry["relpath"])
+    lines = [
+        f"{entry['relpath']}:{entry['sha256']}:{entry['size']}:{entry['mode']}:{entry['adapterTransformationId']}"
+        for entry in ordered
+    ]
+    return hashlib.sha256("\n".join(lines).encode("utf-8")).hexdigest()
+
+
+def aggregate_installed_content_hash(files: dict[str, str]) -> str:
+    """Deterministic aggregate hash over actually-installed relpath->sha256."""
+    lines = [f"{rel}:{files[rel]}" for rel in sorted(files)]
+    return hashlib.sha256("\n".join(lines).encode("utf-8")).hexdigest()
+
+
+def _verify_tree_against_manifest(
+    root: Path, entries: list[dict[str, Any]]
+) -> list[dict[str, str]]:
+    """Return mismatch details for files under ``root`` vs manifest entries."""
+    mismatches: list[dict[str, str]] = []
+    actual = collect_files(root)
+    declared = {entry["relpath"]: entry["sha256"] for entry in entries}
+    for rel, expected in sorted(declared.items()):
+        if rel not in actual:
+            mismatches.append({"relpath": rel, "expected": expected, "actual": "<missing>"})
+        elif actual[rel] != expected:
+            mismatches.append(
+                {"relpath": rel, "expected": expected, "actual": actual[rel]}
+            )
+    return mismatches
+
+
+def cmd_verify_installed(
+    installed_dir: Path, entries: list[dict[str, Any]], bundle_version: str
+) -> dict[str, Any]:
+    """Verify installed content against the bundle manifest, per file."""
+    installed_dir = installed_dir.resolve()
+    mismatches = _verify_tree_against_manifest(installed_dir, entries)
+    actual = collect_files(installed_dir)
+    declared = {entry["relpath"] for entry in entries}
+    content = {
+        rel: digest
+        for rel, digest in actual.items()
+        if rel not in _MANIFEST_EXCLUDED and rel in declared
+    }
+    return {
+        "ok": not mismatches,
+        "action": "verify-installed",
+        "bundleVersion": bundle_version,
+        "verificationStatus": "verified" if not mismatches else "degraded",
+        "installedContentHash": aggregate_installed_content_hash(content),
+        "verifiedAt": now_iso(),
+        "mismatchDetails": mismatches,
+    }
+
+
 def cmd_install(build_out: Path, project: Path, target: Path | None) -> dict[str, Any]:
     build_out = build_out.resolve()
     project = project.resolve()
@@ -644,6 +745,23 @@ def cmd_install(build_out: Path, project: Path, target: Path | None) -> dict[str
     backup: str | None = None
     staging = dest.parent / f".{dest.name}.staging-{uuid.uuid4().hex[:8]}"
     shutil.copytree(build_out, staging)
+    # Per-file content proof (retro §5.1): if the build carries a
+    # bundle-manifest.json, staging must match it exactly before anything is
+    # switched. A mismatch aborts the install without touching dest or any
+    # metadata — never a partial install under a fresh version label.
+    manifest_path = staging / BUNDLE_MANIFEST_NAME
+    if manifest_path.is_file():
+        manifest_data = json.loads(manifest_path.read_text(encoding="utf-8"))
+        manifest_entries = (
+            manifest_data.get("files", []) if isinstance(manifest_data, dict) else []
+        )
+        mismatches = _verify_tree_against_manifest(staging, manifest_entries)
+        if mismatches:
+            shutil.rmtree(staging, ignore_errors=True)
+            raise ValueError(
+                "BUNDLE_CONTENT_MISMATCH: staging diverges from bundle-manifest.json: "
+                + ", ".join(m["relpath"] for m in mismatches)
+            )
     if dest.exists() and any(dest.iterdir()):
         managed_old = _read_managed_set(dest / MANIFEST_NAME)
         # Preserve user-owned files: anything in dest that was NOT managed by a
@@ -771,6 +889,28 @@ def build_parser() -> argparse.ArgumentParser:
     v.add_argument("--bundle", type=Path, required=True)
     v.add_argument("--manifest", type=Path, required=True)
     v.add_argument("--json", action="store_true")
+
+    g = sub.add_parser(
+        "generate-manifest",
+        help="Generate per-file bundle-manifest.json for a bundle dir",
+    )
+    g.add_argument("--bundle", type=Path, required=True)
+    g.add_argument("--bundle-version", required=True)
+    g.add_argument(
+        "--transformation",
+        choices=["raw", "adapted", "workflow-packaged"],
+        default="raw",
+    )
+    g.add_argument("--out", type=Path)
+    g.add_argument("--json", action="store_true")
+
+    vi = sub.add_parser(
+        "verify-installed",
+        help="Verify installed tree content against bundle-manifest.json",
+    )
+    vi.add_argument("--installed", type=Path, required=True)
+    vi.add_argument("--manifest", type=Path, required=True)
+    vi.add_argument("--json", action="store_true")
     return p
 
 
@@ -794,6 +934,43 @@ def main(argv: list[str] | None = None) -> int:
             if args.json:
                 return emit_json(result)
             return 0 if result["ok"] else 1
+        if args.command == "generate-manifest":
+            entries = build_manifest(args.bundle, transformation_id=args.transformation)
+            manifest = {
+                "schemaVersion": 1,
+                "bundleVersion": args.bundle_version,
+                "bundleManifestHash": compute_bundle_manifest_hash(entries),
+                "files": entries,
+            }
+            text = json.dumps(manifest, ensure_ascii=False, indent=2) + "\n"
+            if args.out is not None:
+                args.out.parent.mkdir(parents=True, exist_ok=True)
+                args.out.write_text(text, encoding="utf-8", newline="\n")
+            result = {
+                "ok": True,
+                "action": "generate-manifest",
+                "bundleVersion": args.bundle_version,
+                "bundleManifestHash": manifest["bundleManifestHash"],
+                "fileCount": len(entries),
+                "out": str(args.out) if args.out is not None else None,
+            }
+            if args.json:
+                return emit_json(result)
+            if args.out is None:
+                print(text, end="")
+            return 0
+        if args.command == "verify-installed":
+            manifest_data = json.loads(args.manifest.read_text(encoding="utf-8"))
+            if not isinstance(manifest_data, dict):
+                raise ValueError("manifest must be a JSON object")
+            result = cmd_verify_installed(
+                args.installed,
+                manifest_data.get("files", []),
+                str(manifest_data.get("bundleVersion", "")),
+            )
+            if args.json:
+                return emit_json(result)
+            return 0 if result["ok"] else 1
     except (FileNotFoundError, KeyError, RuntimeError, ValueError) as exc:
         if getattr(args, "json", False):
             return emit_json({"ok": False, "error": str(exc)}, ok=False)

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