release: ship aet v1.4.0 trace artifacts

Author: yjw

.github/workflows/ci.yml

@@ -13,4 +13,4 @@ jobs:
       - run: uv run --no-editable --reinstall-package agent-engineering-toolkit python -m unittest discover -s tests -v
       - run: uv run --no-editable aet audit . --strict --format json --output .aet/evidence/audit.json
       - run: uv build
-      - run: uv run --isolated --with dist/agent_engineering_toolkit-1.3.0-py3-none-any.whl aet --version
+      - run: uv run --isolated --with dist/agent_engineering_toolkit-1.4.0-py3-none-any.whl aet --version

CHANGELOG.md

@@ -2,6 +2,24 @@
 
 ## Unreleased
 
+## 1.4.0 — 2026-07-12
+
+- Added repeatable `aet trace --artifact <relative-path>` for explicitly
+  declared UTF-8 reports generated by a traced command, including pytest JUnit
+  XML. AET redacts report content before persisting it and embeds the redacted
+  artifact plus SHA-256 in the portable Evidence Pack.
+- Trace rejects absolute/outside-workspace artifact declarations. A missing,
+  non-regular, undecodable, or unredactable declared report is recorded as
+  `UNKNOWN`; a successful command then returns a non-zero Trace exit without
+  rewriting the child command's successful execution result. Such a Trace also
+  cannot advance a Run to `PROVEN` or mark a bound proof as complete.
+- Added regression coverage for redacted report capture, portable-pack
+  inclusion, missing artifacts, and outside-workspace rejection. This closes
+  the evidence gap found while tracing Invest-Vault's pytest delivery proof.
+- Constrained optional pytest discovery to AET's first-party `tests/` directory
+  so nested dogfood repositories are not accidentally collected into AET's
+  own test report.
+
 ## 1.3.0 — 2026-07-12
 
 - Added an optional, deterministic **Context Manifest**: `aet context discover`

PROJECT_MEMORY.md

@@ -307,3 +307,24 @@ deterministic core.
   path, as well as direct supersession. The v1.3 release gate requires 27 unit
   tests, strict self-audit, reviewed intent, a proof-bound Trace/Evidence Pack,
   and an isolated wheel smoke test.
+
+## v1.4.0 implementation and release candidate — 2026-07-12
+
+- Invest-Vault dogfood confirmed that v1.3 Trace successfully ran its complete
+  pytest process; the gap was report portability, not subprocess execution.
+  Trace held stdout/stderr but not a test framework's generated report.
+- Added explicit `trace --artifact <relative-path>` capture. It is not a
+  report-file guesser: only a declared regular UTF-8 file under the workspace
+  is captured, redacted, hashed, and embedded into Trace plus Evidence Pack.
+- A missing, outside-root, non-regular, undecodable, or unredactable declared
+  artifact is `UNKNOWN`. AET returns non-zero after an otherwise successful
+  child command, while preserving the child's `execution: PASS` fact.
+- A real pytest dogfood trace initially exposed unrelated collection of nested
+  `work/dogfood` repositories. `pyproject.toml` now limits optional pytest
+  discovery to AET's own `tests/` directory.
+- This adopts the useful Harness Engineering idea of durable, inspectable
+  filesystem artifacts and failure traces. It explicitly rejects the article's
+  broader runtime, autonomous optimization, and generic-memory directions.
+- The v1.4 release gate requires 30 unit tests, a real pytest JUnit artifact
+  dogfood trace/pack, strict self-audit, reviewed intent, a proof-bound release
+  Evidence Pack, and an isolated wheel smoke test.

README.md

@@ -39,7 +39,7 @@ what was declared, what was explicitly executed, and what remains unknown.
 | --- | --- | --- |
 | Can this agent safely follow the repository instructions and Skills? | `aet audit` | Markdown, JSON, or SARIF findings with locations and fixes. |
 | Is the diff inside the human-approved intent? | `aet review` | An intent-gate report for path budget, allowed paths, and declared proofs. |
-| Did the command run against the reviewed workspace? | `aet trace` + `aet evidence pack` | A redacted execution record plus proof and workspace-snapshot bindings. |
+| Did the command run against the reviewed workspace, and did it produce its declared test report? | `aet trace --artifact` + `aet evidence pack` | A redacted execution record, explicitly captured report, plus proof and workspace-snapshot bindings. |
 | What delivery stage is this evidence chain in, and did it become stale? | `aet run` | An optional append-only Run Manifest with explicit lifecycle states. |
 | Which local instructions/references were available, and what was only claimed as read? | `aet context` | A hash-bound Context Manifest; read declarations are explicit attestations. |
 | Which project decisions have local sources, and which records supersede them? | `aet decision` | A source-hash Decision Ledger with verification and supersession history. |
@@ -165,11 +165,11 @@ AET deliberately reports a status matrix rather than a synthetic “agent trust
 score.” Its only numeric model, `aet triage`, exposes its weights and is used
 only to order remediation work.
 
-| Release check | v1.3.0 result | How to reproduce |
+| Release check | v1.4.0 result | How to reproduce |
 | --- | --- | --- |
-| Regression suite | 27 tests passed | `uv run --no-editable --reinstall-package agent-engineering-toolkit python -m unittest discover -s tests -v` |
+| Regression suite | 30 tests passed | `uv run --no-editable --reinstall-package agent-engineering-toolkit python -m unittest discover -s tests -v` |
 | Strict self-audit | 0 `FAIL`, 0 `UNKNOWN` in the configured production Skill scope | `uv run --no-editable aet audit . --strict` |
-| Intent review | Release diff must stay inside the reviewed contract | `uv run --no-editable aet review . --base v1.1.0 --intent aet.intent.json` |
+| Intent review | Release diff must stay inside the reviewed contract | `uv run --no-editable aet review . --base v1.3.0 --intent aet.intent.json` |
 | Distribution smoke | Wheel built and invoked in an isolated environment | `uv build` then install the wheel shown below |
 | Delivery automation | CI on `main`, plus tag-driven GitHub Release workflow | [Actions](https://github.com/AdvancingTitans/agent-engineering-toolkit/actions) |
 
@@ -185,7 +185,7 @@ what AET does and does not claim.
 Install the published GitHub Release wheel with [uv](https://docs.astral.sh/uv/):
 
 ```bash
-uv tool install https://github.com/AdvancingTitans/agent-engineering-toolkit/releases/download/v1.3.0/agent_engineering_toolkit-1.3.0-py3-none-any.whl
+uv tool install https://github.com/AdvancingTitans/agent-engineering-toolkit/releases/download/v1.4.0/agent_engineering_toolkit-1.4.0-py3-none-any.whl
 aet --version
 ```
 
@@ -265,6 +265,28 @@ Trace is opt-in, requires `--`, records only the explicit command, and stores
 redacted excerpts plus hashes. The static viewer needs no server or external
 assets.
 
+### Capture a declared pytest report
+
+`trace` never guesses which files a command wrote. When a test report matters
+to the delivery claim, declare the workspace-relative path explicitly. AET
+captures the completed UTF-8 text report only after the command exits, redacts
+it before persistence, and embeds it in the portable Evidence Pack.
+
+```bash
+aet trace --artifact reports/junit.xml --output .aet/evidence/pytest-trace.json -- \
+  pytest --junitxml=reports/junit.xml
+aet evidence pack --trace .aet/evidence/pytest-trace.json \
+  --output .aet/evidence/evidence-pack.json
+```
+
+Absolute, outside-workspace, missing, non-regular, undecodable, or
+unredactable artifacts are `UNKNOWN`; if one was explicitly requested, Trace
+returns non-zero even when pytest itself exited zero. This preserves the two
+facts separately: the command ran, but its requested report was not safely
+captured. A bound proof with that artifact gap remains `UNKNOWN` and cannot
+advance a Run to `PROVEN`. Stdout and stderr remain excerpt-and-digest only; full report content
+enters a pack solely through this explicit opt-in.
+
 ### 4. Optionally record a delivery lifecycle
 
 ```bash

aet.intent.json

@@ -1,5 +1,5 @@
 {
-  "intent": "Release v1.3.0 with deterministic Context Manifests, explicit read-attestation boundaries, and source-backed Decision Ledgers without adding an Agent runtime or generic memory system.",
+  "intent": "Release v1.4.0 with explicit, redacted capture of declared command-generated text reports so pytest evidence can travel in an Evidence Pack without adding an Agent runtime or guessing output files.",
   "changed_path_budget": 20,
   "allowed_paths": [
     "aet.intent.json",
@@ -23,9 +23,8 @@
       "command": "uv run --no-editable --reinstall-package agent-engineering-toolkit python -m unittest discover -s tests -v",
       "evidence": [
         "README.md",
-        "src/aet/context.py",
-        "src/aet/decision.py",
-        "tests/test_productization.py"
+        "src/aet/evidence.py",
+        "tests/test_audit.py"
       ]
     }
   ]

docs/README.zh-CN.md

@@ -34,7 +34,7 @@ AET 是 Agent 工作与“已经就绪”这个结论之间的一层小而确定
 | --- | --- | --- |
 | 这个 Agent 能安全地遵循当前指令和 Skill 吗？ | `aet audit` | 带位置和修复建议的 Markdown、JSON 或 SARIF。 |
 | 这次 diff 是否在人工批准的意图范围内？ | `aet review` | 路径预算、允许路径和已声明 proof 的 Intent Gate 报告。 |
-| 这条命令是在已审查的工作区运行的吗？ | `aet trace` + `aet evidence pack` | 脱敏执行记录，以及 proof / 工作区快照绑定。 |
+| 这条命令是否在已审查工作区运行，并生成了声明的测试报告？ | `aet trace --artifact` + `aet evidence pack` | 脱敏执行记录、显式捕获的报告，以及 proof / 工作区快照绑定。 |
 | 这份交付证据正处于哪个阶段，是否已经过期？ | `aet run` | 可选、append-only 的 Run Manifest 与明确生命周期状态。 |
 | 哪些本地指令/参考资料可用，哪些只是被声明为已读？ | `aet context` | 哈希绑定的 Context Manifest；读取声明是显式 attestation。 |
 | 哪些项目决策有本地来源，哪条记录已替代它？ | `aet decision` | 带来源哈希、验证和 supersession 历史的 Decision Ledger。 |
@@ -145,11 +145,11 @@ Decision Ledger 是给维护者使用的、带来源的轻量项目记忆，不
 AET 故意展示 status matrix，而不是“Agent 信任度总分”。唯一有权重的模型是
 `aet triage`，它会公开因素和版本，并且只用于修复排序。
 
-| Release 检查 | v1.3.0 实测结果 | 复现方式 |
+| Release 检查 | v1.4.0 实测结果 | 复现方式 |
 | --- | --- | --- |
-| 回归测试 | 27 项测试通过 | `uv run --no-editable --reinstall-package agent-engineering-toolkit python -m unittest discover -s tests -v` |
+| 回归测试 | 30 项测试通过 | `uv run --no-editable --reinstall-package agent-engineering-toolkit python -m unittest discover -s tests -v` |
 | 严格自审 | 在配置的 production Skill 范围内为 0 `FAIL`、0 `UNKNOWN` | `uv run --no-editable aet audit . --strict` |
-| Intent Review | 发布 diff 必须在已审阅合同范围内 | `uv run --no-editable aet review . --base v1.1.0 --intent aet.intent.json` |
+| Intent Review | 发布 diff 必须在已审阅合同范围内 | `uv run --no-editable aet review . --base v1.3.0 --intent aet.intent.json` |
 | 分发冒烟 | 成功构建 wheel，并在隔离环境中调用 | `uv build` 后安装上方 wheel |
 | 自动交付 | `main` 上 CI，`v*` tag 触发 GitHub Release | [Actions](https://github.com/AdvancingTitans/agent-engineering-toolkit/actions) |
 
@@ -163,7 +163,7 @@ AET 故意展示 status matrix，而不是“Agent 信任度总分”。唯一
 使用 [uv](https://docs.astral.sh/uv/) 安装 GitHub Release wheel：
 
 ```bash
-uv tool install https://github.com/AdvancingTitans/agent-engineering-toolkit/releases/download/v1.3.0/agent_engineering_toolkit-1.3.0-py3-none-any.whl
+uv tool install https://github.com/AdvancingTitans/agent-engineering-toolkit/releases/download/v1.4.0/agent_engineering_toolkit-1.4.0-py3-none-any.whl
 aet --version
 ```
 
@@ -240,6 +240,25 @@ aet evidence viewer --pack .aet/evidence/evidence-pack.json \
 Trace 是 opt-in，要求 `--`，只记录显式命令；保存的是脱敏片段和内容哈希。静态 viewer
 不需要服务器或外部资产。
 
+### 捕获显式声明的 pytest 报告
+
+`trace` 不会猜测命令写出了哪些文件。若测试报告属于交付结论，必须显式声明其相对于
+工作区的路径。命令结束后，AET 才读取完整 UTF-8 文本报告、先脱敏再持久化，并将其嵌入
+可携带的 Evidence Pack。
+
+```bash
+aet trace --artifact reports/junit.xml --output .aet/evidence/pytest-trace.json -- \
+  pytest --junitxml=reports/junit.xml
+aet evidence pack --trace .aet/evidence/pytest-trace.json \
+  --output .aet/evidence/evidence-pack.json
+```
+
+绝对路径、工作区外路径、缺失、非常规文件、无法解码或无法安全脱敏的产物均为
+`UNKNOWN`。只要显式请求的产物未被安全捕获，即使 pytest 本身返回 0，Trace 也会返回
+非零。这样能分别保留两个事实：命令确实执行过，但请求的报告并未被安全保留。stdout 与
+stderr 仍只保存片段和 hash；此时绑定 proof 仍为 `UNKNOWN`，Run 也不会推进到 `PROVEN`。
+完整报告仅在用户明确 opt-in 后才会进入 Pack。
+
 ### 4. 可选：记录交付生命周期
 
 ```bash

docs/productization-plan.md

@@ -482,3 +482,24 @@ Evidence IR。
 不采用 LangGraph、XState、工作流引擎、embedding、向量数据库、RAG、后台记忆 Agent 或
 宿主控制器。状态机文章提供的是白名单迁移和显式状态的表达法；这里以小型命令和 JSON
 ledger 吸收该思想，绝不将 AET 变成 Runtime。
+
+## v1.4 决策：显式 Trace 产物捕获（2026-07-12）
+
+Invest-Vault 的真实 dogfood 证明了一个缺口：`aet trace` 可以执行完整 pytest 子进程，
+但 v1.3 只带回 stdout/stderr，无法让 Evidence Pack 携带 pytest 生成的 JUnit、HTML 或
+JSON 报告。命令成功不等于报告已生成、仍在原路径、且可安全复核。
+
+Harness Engineering 对 AET 的可取之处是“把长期运行的可检查产物保留在文件系统，并把
+失败轨迹也留为可读状态”；不应因此把 AET 改造成自我改进 Agent 或工作流调度器。于是采用
+最小、显式的 `aet trace --artifact <relative-path>`：命令结束后才读取声明的工作区内 UTF-8
+文本文件，先脱敏，再将完整脱敏文本与 SHA-256 嵌入 Trace 和 Pack。
+
+| 情况 | Trace 中的事实 | CLI 退出码 |
+| --- | --- | --- |
+| 命令成功，声明报告安全捕获 | execution `PASS`，artifact `PASS` | 0 |
+| 命令成功，报告缺失/越界/非文件/无法安全读取 | execution `PASS`，artifact `UNKNOWN` | 非 0 |
+| 命令失败 | execution `FAIL` | 子进程的非 0 |
+
+不自动猜测 pytest 输出文件、不解析具体测试框架格式、不捕获目录或二进制文件，也不把
+未经显式请求的完整 stdout/stderr 放入 Pack。这既提供端到端的报告证据，又维持 Trace 的
+副作用边界、最小采集和隐私默认值。

docs/security-and-retention.md

@@ -2,7 +2,13 @@
 
 - `audit`, `review`, `triage`, and local `evolve` are read-only.
 - `trace` is the only generic command executor. It requires `--`, records the
-  explicit argv, and writes redacted logs plus digests.
+  explicit argv, and writes redacted logs plus digests. `--artifact` is a
+  separate explicit opt-in for one workspace-relative UTF-8 text report; the
+  report is redacted before it enters Trace or an Evidence Pack. stdout and
+  stderr remain excerpt-and-digest only.
+- Artifact paths may not be absolute or resolve outside the workspace. Missing,
+  non-regular, undecodable, and unredactable artifacts remain `UNKNOWN` and
+  make an otherwise successful Trace invocation return non-zero.
 - `evolve --remote github` is opt-in and records endpoint, retrieval time,
   status, and payload hash in its source manifest. No network access occurs by
   default.