agent-tune-kit 2.3.1__tar.gz → 2.3.2__tar.gz

{agent_tune_kit-2.3.1 → agent_tune_kit-2.3.2}/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-tune-kit",
-  "version": "2.3.1",
+  "version": "2.3.2",
   "description": "Local Codex plugin for batch Agent evaluation and session trace tuning with evidence-backed issues, focused changes, verification and offline review.",
   "author": {
     "name": "hustyichi",

{agent_tune_kit-2.3.1 → agent_tune_kit-2.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: agent-tune-kit
-Version: 2.3.1
+Version: 2.3.2
 Summary: Local Codex plugin for iterative Agent tuning with guided Skills, reusable runner templates, versioned results, and static validation.
 Project-URL: Homepage, https://github.com/hustyichi/agent-tune-kit
 Project-URL: Repository, https://github.com/hustyichi/agent-tune-kit
@@ -165,7 +165,11 @@ $atk-visualize-trace Open the execution lanes for session <session-id> and jump
 
 Detection retains issues with serious impact, recurrence, direct relevance to your stated focus, or a concrete implementation improvement lead, and explains the retention reason, evidence and inspection scope. Implementation leads include code, configuration, tool contracts, Prompt and Skill; an unresolved cause can proceed to diagnosis. Minor observations with none of these reasons are not saved separately. No retained issues does not prove the session was correct.
 
-Use Trace IDs to locate evidence within the session and open issue details to read the retention reason. You can generate a preview once traces are archived. Review any retained content in the HTML before sharing it.
+The capture, detect, diagnose, optimize and verify Skills generate or update `.atk/traces/<session_id>/preview.html` at stage end without opening a browser. Use `$atk-visualize-trace` when you want to open it; refresh an already open page after the file changes. Initialization has no session trace and does not generate an empty page.
+
+These stages also refresh the project dashboard `.atk/traces/index.html`, which shows issues and actual progress across all sessions by session or by issue category and links back to each session page. To open it, send `$atk-visualize-trace Open the trace dashboard`. Issues recorded before categories existed show as uncategorized until their session is analyzed again.
+
+Use Trace IDs to locate evidence within the session and open issue details to read the retention reason. Review any retained content in the HTML before sharing it.
 
 ### 3. Investigate, Fix, and Verify an Issue as Needed
 
@@ -179,7 +183,7 @@ Start with diagnosis when you already have a specific issue and session evidence
 
 ### Where to Find Trace Outputs
 
-Each session archive is stored under `.atk/traces/<session_id>/` in your Agent project. Files appear as you run the corresponding steps.
+Each session archive is stored under `.atk/traces/<session_id>/` in your Agent project. Files appear as you run the corresponding steps. The project dashboard `index.html` and the category list `categories.json` sit directly under `.atk/traces/`.
 
 | File or directory | What it shows |
 | --- | --- |

{agent_tune_kit-2.3.1 → agent_tune_kit-2.3.2}/README.en.md

@@ -151,7 +151,11 @@ $atk-visualize-trace Open the execution lanes for session <session-id> and jump
 
 Detection retains issues with serious impact, recurrence, direct relevance to your stated focus, or a concrete implementation improvement lead, and explains the retention reason, evidence and inspection scope. Implementation leads include code, configuration, tool contracts, Prompt and Skill; an unresolved cause can proceed to diagnosis. Minor observations with none of these reasons are not saved separately. No retained issues does not prove the session was correct.
 
-Use Trace IDs to locate evidence within the session and open issue details to read the retention reason. You can generate a preview once traces are archived. Review any retained content in the HTML before sharing it.
+The capture, detect, diagnose, optimize and verify Skills generate or update `.atk/traces/<session_id>/preview.html` at stage end without opening a browser. Use `$atk-visualize-trace` when you want to open it; refresh an already open page after the file changes. Initialization has no session trace and does not generate an empty page.
+
+These stages also refresh the project dashboard `.atk/traces/index.html`, which shows issues and actual progress across all sessions by session or by issue category and links back to each session page. To open it, send `$atk-visualize-trace Open the trace dashboard`. Issues recorded before categories existed show as uncategorized until their session is analyzed again.
+
+Use Trace IDs to locate evidence within the session and open issue details to read the retention reason. Review any retained content in the HTML before sharing it.
 
 ### 3. Investigate, Fix, and Verify an Issue as Needed
 
@@ -165,7 +169,7 @@ Start with diagnosis when you already have a specific issue and session evidence
 
 ### Where to Find Trace Outputs
 
-Each session archive is stored under `.atk/traces/<session_id>/` in your Agent project. Files appear as you run the corresponding steps.
+Each session archive is stored under `.atk/traces/<session_id>/` in your Agent project. Files appear as you run the corresponding steps. The project dashboard `index.html` and the category list `categories.json` sit directly under `.atk/traces/`.
 
 | File or directory | What it shows |
 | --- | --- |

{agent_tune_kit-2.3.1 → agent_tune_kit-2.3.2}/README.md

@@ -151,7 +151,11 @@ $atk-visualize-trace 打开 <session-id> 的执行泳道，从问题跳到相关
 
 分析保留影响严重、反复出现、与你明确关注点相关，或有具体实现改进线索的问题，并说明保留理由、证据和检查范围。实现线索包括代码、配置、工具契约、Prompt 和 Skill；根因尚未确定也可进入后续诊断。轻微且无上述保留理由的观察不单独记录，没有保留问题不代表会话完全正确。
 
-可用 Trace ID 定位会话内的证据，在问题详情中查看保留理由。有归档轨迹即可生成预览，分享 HTML 前请核对其中留存的正文。
+采集、分析、诊断、修复和验证 Skill 在阶段结束后默认生成或更新 `.atk/traces/<session_id>/preview.html`，不自动打开浏览器。需要打开时使用 `$atk-visualize-trace`；已打开的页面在文件更新后需刷新。初始化没有会话轨迹，不生成空页面。
+
+这些阶段同时刷新项目大盘 `.atk/traces/index.html`，按会话或异常分类查看全部会话的问题和实际进度，并可跳回各会话页。需要打开时发送 `$atk-visualize-trace 打开轨迹大盘`。早于分类功能的问题显示为“未分类”，对应会话重新分析时补上。
+
+可用 Trace ID 定位会话内的证据，在问题详情中查看保留理由。分享 HTML 前请核对其中留存的正文。
 
 ### 3. 按问题调查、修复和验证（按需）
 
@@ -165,7 +169,7 @@ $atk-trace-verify 验证 <session-id> 的 ISSUE-001 对应候选，并检查相
 
 ### 查看轨迹产物
 
-会话归档保存在 Agent 项目的 `.atk/traces/<session_id>/` 下，文件随对应步骤生成。
+会话归档保存在 Agent 项目的 `.atk/traces/<session_id>/` 下，文件随对应步骤生成。项目大盘 `index.html` 和分类表 `categories.json` 位于 `.atk/traces/` 根目录。
 
 | 文件或目录 | 用途 |
 | --- | --- |

{agent_tune_kit-2.3.1 → agent_tune_kit-2.3.2}/agent_tune_kit/__init__.py

@@ -1,3 +1,3 @@
 """Agent Tune Kit package."""
 
-__version__ = "2.3.1"
+__version__ = "2.3.2"

{agent_tune_kit-2.3.1 → agent_tune_kit-2.3.2}/agent_tune_kit/cli/trace.py

@@ -3,7 +3,7 @@
 import json
 from pathlib import Path
 
-from agent_tune_kit.traces import records, store
+from agent_tune_kit.traces import categories, records, store
 from agent_tune_kit.traces.capture import fetch_session, import_session
 from agent_tune_kit.traces.query import overview, search, show
 
@@ -34,6 +34,12 @@ def register(subparsers):
     init.add_argument("--config", help="non-secret configuration JSON file")
     init.add_argument("--project-file", help="project context Markdown file")
     init.add_argument("--json", action="store_true")
+    category = actions.add_parser("category", help="list or update the project issue category vocabulary")
+    category.add_argument("--project-root", default=".")
+    mode = category.add_mutually_exclusive_group(required=True)
+    mode.add_argument("--list", action="store_true", help="list categories with per-session issue counts")
+    mode.add_argument("--data", help="category JSON; revising the vocabulary requires its current revision")
+    category.add_argument("--json", action="store_true")
     for action in [
         "migrate",
         "fetch",
@@ -100,6 +106,10 @@ def execute(args):
     if args.action == "init":
         text = Path(args.project_file).read_text(encoding="utf-8") if args.project_file else None
         return store.init_workspace(args.project_root, config=read_json(args.config), project_text=text)
+    if args.action == "category":
+        if args.list:
+            return categories.list_categories(args.project_root)
+        return categories.save_category(args.project_root, read_json(args.data))
     source = read_json(args.source)
     if args.action == "migrate":
         from agent_tune_kit.traces.migrate import migrate

{agent_tune_kit-2.3.1 → agent_tune_kit-2.3.2}/agent_tune_kit/cli/visualize.py

@@ -4,6 +4,7 @@ import sys
 from agent_tune_kit.errors import UserActionRequired
 from agent_tune_kit.visualize import generate_dataset, generate_failures
 from agent_tune_kit.visualize.trace import generate_trace
+from agent_tune_kit.visualize.traces import generate_traces
 
 from .output import emit
 from .trace import add_session_options, read_json
@@ -17,6 +18,8 @@ def add_options(parser, kind):
         parser.add_argument("--json", action="store_true")
     if kind == "dataset":
         parser.add_argument("--dataset-path", default=".atk/datasets/dataset.csv")
+    elif kind == "traces":
+        parser.add_argument("--project-root", default=".")
     elif kind == "trace":
         add_session_options(parser)
         parser.add_argument("--output-path")
@@ -31,14 +34,17 @@ def register(subparsers):
     commands = subparsers.add_parser("visualize", help="generate offline review pages").add_subparsers(
         dest="action", required=True
     )
-    for kind in ["dataset", "failures", "trace"]:
-        add_options(commands.add_parser(kind), kind)
+    helps = {"traces": "generate the project dashboard of every archived trace session"}
+    for kind in ["dataset", "failures", "trace", "traces"]:
+        add_options(commands.add_parser(kind, help=helps.get(kind)), kind)
 
 
 def execute(args):
     options = dict(overwrite=args.overwrite, open_browser=args.open_browser)
     if args.action == "dataset":
         return generate_dataset(args.dataset_path, **options)
+    if args.action == "traces":
+        return generate_traces(args.project_root, **options)
     if args.action == "trace":
         return generate_trace(
             args.project_root,

{agent_tune_kit-2.3.1 → agent_tune_kit-2.3.2}/agent_tune_kit/traces/archive.py

@@ -18,7 +18,9 @@ def component(value):
     if not isinstance(value, str) or not value.strip():
         raise UserActionRequired("An explicit nonempty native ID is required.")
     name = quote(value, safe="")
-    if name.startswith(".") or name.casefold() in {"project.md", "config.json", "_export_summary"}:
+    # Names of the files that live beside session directories at the archive root.
+    reserved = {"project.md", "config.json", "categories.json", "index.html", "_export_summary"}
+    if name.startswith(".") or name.casefold() in reserved:
         name = "%" + format(ord(name[0]), "02X") + name[1:]
     if len(name) > 200:
         name = name[:150] + "~" + hashlib.sha256(value.encode()).hexdigest()

agent_tune_kit-2.3.2/agent_tune_kit/traces/categories.py

@@ -0,0 +1,173 @@
+"""Project-level issue category vocabulary.
+
+The host decides which category fits an issue; this module only keeps the vocabulary consistent. Entries are never
+deleted, so issues that reference a category stay displayable after it is deprecated.
+"""
+
+import re
+from pathlib import Path
+
+from agent_tune_kit.errors import UserActionRequired
+from agent_tune_kit.results.evidence import now, safe_path, write_manifest
+
+from .store import ensure_workspace, read_json, session_write_lock, trace_root
+
+FILENAME = "categories.json"
+CATEGORY_ID = re.compile(r"[a-z0-9]+(?:-[a-z0-9]+)*")
+MAX_ID = 64
+
+
+def _path(root):
+    return safe_path(Path(root), FILENAME)
+
+
+def _check_catalog(value):
+    if (
+        value.get("schema_version") != 1
+        or not isinstance(value.get("revision"), int)
+        or isinstance(value.get("revision"), bool)
+        or not isinstance(value.get("categories"), list)
+    ):
+        raise UserActionRequired("Invalid Trace category vocabulary.")
+    seen = set()
+    for item in value["categories"]:
+        if (
+            not isinstance(item, dict)
+            or not isinstance(item.get("id"), str)
+            or not CATEGORY_ID.fullmatch(item["id"])
+            or item["id"] in seen
+            or any(not isinstance(item.get(key), str) or not item[key].strip() for key in ("name", "definition"))
+            or not isinstance(item.get("deprecated"), bool)
+        ):
+            raise UserActionRequired("Invalid Trace category entry.")
+        seen.add(item["id"])
+    return value
+
+
+def load_catalog(root):
+    """Read the vocabulary from a traces root; a missing file is an empty vocabulary."""
+    path = _path(root)
+    if not path.exists():
+        return {"schema_version": 1, "revision": 0, "categories": []}
+    return _check_catalog(read_json(path))
+
+
+def category_map(root):
+    """Return ``{id: entry}`` for display, tolerating a damaged file so one bad record cannot hide sessions."""
+    try:
+        return {item["id"]: item for item in load_catalog(root)["categories"]}
+    except UserActionRequired:
+        return {}
+
+
+def check_issue_category(root, category, previous=None):
+    """Validate an issue category against the vocabulary; an unchanged deprecated value stays valid."""
+    if not isinstance(category, str) or not category:
+        raise UserActionRequired("Issue category must be a category ID from the project vocabulary.")
+    entry = next((item for item in load_catalog(root)["categories"] if item["id"] == category), None)
+    if entry is None:
+        raise UserActionRequired(
+            f"Unknown issue category {category!r}; list the vocabulary with `atk trace category --list` first."
+        )
+    if entry["deprecated"] and category != previous:
+        raise UserActionRequired(f"Issue category {category!r} is deprecated; choose a current category.")
+    return category
+
+
+def save_category(project_root, data):
+    """Add or revise one category. Supplying ``revision`` is required once the vocabulary exists."""
+    if not isinstance(data, dict):
+        raise UserActionRequired("Category data must be an object.")
+    unknown = set(data) - {"id", "name", "definition", "deprecated", "revision", "expected_revision"}
+    if unknown:
+        raise UserActionRequired(f"Unsupported category fields: {', '.join(sorted(unknown))}.")
+    category_id = data.get("id")
+    if not isinstance(category_id, str) or not CATEGORY_ID.fullmatch(category_id) or len(category_id) > MAX_ID:
+        raise UserActionRequired("Category id must be lowercase kebab-case (letters, digits and single hyphens).")
+    expected = data.get("revision", data.get("expected_revision"))
+    if expected is not None and (not isinstance(expected, int) or isinstance(expected, bool)):
+        raise UserActionRequired("Category revision must be an integer.")
+    # The vocabulary lives in the private archive, so it gets the same Git ignore rule as captured sessions.
+    root, _ = ensure_workspace(project_root)
+    with session_write_lock(root):
+        catalog = load_catalog(root)
+        if expected is None and catalog["revision"] == 0:
+            expected = 0
+        if expected != catalog["revision"]:
+            raise UserActionRequired(
+                f"Stale or missing category revision; current vocabulary revision is {catalog['revision']}."
+            )
+        entries = catalog["categories"]
+        existing = next((item for item in entries if item["id"] == category_id), None)
+        stamp = now()
+        if existing is None:
+            for key in ("name", "definition"):
+                if not isinstance(data.get(key), str) or not data[key].strip():
+                    raise UserActionRequired(f"A new category needs a nonempty {key}.")
+            if data.get("deprecated") not in (None, False):
+                raise UserActionRequired("A new category cannot start deprecated.")
+            entry = {
+                "id": category_id,
+                "name": data["name"].strip(),
+                "definition": data["definition"].strip(),
+                "deprecated": False,
+                "created_at": stamp,
+                "updated_at": stamp,
+            }
+            entries.append(entry)
+        else:
+            entry = existing
+            for key in ("name", "definition"):
+                if key in data:
+                    if not isinstance(data[key], str) or not data[key].strip():
+                        raise UserActionRequired(f"Category {key} must be a nonempty string.")
+                    entry[key] = data[key].strip()
+            if "deprecated" in data:
+                if not isinstance(data["deprecated"], bool):
+                    raise UserActionRequired("Category deprecated must be true or false.")
+                entry["deprecated"] = data["deprecated"]
+            entry["updated_at"] = stamp
+        catalog["revision"] += 1
+        write_manifest(_path(root), catalog)
+    return {**entry, "vocabulary_revision": catalog["revision"], "created": existing is None}
+
+
+def list_categories(project_root):
+    """Return the vocabulary with how many issues in each session reference every category."""
+    from . import records
+
+    root = trace_root(project_root)
+    catalog = load_catalog(root)
+    usage = {item["id"]: {} for item in catalog["categories"]}
+    uncategorized = 0
+    warnings = []
+    sessions = sorted(child for child in root.iterdir() if child.is_dir()) if root.exists() else []
+    for session_dir in sessions:
+        if not (session_dir / "session.json").is_file() or session_dir.is_symlink():
+            continue
+        issue_root = session_dir / "issues"
+        for issue_file in sorted(issue_root.glob("*/issue.json")) if issue_root.is_dir() else []:
+            try:
+                issue = records.load_issue(session_dir, issue_file.parent.name)
+            except UserActionRequired as exc:
+                warnings.append({"session": session_dir.name, "issue_id": issue_file.parent.name, "error": str(exc)})
+                continue
+            category = issue.get("category")
+            if category is None:
+                uncategorized += 1
+            elif category in usage:
+                usage[category][session_dir.name] = usage[category].get(session_dir.name, 0) + 1
+    return {
+        "revision": catalog["revision"],
+        "categories": [
+            {
+                **item,
+                "sessions": len(usage[item["id"]]),
+                "issues": sum(usage[item["id"]].values()),
+                "by_session": usage[item["id"]],
+            }
+            for item in catalog["categories"]
+        ],
+        "uncategorized_issues": uncategorized,
+        "warnings": warnings,
+    }

agent_tune_kit-2.3.2/agent_tune_kit/traces/progress.py

@@ -0,0 +1,95 @@
+"""Actual issue progress derived from saved records.
+
+The declared issue ``status`` is not a progress signal; only ``excluded`` is honored so that withdrawn issues do not
+stay in the backlog. Everything else comes from diagnoses, changes and verification records. The functions here do no
+I/O so the session preview and the project dashboard report the same result.
+"""
+
+from datetime import datetime
+
+# Workflow order: unfinished work first, closed outcomes last. Keys double as CSS class names.
+PROGRESS = (
+    ("pending", "待诊断"),
+    ("diagnosed", "已诊断"),
+    ("changing", "修复中"),
+    ("awaiting", "待验证"),
+    ("verifying", "验证中"),
+    ("fail", "验证失败"),
+    ("inconclusive", "无法判断"),
+    ("pass", "验证通过"),
+    ("excluded", "已排除"),
+)
+LABELS = dict(PROGRESS)
+ORDER = {key: index for index, (key, _) in enumerate(PROGRESS)}
+
+
+def parse_instant(value):
+    """Return epoch seconds for an ISO timestamp, or None when it is missing, malformed or has no timezone."""
+    try:
+        stamp = datetime.fromisoformat(value.replace("Z", "+00:00"))
+        if stamp.tzinfo is not None:
+            return stamp.timestamp()
+    except (TypeError, ValueError, AttributeError, OverflowError, OSError):
+        pass
+    return None
+
+
+def instant(record):
+    """Return the creation instant in seconds, or infinity when it is missing or has no timezone."""
+    when = parse_instant(record.get("created_at")) if isinstance(record, dict) else None
+    return float("inf") if when is None else when
+
+
+def _recency(record):
+    """Sort key where the newest known instant is largest; records with unknown time never count as newest."""
+    when = instant(record)
+    known = when != float("inf")
+    return known, when if known else 0.0, str(record.get("id", ""))
+
+
+def _result(key):
+    return {"key": key, "label": LABELS[key]}
+
+
+# Verification states whose per-issue conclusions count as an effect outcome. Failed, blocked and interrupted attempts
+# stay visible on the session page but never replace an earlier finished outcome.
+FINISHED = {"completed", "partial"}
+
+
+def issue_progress(issue, changes):
+    """Return ``{key, label}`` for one issue.
+
+    ``changes`` pairs every change linked to the issue (including a shared change owned by another issue) with all
+    verification records of that change; an entry that could not be read is passed as ``None``. The newest completed
+    or running change decides the stage, because an older verified attempt says nothing about a newer one. Within that
+    change the newest finished verification gives the outcome. An unreadable verification might be the newest one, so
+    the outcome is then unknown rather than an older result.
+    """
+    if issue.get("status") == "excluded":
+        return _result("excluded")
+    active = [(change, items) for change, items in changes if change.get("status") in {"completed", "running"}]
+    if active:
+        change, verifications = max(active, key=lambda pair: _recency(pair[0]))
+        if change["status"] == "running":
+            return _result("changing")
+        if any(not isinstance(item, dict) for item in verifications):
+            return _result("inconclusive")
+        finished = [item for item in verifications if item.get("status") in FINISHED]
+        if finished:
+            latest = max(finished, key=_recency)
+            conclusions = latest.get("conclusions")
+            conclusion = conclusions.get(issue.get("id")) if isinstance(conclusions, dict) else None
+            outcome = conclusion.get("outcome") if isinstance(conclusion, dict) else None
+            return _result(outcome if outcome in {"pass", "fail"} else "inconclusive")
+        if any(item.get("status") == "running" for item in verifications):
+            return _result("verifying")
+        return _result("awaiting")
+    return _result("diagnosed" if issue.get("diagnoses") else "pending")
+
+
+def summarize(keys):
+    """Count progress keys in workflow order, omitting nothing so callers can render stable legends."""
+    counts = dict.fromkeys(LABELS, 0)
+    for key in keys:
+        counts[key] += 1
+    return counts

{agent_tune_kit-2.3.1 → agent_tune_kit-2.3.2}/agent_tune_kit/traces/records.py

@@ -9,6 +9,7 @@ from agent_tune_kit.errors import UserActionRequired
 from agent_tune_kit.results.evidence import json_bytes, now, safe_path, write_manifest
 from agent_tune_kit.utils.files import write_text_atomic
 
+from .categories import check_issue_category
 from .segments import resolve_segments, segments_for_storage
 from .store import (
     STATES,
@@ -64,6 +65,7 @@ def load_issue(session_dir, issue_id):
         or any(not isinstance(issue.get(key), str) for key in ("title", "description", "created_at"))
         or any(not isinstance(issue.get(key), list) for key in ("notes", "history"))
         or issue.get("status") not in ISSUE_STATES
+        or ("category" in issue and not isinstance(issue["category"], str))
     ):
         raise UserActionRequired("Invalid issue identity or record structure.")
     segments = issue.get("segments", [])
@@ -171,7 +173,11 @@ def prepare_issue(session_dir, data, *, dry_run=False):
             "segments": [],
         }
     )
-    for field in ("title", "description", "evidence", "status", "notes", "selection_reason", "segments"):
+    if "category" in data:
+        data["category"] = check_issue_category(
+            directory.parent, data["category"], previous.get("category") if previous else None
+        )
+    for field in ("title", "description", "evidence", "status", "notes", "selection_reason", "segments", "category"):
         if field in data:
             issue[field] = data[field]
     if not previous:
@@ -220,6 +226,7 @@ def prepare_issue(session_dir, data, *, dry_run=False):
                     "title",
                     "description",
                     "selection_reason",
+                    "category",
                     "evidence",
                     "segments",
                     "status",
@@ -336,8 +343,9 @@ def save_diagnosis(session_dir, issue_id, text, diagnosis_id=None):
         "segments": issue.get("segments", []),
         "created_at": now(),
     }
-    if "selection_reason" in issue:
-        snapshot["selection_reason"] = issue["selection_reason"]
+    for optional in ("selection_reason", "category"):
+        if optional in issue:
+            snapshot[optional] = issue[optional]
     _refs(directory, issue["evidence"])
     for segment in snapshot["segments"]:
         _refs(directory, segment["evidence"])
@@ -407,6 +415,51 @@ def _sync_change_links(session_dir, owner, change):
             write_manifest(_issue_path(session_dir, issue_id), issue)
 
 
+def _summary_text(value):
+    return isinstance(value, str) and bool(value.strip())
+
+
+def _summary_list(value, *, allow_empty=False):
+    return isinstance(value, list) and (allow_empty or bool(value)) and all(_summary_text(item) for item in value)
+
+
+def _validate_change_summary(change):
+    if "change_summary" in change or change["status"] == "completed":
+        summary = change.get("change_summary")
+        if (
+            not isinstance(summary, list)
+            or not summary
+            or any(
+                not isinstance(item, dict)
+                or not _summary_text(item.get("what"))
+                or not _summary_text(item.get("why"))
+                or not _summary_list(item.get("files", []), allow_empty=True)
+                for item in summary
+            )
+        ):
+            raise UserActionRequired("change_summary needs actual changes with nonempty what/why and optional files.")
+    if ("remaining_verification" in change or change["status"] == "completed") and not _summary_list(
+        change.get("remaining_verification")
+    ):
+        raise UserActionRequired("remaining_verification must list specific behavior still to verify.")
+
+
+def _validate_verification_summary(result):
+    if "verification_summary" in result or result["status"] != "running":
+        summary = result.get("verification_summary")
+        if (
+            not isinstance(summary, dict)
+            or not _summary_text(summary.get("method"))
+            or not _summary_text(summary.get("sample_scope"))
+            or not _summary_list(summary.get("observations"))
+        ):
+            raise UserActionRequired("verification_summary needs method, sample_scope and nonempty observations.")
+    if ("limitations" in result or result["status"] != "running") and not _summary_list(
+        result.get("limitations"), allow_empty=True
+    ):
+        raise UserActionRequired("limitations must be a list of concise statements (empty when none are known).")
+
+
 @_locked_write
 def save_change(session_dir, issue_id, data):
     directory = Path(session_dir)
@@ -448,6 +501,7 @@ def save_change(session_dir, issue_id, data):
         raise UserActionRequired("A completed change needs actual candidate identity and a recorded diff.")
     if not previous and change["status"] != "running":
         raise UserActionRequired("Save a running change before applying the implementation.")
+    _validate_change_summary(change)
     for field in ("verifications", "schema_version", "owner_issue", "created_at"):
         if field in data and (not previous or data[field] != previous.get(field)):
             raise UserActionRequired(f"Change {field} is managed by its dedicated operation.")
@@ -517,6 +571,7 @@ def save_verification(session_dir, issue_id, change_id, data):
             raise UserActionRequired("Unverified candidate loading requires an inconclusive effect judgment.")
     if result["status"] == "completed" and not result["execution"]:
         raise UserActionRequired("Completed verification needs actual execution details.")
+    _validate_verification_summary(result)
     result.update(
         change=evidence_ref(directory, _change_path(directory, issue_id, change_id).relative_to(directory).as_posix()),
         schema_version=1,

{agent_tune_kit-2.3.1 → agent_tune_kit-2.3.2}/agent_tune_kit/traces/store.py

@@ -88,7 +88,7 @@ def read_json(path):
         if not isinstance(value, dict):
             raise ValueError
         return value
-    except (OSError, ValueError, UnicodeError):
+    except (OSError, ValueError, UnicodeError, RecursionError):
         raise UserActionRequired(f"Missing or damaged Trace record: {path.name}") from None