agent-tune-kit 2.4.1__tar.gz → 2.4.2__tar.gz

{agent_tune_kit-2.4.1 → agent_tune_kit-2.4.2}/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-tune-kit",
-  "version": "2.4.1",
+  "version": "2.4.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.4.1 → agent_tune_kit-2.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: agent-tune-kit
-Version: 2.4.1
+Version: 2.4.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
@@ -154,16 +154,18 @@ Run `atk trace --help` to check whether your CLI supports trace tuning. If the c
 - **Langfuse v4**. Use `$atk-trace-init` to record project settings and configure read-only access on first setup. Configuration references credentials by environment-variable name. Then send `$atk-trace-capture Download session <session-id> from <start time> to <end time>`.
 - **Local files**. Send `$atk-trace-capture Import traces for session <session-id> from <file path>, with source <source>`. You can also provide files with verifiable ties to the session during analysis and let detection import them. Analyze an already archived session directly.
 
-The capture step downloads or imports data. Before saving, decide which content to retain and which fields to redact. ATK adds `.atk/traces/` to the project's `.gitignore`.
+The capture step downloads or imports data. Before saving, decide which content to retain and which fields to redact. ATK checks whether Git ignores `.atk/traces/` and adds a rule to the project's `.gitignore` if needed.
+
+`$atk-trace-init` infers and saves the tuning scope from project documents and implementation; later detection, diagnosis, repair and verification use it. No manual configuration is required. You can also say "For this run, focus on this project or component." When you skip initialization, analysis fills in the necessary context and explains any unresolved boundaries.
 
 ### 2. Analyze and Review Evidence
 
 ```text
-$atk-trace-detect Check whether session <session-id> completed its task correctly. List issues, evidence, and what you did not inspect.
+$atk-trace-detect Analyze session <session-id> for issues actionable within this project. List evidence and what you did not inspect.
 $atk-visualize-trace Open the execution lanes for session <session-id> and jump from issues to the relevant trace segments and evidence fields.
 ```
 
-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.
+By default, detection retains evidence-backed issues worth pursuing that have a project mechanism, an improvement direction and a minimal verification approach; the root cause may still be uncertain. It explains out-of-scope findings and missing actionability evidence, and still calls attention to serious problems. You can explicitly request a comprehensive quality audit or investigation of a specific symptom without an existing improvement lead. No retained issues does not prove the session was correct.
 
 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.
 
@@ -176,11 +178,13 @@ Use Trace IDs to locate evidence within the session and open issue details to re
 ```text
 $atk-trace-diagnose Investigate session <session-id> and propose repair and verification plans.
 $atk-trace-diagnose Investigate ISSUE-001 in session <session-id> and propose a repair and verification plan.
-$atk-trace-optimize Implement the selected plan for ISSUE-001 in session <session-id>.
+$atk-trace-optimize Prepare a detailed implementation plan for ISSUE-001 in session <session-id>, then implement after confirmation.
 $atk-trace-verify Verify the candidate for ISSUE-001 in session <session-id> and check relevant behavior that should still work.
 ```
 
-Without specified issues, diagnosis reviews all available session traces and works through existing and newly found issues, prioritizing causes directly related to project code, configuration, tool contracts, Prompt or Skill. Findings established as unrelated to the existing implementation may be skipped with an explanation. Findings with uncertain relevance remain open for investigation. Specified issues or concrete symptoms limit the investigation scope. You can start directly with diagnosis without a separate detection invocation.
+`$atk-trace-optimize` first lists the files, exact modification locations, before/after behavior and supporting checks in Codex. Discuss adjustments in chat; only after you confirm the final version does it save the detailed plan and edit the code. Material scope expansion requires another confirmation; an unchanged confirmed plan does not. Draft discussion stays in chat by default, while the session preview shows the final plan and actual changes.
+
+Without specified issues, diagnosis reviews all available session traces, selects new issues within the tuning scope and reviews each existing issue. Findings established as unrelated to the implementation may be excluded with their reasons and history preserved; existing issues with uncertain relevance are not simply deleted. Specified issues or concrete symptoms define the investigation scope, and a temporary focus does not permanently exclude other issues. You can start directly with diagnosis without a separate detection invocation.
 
 Diagnoses and verification conclusions are saved per issue. If the evidence cannot establish which candidate loaded or whether key verification conditions were met, the verification outcome is `inconclusive`. Investigation results identify unread ranges and evidence gaps. As new issues surface, work through them individually or start another analysis with a new session trace.
 

{agent_tune_kit-2.4.1 → agent_tune_kit-2.4.2}/README.en.md

@@ -140,16 +140,18 @@ Run `atk trace --help` to check whether your CLI supports trace tuning. If the c
 - **Langfuse v4**. Use `$atk-trace-init` to record project settings and configure read-only access on first setup. Configuration references credentials by environment-variable name. Then send `$atk-trace-capture Download session <session-id> from <start time> to <end time>`.
 - **Local files**. Send `$atk-trace-capture Import traces for session <session-id> from <file path>, with source <source>`. You can also provide files with verifiable ties to the session during analysis and let detection import them. Analyze an already archived session directly.
 
-The capture step downloads or imports data. Before saving, decide which content to retain and which fields to redact. ATK adds `.atk/traces/` to the project's `.gitignore`.
+The capture step downloads or imports data. Before saving, decide which content to retain and which fields to redact. ATK checks whether Git ignores `.atk/traces/` and adds a rule to the project's `.gitignore` if needed.
+
+`$atk-trace-init` infers and saves the tuning scope from project documents and implementation; later detection, diagnosis, repair and verification use it. No manual configuration is required. You can also say "For this run, focus on this project or component." When you skip initialization, analysis fills in the necessary context and explains any unresolved boundaries.
 
 ### 2. Analyze and Review Evidence
 
 ```text
-$atk-trace-detect Check whether session <session-id> completed its task correctly. List issues, evidence, and what you did not inspect.
+$atk-trace-detect Analyze session <session-id> for issues actionable within this project. List evidence and what you did not inspect.
 $atk-visualize-trace Open the execution lanes for session <session-id> and jump from issues to the relevant trace segments and evidence fields.
 ```
 
-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.
+By default, detection retains evidence-backed issues worth pursuing that have a project mechanism, an improvement direction and a minimal verification approach; the root cause may still be uncertain. It explains out-of-scope findings and missing actionability evidence, and still calls attention to serious problems. You can explicitly request a comprehensive quality audit or investigation of a specific symptom without an existing improvement lead. No retained issues does not prove the session was correct.
 
 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.
 
@@ -162,11 +164,13 @@ Use Trace IDs to locate evidence within the session and open issue details to re
 ```text
 $atk-trace-diagnose Investigate session <session-id> and propose repair and verification plans.
 $atk-trace-diagnose Investigate ISSUE-001 in session <session-id> and propose a repair and verification plan.
-$atk-trace-optimize Implement the selected plan for ISSUE-001 in session <session-id>.
+$atk-trace-optimize Prepare a detailed implementation plan for ISSUE-001 in session <session-id>, then implement after confirmation.
 $atk-trace-verify Verify the candidate for ISSUE-001 in session <session-id> and check relevant behavior that should still work.
 ```
 
-Without specified issues, diagnosis reviews all available session traces and works through existing and newly found issues, prioritizing causes directly related to project code, configuration, tool contracts, Prompt or Skill. Findings established as unrelated to the existing implementation may be skipped with an explanation. Findings with uncertain relevance remain open for investigation. Specified issues or concrete symptoms limit the investigation scope. You can start directly with diagnosis without a separate detection invocation.
+`$atk-trace-optimize` first lists the files, exact modification locations, before/after behavior and supporting checks in Codex. Discuss adjustments in chat; only after you confirm the final version does it save the detailed plan and edit the code. Material scope expansion requires another confirmation; an unchanged confirmed plan does not. Draft discussion stays in chat by default, while the session preview shows the final plan and actual changes.
+
+Without specified issues, diagnosis reviews all available session traces, selects new issues within the tuning scope and reviews each existing issue. Findings established as unrelated to the implementation may be excluded with their reasons and history preserved; existing issues with uncertain relevance are not simply deleted. Specified issues or concrete symptoms define the investigation scope, and a temporary focus does not permanently exclude other issues. You can start directly with diagnosis without a separate detection invocation.
 
 Diagnoses and verification conclusions are saved per issue. If the evidence cannot establish which candidate loaded or whether key verification conditions were met, the verification outcome is `inconclusive`. Investigation results identify unread ranges and evidence gaps. As new issues surface, work through them individually or start another analysis with a new session trace.
 

{agent_tune_kit-2.4.1 → agent_tune_kit-2.4.2}/README.md

@@ -140,16 +140,18 @@ $atk-report
 - **Langfuse v4**。首次接入可用 `$atk-trace-init` 记录项目和只读来源配置。配置只引用凭据的环境变量名。然后发送 `$atk-trace-capture 下载 <session-id> 的会话，时间范围是 <开始时间> 到 <结束时间>`。
 - **本地文件**。发送 `$atk-trace-capture 从 <文件路径> 导入 <session-id> 的轨迹，来源是 <来源>`。也可在分析时提供可验证会话归属的文件，由分析流程导入。已归档的会话可直接分析。
 
-采集步骤负责下载或导入。保存前确认哪些正文可以留存、哪些字段需要脱敏。`.atk/traces/` 会加入项目的 `.gitignore`。
+采集步骤负责下载或导入。保存前确认哪些正文可以留存、哪些字段需要脱敏。ATK 确保 Git 忽略 `.atk/traces/`，需要时会补写项目的 `.gitignore`。
+
+`$atk-trace-init` 会根据项目说明和实现自动识别并保存调优范围，后续分析、诊断、修复和验证沿用该范围。无需手工配置；也可直接说明“本轮只看某个项目或组件”。跳过初始化时，分析流程会自动补齐必要上下文，无法确定的边界会明确说明。
 
 ### 2. 分析并查看证据
 
 ```text
-$atk-trace-detect 分析 <session-id> 的任务结果是否正确，列出问题、证据和未检查的范围。
+$atk-trace-detect 分析 <session-id>，筛选当前项目可调优的问题，列出证据和未检查的范围。
 $atk-visualize-trace 打开 <session-id> 的执行泳道，从问题跳到相关轨迹片段和证据字段。
 ```
 
-分析保留影响严重、反复出现、与你明确关注点相关，或有具体实现改进线索的问题，并说明保留理由、证据和检查范围。实现线索包括代码、配置、工具契约、Prompt 和 Skill；根因尚未确定也可进入后续诊断。轻微且无上述保留理由的观察不单独记录，没有保留问题不代表会话完全正确。
+分析默认保留有证据、值得投入，且能说明项目机制、改进方向和最小验证办法的问题；根因尚未确定也可进入后续诊断。范围外的问题说明未纳入原因，暂缺可处理性证据的问题说明缺口，严重问题仍会提示。需要全面质量审计或调查某个具体症状时可直接提出，不限于已有改进线索。没有保留问题不代表会话完全正确。
 
 采集、分析、诊断、修复和验证 Skill 在阶段结束后默认生成或更新 `.atk/traces/<session_id>/preview.html`，不自动打开浏览器。需要打开时使用 `$atk-visualize-trace`；已打开的页面在文件更新后需刷新。初始化没有会话轨迹，不生成空页面。
 
@@ -162,11 +164,13 @@ $atk-visualize-trace 打开 <session-id> 的执行泳道，从问题跳到相关
 ```text
 $atk-trace-diagnose 调查 <session-id>，给出修复和验证方案。
 $atk-trace-diagnose 调查 <session-id> 的 ISSUE-001，给出修复和验证方案。
-$atk-trace-optimize 实施 <session-id> 的 ISSUE-001 已选定的方案。
+$atk-trace-optimize 为 <session-id> 的 ISSUE-001 准备详细修改方案，确认后实施。
 $atk-trace-verify 验证 <session-id> 的 ISSUE-001 对应候选，并检查相关正常行为。
 ```
 
-未指定问题时，调查默认检查会话中可用的全部轨迹，逐项处理已记录和新发现的问题，优先定位与项目代码、配置、工具契约、Prompt 或 Skill 直接相关的原因。证据确认与现有实现无关的问题可以忽略，并说明理由。关联尚不明确的问题保留待查。指定问题或具体症状时，按指定范围调查。可以直接从调查开始，无需先单独执行检测。
+`$atk-trace-optimize` 会先在 Codex 中列出具体文件、修改位置、前后行为和配套验证。你可以在对话中调整方案；确认最终版本后，才保存详细实施方案并修改代码。实质扩大范围时会再次确认，同一已确认方案无需重复确认。讨论稿默认保留在对话中；会话预览展示最终方案与实际修改。
+
+未指定问题时，调查默认检查会话中可用的全部轨迹，按调优范围筛选新问题，并逐项审阅已记录的问题。证据确认与现有实现无关的问题可以排除，并保留理由和历史；已记录但关联尚不明确的问题不会直接删除。指定问题或具体症状时，按指定范围调查，临时收窄范围不会永久排除其他问题。可以直接从调查开始，无需先单独执行检测。
 
 诊断和验证结论分别按问题保存。证据不足以确认实际加载的候选或关键验证条件时，验证效果记为 `inconclusive`（无法判断）。调查结果会说明未检查的范围和证据缺口。后续发现新的问题，可继续按问题处理，或用新会话的轨迹开始下一次分析。
 

{agent_tune_kit-2.4.1 → agent_tune_kit-2.4.2}/agent_tune_kit/__init__.py

@@ -1,3 +1,3 @@
 """Agent Tune Kit package."""
 
-__version__ = "2.4.1"
+__version__ = "2.4.2"

{agent_tune_kit-2.4.1 → agent_tune_kit-2.4.2}/agent_tune_kit/traces/store.py

@@ -4,6 +4,7 @@ import hashlib
 import json
 import os
 import re
+import subprocess
 import uuid
 from contextlib import contextmanager
 from pathlib import Path
@@ -11,7 +12,7 @@ from urllib.parse import urlsplit
 
 from agent_tune_kit.errors import UserActionRequired
 from agent_tune_kit.results.evidence import digest_file, json_bytes, now, safe_path, write_manifest
-from agent_tune_kit.utils.files import write_text_atomic
+from agent_tune_kit.utils.files import atomic_text_writer, write_text_atomic
 
 from . import archive
 
@@ -97,16 +98,41 @@ def trace_root(project_root):
     return safe_path(project, ".atk/traces")
 
 
+def _trace_git_ignored(project):
+    try:
+        result = subprocess.run(
+            ["git", "check-ignore", "-q", "--no-index", "--", ".atk/traces/"],
+            cwd=project,
+            capture_output=True,
+            env={**os.environ, "LC_ALL": "C"},
+            check=False,
+        )
+    except FileNotFoundError:
+        return None
+    if result.returncode in {0, 1}:
+        return result.returncode == 0
+    if result.stderr.startswith((b"fatal: not a git repository", b"fatal: this operation must be run in a work tree")):
+        return None
+    raise UserActionRequired("Git could not check the Trace ignore rules. Check Git status in the project.")
+
+
 def ensure_workspace(project_root):
     project = Path(project_root).resolve()
     root = trace_root(project)
     ignore = safe_path(project, ".gitignore")
-    text = ignore.read_text(encoding="utf-8") if ignore.exists() else ""
-    # An explicit final rule also protects archives after a previous negated rule.
-    rule = "/.atk/traces/"
-    changed = not text.rstrip().endswith(rule)
-    if changed:
-        write_text_atomic(ignore, text + ("\n" if text and not text.endswith("\n") else "") + rule + "\n")
+    ignored = _trace_git_ignored(project)
+    changed = False
+    if ignored is not True:
+        text = ignore.read_bytes().decode("utf-8") if ignore.exists() else ""
+        rule = "/.atk/traces/"
+        changed = text.rstrip("\r\n").rsplit("\n", 1)[-1] != rule
+        if changed:
+            newline = "\r\n" if "\r\n" in text else "\n"
+            separator = newline if text and not text.endswith("\n") else ""
+            with atomic_text_writer(ignore, newline="") as handle:
+                handle.write(text + separator + rule + newline)
+        if ignored is False and not _trace_git_ignored(project):
+            raise UserActionRequired("Git still does not ignore .atk/traces/. Resolve the conflicting ignore rules.")
     root.mkdir(mode=0o700, parents=True, exist_ok=True)
     return root, changed
 

{agent_tune_kit-2.4.1 → agent_tune_kit-2.4.2}/docs/shared-versioning-and-confirmation.md

@@ -203,7 +203,9 @@ CSV-only judgments remain supported. Integrity is distinct from coverage, source
 
 ## Uncertainty confirmation pattern
 
-Each Skill should inspect repository files first, state the evidence it found, and ask a concise confirmation question only when acting without confirmation would likely corrupt data, write the wrong files, or misinterpret evaluation results.
+Trace optimization additionally follows the [implementation plan confirmation workflow](trace-tuning.md): prepare the concrete file-level plan in chat, obtain confirmation, then save the final plan and modify the implementation. This applies even to reversible implementation edits; reuse an unchanged plan already confirmed in the conversation.
+
+Outside that Trace implementation confirmation, each Skill should inspect repository files first, state the evidence it found, and ask a concise confirmation question only when acting without confirmation would likely corrupt data, write the wrong files, or misinterpret evaluation results.
 
 Ask before proceeding when any of these remain unresolved after inspection:
 

{agent_tune_kit-2.4.1 → agent_tune_kit-2.4.2}/docs/trace-tuning.md

@@ -8,15 +8,15 @@ Use the seven independent Skills in your Agent project:
 
 | Skill | Delivers |
 | --- | --- |
-| `$atk-trace-init` | Project context, supported sources and specific missing facts |
+| `$atk-trace-init` | Automatically inferred tuning boundary, project context, supported sources and specific missing facts |
 | `$atk-trace-capture` | A retained session snapshot; stops after acquisition |
-| `$atk-trace-detect` | Evidence-backed issues and actual inspection coverage |
+| `$atk-trace-detect` | Evidence-backed, actionable tuning issues and actual inspection coverage |
 | `$atk-trace-diagnose` | Per-issue root-cause explanations and repair/verification plans, reviewing all session issues by default with an implementation focus |
 | `$atk-trace-optimize` | An actual repair, frozen adopted diagnosis and candidate identity |
 | `$atk-trace-verify` | Actual execution, candidate loading and per-issue effect judgments |
 | `$atk-visualize-trace` | A self-contained offline HTML browser from existing records |
 
-A known problem can go directly to diagnosis after binding its session and issue. Without specified issues or symptoms, diagnosis reviews all available session traces, handles existing and newly found issues, and saves each diagnosis separately. It prioritizes causes directly related to the project implementation and may skip findings established as unrelated, recording reasons and coverage gaps. Unknown attribution remains an open question. Detection invoked on its own normally stops at the issue list. An explicit continuous investigation/repair request can proceed within its authorized scope without fixed per-stage confirmations. Capture, detect, diagnose, optimize and verify Skills generate/update the session preview at stage end without opening a browser, including zero-issue and partial sessions. Init has no bound session and does not generate an empty preview.
+A known problem can go directly to diagnosis after binding its session and issue. Without specified issues or symptoms, diagnosis reviews all available session traces, applies the tuning boundary to newly found issues, reviews existing issues without silently discarding them, and saves each diagnosis separately. It may skip findings established as outside the effective boundary, recording reasons and coverage gaps. Unknown attribution remains an open question. Detection invoked on its own normally stops at the issue list. An explicit continuous investigation/repair request can proceed through investigation and implementation preparation; optimize obtains confirmation of the concrete plan before saving its final version and editing target files. An unchanged plan already confirmed in chat needs no repeated confirmation. Capture, detect, diagnose, optimize and verify Skills generate/update the session preview at stage end without opening a browser, including zero-issue and partial sessions. Init has no bound session and does not generate an empty preview.
 
 Every session command takes `--session-id`, optional `--source <json-file>` to disambiguate, `--project-root` (default `.`), and `--json`. JSON-taking arguments such as `--ref`, `--source`, `--config`, `--data`, `--association` and `--retention` receive a JSON file path, not inline JSON text. Save a returned reference object to a file before using it with `show`. Trace IDs locate evidence inside a session; they are not independent import/download entry points. Missing native session identity or verifiable association does not create a replacement identity.
 
@@ -47,7 +47,7 @@ Use the actual origin/project namespace rather than inferring one from a filenam
 atk trace init --config /path/to/source-config.json --project-file /path/to/project-notes.md --json
 ```
 
-`project.md` records purpose, relevant code/Prompt/tool locations, known run/verification entry points, sources and unknowns. Existing human notes are preserved; the initial generated placeholder can be filled, while a conflicting supplied human document requires reconciling confirmed differences rather than overwriting it. Explicit configuration updates recursively preserve other manual fields, including nested entries. Session metadata records the source and latest import scope.
+`project.md` records the [tuning boundary](#tuning-boundary), relevant code/Prompt/tool locations and known run/verification entry points. The init Skill researches and writes this context; the bare CLI command only creates a placeholder when no project notes are supplied. Existing human notes are preserved; the initial generated placeholder can be filled, while a conflicting supplied human document requires reconciling confirmed differences rather than overwriting it. Explicit configuration updates recursively preserve other manual fields, including nested entries. Session metadata records the source and latest import scope.
 
 For Langfuse v4, configure the actual deployment and credential references:
 
@@ -69,6 +69,28 @@ For Langfuse v4, configure the actual deployment and credential references:
 
 Provide credentials through the referenced environment variables or an existing secure environment; never put their values in configuration, archives, terminal output or HTML. A configured source or installed SDK does not establish server version, connection success or replay readiness. Initialization is local; capture tests the real source. Remote capture requires an explicit time range, from configuration `from_time`/`to_time` or command arguments; no recent-days range is assumed.
 
+## Tuning boundary
+
+The host infers the default tuning boundary from the user's requirements, project responsibilities and implementation entry points; users need not fill out a scope form or approve routine inference. Persist it in `.atk/traces/project.md` in the user's language, covering these five items:
+
+- **Goal:** which Agent behavior the project is intended to improve.
+- **Included:** projects and mechanisms that support this goal, such as runtime code, configuration, tool contracts, Prompt, Skill or recovery behavior.
+- **Excluded:** established exclusions and their reasons, distinguishing user task artifacts from the implementation that produces them.
+- **Unknown:** unresolved responsibility, availability or controllability; missing evidence is not an exclusion.
+- **Sources:** the user requirements, project documents and implementation locations supporting those judgments.
+
+Reference stable IDs and paths in `projects.json` rather than copying the project registry. Repository presence, editability, a runtime location, `source.project` or `--project-root` does not establish tuning relevance or grant modification authority. An external failure can still have an in-scope handling defect; inspect the relevant call or recovery mechanism before treating it as outside scope.
+
+Before init, detect, diagnose, optimize or verify makes scope decisions, read the existing `project.md`, optional `.atk/context.md`, the project registry and relevant project entry documents. Preserve human constraints. Fill missing, placeholder or incomplete boundary context in the current workflow using available evidence. For a new or placeholder `project.md`, save through `atk trace init --project-file <markdown-file> --json` to preserve workspace ignore rules; reconcile existing human notes with targeted edits. This reuses the CLI without requiring a separate init Skill invocation. Ask only when a material ambiguity cannot be resolved from the request or available sources. A missing checkout or unverified historical version stays explicit and does not establish irrelevance.
+
+The current user request determines the effective scope and can override saved defaults. A temporary focus applies to that invocation and subsequent work on its selected issues; do not silently persist it as the new project default. Reconcile only affected default notes when the user requests a lasting change or reliable project evidence updates an inferred responsibility; preserve unrelated notes and explicit user restrictions. Explain unresolved conflicts before dependent work. Report the effective scope and important unknowns without imposing an extra confirmation step.
+
+In ordinary project tuning, apply the [detect selection policy](../skills/atk-trace-detect/SKILL.md#which-findings-to-retain) before creating an Issue. A retained tuning candidate needs an evidence-informed connection to an in-scope mechanism, a plausible intervention direction and a smallest check that can distinguish explanations or assess improvement. Neither a proven root cause nor a successful repair is required. A task-artifact correction or generic reminder alone does not establish project actionability. Seriousness and recurrence prioritize findings; they do not supply a missing project mechanism. Honor explicitly requested symptoms and comprehensive quality audits even without an implementation lead, describing that purpose and the actionability gap rather than presenting every finding as a tuning candidate.
+
+Record the effective boundary, overrides and their sources in the existing detection `scope`, alongside actual inspected and unread material. Put unresolved boundary evidence in `gaps`; briefly explain established exclusions and surface serious unresolved findings in the coverage and delivery. Subsequent diagnosis, repair and verification read this recorded scope as well as current project context and the user's request. Explain any scope change, preserve prior records, and check that causes, actual modification locations and verification targets remain aligned. This scope description is not a session-level union of Issue project associations.
+
+Capture and visualization consult existing boundary context when interpreting the request, but do not require boundary initialization, narrow retained evidence or reclassify saved Issues because of it. Their acquisition, retention and display contracts remain intact. The boundary is a host judgment contract using existing files and fields, not a CLI semantic validator.
+
 ## Capture or import
 
 Download a declared session range using Langfuse's read-only Observations API v2:
@@ -145,14 +167,14 @@ The following are host-produced records, not automatic CLI diagnoses. Each `--da
 | --- | --- |
 | `atk trace issue --session-id ID --data FILE --json` | `title`, `description`; optional `selection_reason` (nonempty string), `category` (a project category ID), `project_links` (associated projects with reasons and evidence), `segments`, top-level `evidence`, stable `id`, `status`, `notes`; updates include `revision`. `--dry-run` validates and reports covered nodes without writing |
 | `atk trace category --list --json` / `atk trace category --data FILE --json` | Project-level, no Session ID. `--list` returns the vocabulary, its `revision` and per-session usage. `--data` adds or revises one category: `id`, `name`, `definition`, optional `deprecated`, and the current vocabulary `revision` once the vocabulary exists |
-| `atk trace detect --session-id ID --data FILE --json` | nonempty `scope` describing inspected and unread material, actual `status`, `gaps: []`; inputs bind current file digests; updates include `id`/`revision` |
+| `atk trace detect --session-id ID --data FILE --json` | nonempty `scope` describing the effective tuning boundary, overrides and inspected/unread material, actual `status`, `gaps: []`; inputs bind current file digests; updates include `id`/`revision` |
 | `atk trace diagnose --session-id ID --issue-id ISSUE --file MD --expected-revision N --json` | Markdown combining observed issue/evidence, facts/hypotheses, cause, repair/verification plan and gaps; use the latest Issue revision after saving project associations; optional `--diagnosis-id`. Markdown may cite `ISSUE-001/S2` |
 | `atk trace change --session-id ID --issue-id ISSUE --data FILE --json` | Begin with `status: "running"`, nonempty `before` identifying actual baseline and adopted `diagnoses`; finish with same `id`/`revision`, actual `candidate`, `diff`, `checks: []`, `change_summary`, `remaining_verification` and `status: "completed"` |
 | `atk trace verify --session-id ID --issue-id OWNER --change-id CHANGE --data FILE --json` | Begin with actual intended `execution` and `status: "running"`; finish same `id`/`revision`, actual status, `candidate_loaded`, `loading_evidence`, `execution`, `verification_summary`, `conclusions`, `limitations`, `evidence` |
 
-Detection selects findings before creating Issues. The selection policy lives in [atk-trace-detect](../skills/atk-trace-detect/SKILL.md#which-findings-to-retain). Detection writes `selection_reason` to explain why an issue warrants investigation. The title and description first state a concrete, evidence-backed mismatch understandable without the trace, then add impact/recovery, relevant recurrence, implementation leads and unresolved questions. The [description guidance](../skills/atk-trace-detect/SKILL.md#write-a-recognizable-problem) defines the host's semantic check. The CLI validates record shape, not semantic quality. The reason remains optional for compatibility; omission during an update preserves it. Revisions retain the previous reason in history, and new diagnoses snapshot the reason when present.
+Detection selects findings before creating Issues using the [effective tuning boundary](#tuning-boundary) and the [atk-trace-detect selection policy](../skills/atk-trace-detect/SKILL.md#which-findings-to-retain). Detection writes `selection_reason` to explain the issue's value, in-scope mechanism, intervention direction and smallest discriminating check, or the explicit audit/symptom request that warrants retaining a finding without that lead. The title and description first state a concrete, evidence-backed mismatch understandable without the trace, then add impact/recovery, relevant recurrence, implementation leads and unresolved questions. The [description guidance](../skills/atk-trace-detect/SKILL.md#write-a-recognizable-problem) defines the host's semantic check. The CLI validates record shape, not semantic quality. The reason remains optional for compatibility; omission during an update preserves it. Revisions retain the previous reason in history, and new diagnoses snapshot the reason when present.
 
-[Diagnosis](../skills/atk-trace-diagnose/SKILL.md) continues from those questions without treating selection as proof of a cause. Its description identifies the problem independently, each cause explains that problem, and each fix addresses a cause or uncertainty. Scope changes reconcile the live issue while preserving history. An independent defect without an established causal link is recorded separately. Final summaries draw from the saved explanations. Existing issues skipped as unrelated to the implementation receive `status: excluded` with an evidence-backed reason appended to their `notes`, preserving evidence and history. New findings already established as unrelated need only a brief exclusion reason in review coverage. A rejected hypothesis or missing evidence alone is insufficient for exclusion. Explicitly requested issues receive an attribution explanation even when unrelated. Coverage records the focus, selection scope and gaps. Zero retained issues is not a correctness verdict.
+[Diagnosis](../skills/atk-trace-diagnose/SKILL.md) continues from those questions without treating selection as proof of a cause. Its description identifies the problem independently, each cause explains that problem, and each fix addresses a cause or uncertainty. Scope changes reconcile the live issue while preserving history. An independent defect without an established causal link follows the same selection policy before being recorded separately. Final summaries draw from the saved explanations. Existing issues skipped as unrelated to the implementation receive `status: excluded` with an evidence-backed reason appended to their `notes`, preserving evidence and history; a temporary focus does not permanently exclude other issues. New findings established as outside scope need only a brief exclusion reason in review coverage. Findings without enough actionability evidence remain coverage gaps, with serious unresolved findings surfaced explicitly. A rejected hypothesis, missing evidence or empty `project_links` alone is insufficient to exclude an existing issue. Explicitly requested issues receive an attribution explanation even when unrelated. Coverage records the focus, selection scope and gaps. Zero retained issues is not a correctness verdict.
 
 ### Issue categories
 
@@ -226,6 +248,12 @@ Segments are ordered by their scoped observations' start times. For a final answ
 
 Issue IDs are stable within the session. Omitting an old issue during new detection does not resolve it. Exclusion/correction needs a reason while preserving history. Detection coverage includes zero findings, checked/unread nodes, partial work and interruptions; an empty issue list does not prove correctness. Re-capture creates new unanalyzed material rather than rewriting previous coverage.
 
+Optimize prepares and revises the file-level implementation plan in Codex chat. Include project/file/symbol or configuration/Skill section, concrete edits, before/after behavior, causal reason, necessary supporting changes and checks with pass criteria. Present the consolidated plan for confirmation. Drafts and review discussion stay in chat unless explicitly requested as a saved draft. General repair authorization and saved drafts do not confirm an undisclosed plan.
+
+After confirmation, save exactly the agreed final plan as `### 详细实施方案` / `### Detailed implementation plan` under the diagnosis's third heading, preserving its description, causes and limits. Create a new immutable diagnosis snapshot (or reuse an identical one), then bind its path/digest in the running change before implementation. Saving failure prevents implementation. Shared repairs use one combined confirmed scope and one change binding each target's diagnosis. No approval metadata, progress state or review UI is added. A saved plan proves neither confirmation nor execution. The preview shows the detailed plan in diagnosis and actual edits in change summaries; the dashboard retains existing progress semantics.
+
+Material scope changes require confirming the revised complete plan before additional edits and saving a new diagnosis. Routine choices within scope and unrelated repository changes need no new confirmation. If implementation has started, preserve actual progress and end that attempt before starting a new change bound to the revised diagnosis; never overwrite frozen references or blindly repeat work. On resumption, inspect Git/files and records and establish confirmation from the conversation. Delivery compares actual changes against the confirmed plan, including unimplemented items.
+
 Diagnoses are immutable Markdown and include an issue snapshot (including segments when present). Adopted diagnoses bind path and digest. Change `target_issues` may list several issues and `diagnoses` maps each target issue to its adopted reference. Save a shared modification once under its owner issue; the other issues explicitly reference that owner-relative change path. Completed candidates are frozen; a new diagnosis/candidate is a new record.
 
 A verification conclusion has this shape:
@@ -380,7 +408,7 @@ No private trace, credential, company gateway or business example is bundled. Au
 
 ## Projects and scope
 
-Use `atk trace project --list --json` to resolve existing project IDs, names, established abbreviations and workspace-relative paths. `--project-root` remains the archive workspace; it is not an attribution target. Prefer user-specified projects for investigation, then follow evidence into other projects. Never invent abbreviations. A caller, runtime location or proposed fix alone does not establish a project association.
+Use `atk trace project --list --json` to resolve existing project IDs, names, established abbreviations and workspace-relative paths. `--project-root` remains the archive workspace; it is not an attribution target. Prefer user-specified projects for investigation; follow cross-project evidence without silently broadening the effective tuning boundary. Never invent abbreviations. A caller, runtime location or proposed fix alone does not establish a project association.
 
 Read the applicable project's README, AGENTS.md and CLAUDE.md (including actual filename case variants) before investigation or modification. Keep project IDs and workspace-relative paths consistent. State inspected and uninspected scope, proposed versus actual modifications, candidate versions and per-project loading evidence. When modifying another project, explain the tradeoff and remaining limits. Do not update parent gitlinks without explicit authorization.
 

{agent_tune_kit-2.4.1 → agent_tune_kit-2.4.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "agent-tune-kit"
-version = "2.4.1"
+version = "2.4.2"
 description = "Local Codex plugin for iterative Agent tuning with guided Skills, reusable runner templates, versioned results, and static validation."
 readme = "README.en.md"
 requires-python = ">=3.11"

{agent_tune_kit-2.4.1 → agent_tune_kit-2.4.2}/scripts/check-release.py

@@ -141,11 +141,11 @@ def require_uv() -> str:
 
 
 def run_static_python_checks() -> None:
-    run(["uv", "run", "ruff", "format", "."])
-    run(["uv", "run", "ruff", "check", "--fix", "."])
-    run(["uv", "run", "ruff", "format", "--check", "."])
-    run(["uv", "run", "ruff", "check", "."])
-    run(["uv", "run", "python", "-m", "py_compile", *PYTHON_FILES], timeout=120)
+    run(["uv", "run", "--locked", "ruff", "format", "."])
+    run(["uv", "run", "--locked", "ruff", "check", "--fix", "."])
+    run(["uv", "run", "--locked", "ruff", "format", "--check", "."])
+    run(["uv", "run", "--locked", "ruff", "check", "."])
+    run(["uv", "run", "--locked", "python", "-m", "py_compile", *PYTHON_FILES], timeout=120)
 
 
 def read_project_identity() -> ProjectIdentity:
@@ -403,10 +403,10 @@ def main() -> int:
     assert_versions_aligned(identity)
     clean_generated_artifacts()
     try:
-        run(["uv", "sync"], timeout=180)
+        run(["uv", "sync", "--locked"], timeout=180)
         run_static_python_checks()
-        run(["uv", "run", "python", "scripts/validate_skill_pack.py"], timeout=120)
-        run(["uv", "run", "pytest", "-q"], timeout=240)
+        run(["uv", "run", "--locked", "python", "scripts/validate_skill_pack.py"], timeout=120)
+        run(["uv", "run", "--locked", "pytest", "-q"], timeout=240)
         with tempfile.TemporaryDirectory(prefix="atk-release-check-") as tmp:
             temp_dir = Path(tmp)
             wheel, sdist = build_distributions(temp_dir / "dist", identity)

{agent_tune_kit-2.4.1 → agent_tune_kit-2.4.2}/scripts/publish-pypi.sh

@@ -6,4 +6,4 @@ cd "$(dirname "${BASH_SOURCE[0]}")/.."
 # Credential handling lives in publish-release.py; it accepts UV_PUBLISH_TOKEN
 # or a matching ~/.pypirc section for the target repository.
 export UV_NO_CONFIG=1
-exec uv run python scripts/publish-release.py --repository pypi --publish
+exec uv run --locked python scripts/publish-release.py --repository pypi --publish

{agent_tune_kit-2.4.1 → agent_tune_kit-2.4.2}/scripts/publish-release.py

@@ -292,7 +292,7 @@ def main() -> int:
         for artifact in artifacts:
             print(f"- {artifact.relative_to(REPO_ROOT)}")
         print(
-            f"To publish: UV_PUBLISH_TOKEN='pypi-...' uv run python scripts/publish-release.py --repository {target.name} --publish"
+            f"To publish: UV_PUBLISH_TOKEN='pypi-...' UV_NO_CONFIG=1 uv run --locked python scripts/publish-release.py --repository {target.name} --publish"
         )
         return 0
 

{agent_tune_kit-2.4.1 → agent_tune_kit-2.4.2}/scripts/release-version.py

@@ -87,9 +87,9 @@ def release_commands(
     commands = [
         ["git", "status", "--porcelain"],
         ["uv", "lock"],
-        ["uv", "run", "pytest"],
-        ["uv", "run", "atk", "--version"],
-        ["uv", "run", "python", "scripts/validate_skill_pack.py"],
+        ["uv", "run", "--locked", "pytest"],
+        ["uv", "run", "--locked", "atk", "--version"],
+        ["uv", "run", "--locked", "python", "scripts/validate_skill_pack.py"],
         ["git", "diff", "--check"],
         ["git", "add", *RELEASE_FILES],
         ["git", "commit", "-m", f"Prepare Agent Tune Kit {version} release"],
@@ -101,6 +101,7 @@ def release_commands(
         publish_command = [
             "uv",
             "run",
+            "--locked",
             "python",
             "scripts/publish-release.py",
             "--repository",
@@ -130,9 +131,9 @@ def commit_message(version: str) -> list[str]:
         "-m",
         "Directive: use scripts/release-version.sh for future version bumps so tag, push, and publish steps remain consistent.",
         "-m",
-        "Tested: uv run pytest; uv run atk --version; git diff --check",
+        "Tested: uv run --locked pytest; uv run --locked atk --version; git diff --check",
         "-m",
-        "Not-tested: uv run python scripts/validate_skill_pack.py may report known README/plugin documentation phrase gaps unless strict mode is used.",
+        "Not-tested: uv run --locked python scripts/validate_skill_pack.py may report known README/plugin documentation phrase gaps unless strict mode is used.",
         "-m",
         "Co-authored-by: OmX <omx@oh-my-codex.dev>",
     ]
@@ -190,13 +191,13 @@ def main() -> int:
         print(f"- {path}")
 
     run(["uv", "lock"])
-    run(["uv", "run", "pytest"])
-    version_output = capture(["uv", "run", "atk", "--version"])
+    run(["uv", "run", "--locked", "pytest"])
+    version_output = capture(["uv", "run", "--locked", "atk", "--version"])
     expected_version_output = f"agent-tune-kit {args.version}"
     if version_output != expected_version_output:
         raise ReleaseVersionError(f"unexpected CLI version output: {version_output!r}")
 
-    skill_pack = run(["uv", "run", "python", "scripts/validate_skill_pack.py"], check=False)
+    skill_pack = run(["uv", "run", "--locked", "python", "scripts/validate_skill_pack.py"], check=False)
     if skill_pack.returncode != 0 and args.strict_skill_pack:
         raise ReleaseVersionError("scripts/validate_skill_pack.py failed in strict mode")
     if skill_pack.returncode != 0:
@@ -213,6 +214,7 @@ def main() -> int:
         publish_command = [
             "uv",
             "run",
+            "--locked",
             "python",
             "scripts/publish-release.py",
             "--repository",

agent_tune_kit-2.4.2/scripts/release-version.sh

@@ -0,0 +1,7 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+cd "$(dirname "${BASH_SOURCE[0]}")/.."
+
+export UV_NO_CONFIG=1
+exec uv run --locked python scripts/release-version.py "$@"

{agent_tune_kit-2.4.1 → agent_tune_kit-2.4.2}/scripts/validate_skill_pack.py

@@ -125,7 +125,7 @@ REQUIRED_FILES += TRACE_SKILL_FILES + [
 ]
 
 PER_FILE_PHRASES = {
-    ".codex-plugin/plugin.json": ['"name": "agent-tune-kit"', '"version": "2.4.1"', '"skills": "./skills/"'],
+    ".codex-plugin/plugin.json": ['"name": "agent-tune-kit"', '"version": "2.4.2"', '"skills": "./skills/"'],
     "skills/atk-dataset/SKILL.md": [
         "## Purpose",
         "## Inputs",

{agent_tune_kit-2.4.1 → agent_tune_kit-2.4.2}/skills/atk-trace-capture/SKILL.md

@@ -21,7 +21,7 @@ Session identity, local path, actual trace/observation counts, selector/field sc
 
 ## Workflow
 
-1. Resolve the session/source and inspect existing status before retrying. A running/interrupted capture may have performed requests; verify retained facts before repeating. Analysis of saved data does not require a new capture.
+1. Read the shared [tuning boundary](../../docs/trace-tuning.md#tuning-boundary) rules and existing `.atk/traces/project.md` when present. Capture follows the requested acquisition scope, not tuning eligibility: keep authorized evidence for outside or unknown components, and do not require init or boundary completion. Resolve the session/source and inspect existing status before retrying. A running/interrupted capture may have performed requests; verify retained facts before repeating. Analysis of saved data does not require a new capture.
 2. Reuse `.atk/traces/config.json` or an explicit config. Missing dataset, runner or Agent runtime is irrelevant. Ask only for necessary source settings; never invent a recent-days window or infer server version from an SDK/export wrapper.
 3. Use `atk trace fetch --session-id <id> --json`, optionally `--config <file> --from-time <timestamp> --to-time <timestamp>`. The CLI handles Session filtering, cursor pagination and updates by native Trace ID. Existing issues survive reimport.
 4. For local material use `atk trace import --session-id <id> --source <source-json> --path <file> --json`, repeating `--path`. Supply `--association <json>` only with sourced association proof; use `--retention <json>` as needed. A supplied ID or directory name alone is not ownership proof. Import necessary ATK execution evidence with original identities/provenance, not an entire project.