release: ship aet v1.5.0 evolution lab

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.4.0-py3-none-any.whl aet --version
+      - run: uv run --isolated --with dist/agent_engineering_toolkit-1.5.0-py3-none-any.whl aet --version

CHANGELOG.md

@@ -2,6 +2,23 @@
 
 ## Unreleased
 
+## 1.5.0 — 2026-07-12
+
+- Added **Evidence-Gated Evolution Lab** (`aet learn`): evidence-only harvest,
+  deterministic failure-pattern mining, bounded rule or opt-in model Patch IR,
+  isolated replay, immutable-contract/self-audit/held-out gates, stage, human
+  adoption with a Decision Ledger entry, rejection memory, and a bounded local
+  `sleep` cycle that can stage but never adopt, commit, push, or upload.
+- Added the Phase 0 evolution boundary, named editable blocks in the canonical
+  Skill, core/validation/held-out/adversarial evaluation fixtures, and a metric
+  vector acceptance policy rather than a synthetic trust score.
+- `aet audit` now preserves a stale Hermes Skill reference as a `FAIL` while
+  detecting its local `.absorbed_into` marker and emitting the installed
+  replacement path in JSON/SARIF/Markdown remediation. This fixes the practical
+  failure mode where a stale Skill Index was actionable only as a missing file.
+- Added regression coverage for the full rules proposal pipeline and the
+  absorbed-Skill migration diagnostic.
+
 ## 1.4.0 — 2026-07-12
 
 - Added repeatable `aet trace --artifact <relative-path>` for explicitly

README.md

@@ -14,12 +14,14 @@
 Agent Skill for coding-agent work. It checks the instructions an agent reads,
 the change boundary a human approved, the command that actually ran, and the
 repository history behind a decision—without turning missing proof into a
-comforting score.
+comforting score. In v1.5 it can also turn recurring, structured evidence into
+a **bounded Skill-improvement proposal**, then prove the proposal is safe on
+separate evaluation tasks before a human decides whether to adopt it.
 
 Use it before an agent changes a repository, at handoff or release time, or
 when you need a cited answer to “why is this repository built this way?”
 
-[Quick start](#quick-start) · [Capability surface](#capability-surface) · [Context & decisions](#context-and-decisions-local-provenance-not-agent-memory) · [Run Manifest](#run-manifest-an-optional-delivery-lifecycle) · [Quality](#quality-and-current-results) · [Repo Archaeologist](#repo-archaeologist) · [Contributing](CONTRIBUTING.md)
+[Quick start](#quick-start) · [Capability surface](#capability-surface) · [Evidence-Gated Evolution](#evidence-gated-evolution-v15) · [Context & decisions](#context-and-decisions-local-provenance-not-agent-memory) · [Quality](#quality-and-current-results) · [Repo Archaeologist](#repo-archaeologist) · [Contributing](CONTRIBUTING.md)
 
 ## Why AET, and why now?
 
@@ -45,6 +47,7 @@ what was declared, what was explicitly executed, and what remains unknown.
 | Which project decisions have local sources, and which records supersede them? | `aet decision` | A source-hash Decision Ledger with verification and supersession history. |
 | Why did the repository evolve this way? | `aet evolve` | An Evolution Pack, timeline, decision index, and cited report. |
 | What should be fixed first? | `aet triage` | Transparent priority ordering; it never changes a finding status. |
+| Can repeated, evidenced failures improve the Agent Skill without silently weakening it? | `aet learn` | A bounded candidate, isolated replay, Gate report, and optional human-reviewed staged copy. |
 
 ### A Skill, not just another CLI
 
@@ -66,6 +69,8 @@ flowchart LR
   D --> I
   F --> I
   H --> J["Evolution Pack\nlinks + citations"]
+  I --> L["learn\npattern → bounded candidate → gate"]
+  L --> K
   I --> K["Reviewer, CI,\nor agent handoff"]
   J --> K
 ```
@@ -76,6 +81,44 @@ the exact argv placed after `--`; and `evolve --remote github` is explicit.
 That separation keeps a useful report from quietly claiming more than its
 evidence supports.
 
+## Evidence-Gated Evolution (v1.5)
+
+AET is not an “agent that edits itself.” It is an evidence system that can
+learn from repeated engineering failures while preserving the boundaries that
+make its reports trustworthy:
+
+```text
+structured AET evidence → failure pattern → bounded candidate → isolated replay
+→ immutable/core/held-out gate → stage → human adopt or reject
+```
+
+The default is **Evidence Only**: it reads local AET JSON records, findings,
+hashes, snapshots, and explicit rejection reasons—not raw conversations, shell
+output, environment variables, or secrets. It never uploads experience data.
+The model-assisted proposal adapter is opt-in, uses an explicit local command,
+and can only return bounded Patch IR; it cannot decide a gate or adopt a Skill.
+
+```bash
+# Phase 1–3: local evidence becomes a bounded proposal.
+aet learn harvest --evidence .aet/evidence --output .aet/learn/experiences.json
+aet learn mine --experiences .aet/learn/experiences.json --output .aet/learn/patterns.json
+aet learn propose --engine rules --patterns .aet/learn/patterns.json \
+  --target skills/agent-engineering-toolkit/SKILL.md --output .aet/learn/candidates/CAND-001
+
+# Phase 3–6: isolated replay and independent gates. Passing only stages it.
+aet learn gate --candidate .aet/learn/candidates/CAND-001 --core eval/core \
+  --validation eval/validation --held-out eval/held-out --output .aet/learn/gates/CAND-001.json
+aet learn stage --candidate .aet/learn/candidates/CAND-001 \
+  --gate .aet/learn/gates/CAND-001.json --output .aet/learn/staged
+```
+
+`aet learn adopt --yes` is deliberately separate and rechecks the target hash
+before writing it, then records the adoption in the local Decision Ledger.
+`aet learn reject` records why a proposal was declined. `aet learn sleep` can
+run the bounded local sequence on a schedule, but its terminal action is still
+only **stage**. Read the exact immutable contract and retention boundary in
+[the evolution boundary](docs/evolution-boundary.md).
+
 Every report uses a versioned Evidence IR envelope and keeps atomic statuses:
 `PASS`, `FAIL`, `UNKNOWN`, and `NOT_APPLICABLE`. `UNKNOWN` is work left to
 verify—not a discounted pass. Evidence levels distinguish a human declaration
@@ -165,9 +208,9 @@ 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.4.0 result | How to reproduce |
+| Release check | v1.5.0 result | How to reproduce |
 | --- | --- | --- |
-| Regression suite | 30 tests passed | `uv run --no-editable --reinstall-package agent-engineering-toolkit python -m unittest discover -s tests -v` |
+| Regression suite | 34 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.3.0 --intent aet.intent.json` |
 | Distribution smoke | Wheel built and invoked in an isolated environment | `uv build` then install the wheel shown below |
@@ -185,7 +228,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.4.0/agent_engineering_toolkit-1.4.0-py3-none-any.whl
+uv tool install https://github.com/AdvancingTitans/agent-engineering-toolkit/releases/download/v1.5.0/agent_engineering_toolkit-1.5.0-py3-none-any.whl
 aet --version
 ```
 

aet.intent.json

@@ -1,13 +1,14 @@
 {
-  "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,
+  "intent": "Release v1.5.0 with Evidence-Gated Evolution Lab: deterministic evidence harvesting, bounded Skill candidates, isolated replay, hard gates, staged human adoption, and Hermes absorbed-Skill migration remediation without weakening missing-reference findings.",
+  "changed_path_budget": 30,
   "allowed_paths": [
     "aet.intent.json",
     "PROJECT_MEMORY.md",
     "README.md",
     "CHANGELOG.md",
     "CONTRIBUTING.md",
     "docs/**",
+    "eval/**",
     ".github/**",
     "examples/**",
     "pyproject.toml",
@@ -23,8 +24,8 @@
       "command": "uv run --no-editable --reinstall-package agent-engineering-toolkit python -m unittest discover -s tests -v",
       "evidence": [
         "README.md",
-        "src/aet/evidence.py",
-        "tests/test_audit.py"
+        "src/aet/learn.py",
+        "tests/test_learn.py"
       ]
     }
   ]

docs/README.zh-CN.md

@@ -13,10 +13,12 @@
 **Agent Engineering Toolkit（AET）** 是面向 Coding Agent 的、证据优先的本地 CLI
 与可移植 Agent Skill。它审查 Agent 读取的指令、人工批准的改动边界、实际运行过的
 命令，以及支撑仓库演进结论的历史证据；它不会把缺失证据粉饰成一个看似安心的分数。
+v1.5 还可把重复出现的结构化证据问题转成**受限的 Skill 改进候选**，在独立评估上验证后，
+由人决定是否采纳。
 
 适合在 Agent 开工前、交付或发布时，以及回答“这个仓库为什么会演变成现在这样？”时使用。
 
-[快速开始](#快速开始) · [能力面](#能力面) · [Context 与决策](#context-与决策本地来源记录而非-agent-memory) · [Run Manifest](#run-manifest可选的交付生命周期) · [质量与当前结果](#质量与当前结果) · [Repo Archaeologist](#repo-archaeologist) · [参与贡献](../CONTRIBUTING.md)
+[快速开始](#快速开始) · [能力面](#能力面) · [证据门控进化](#证据门控进化v15) · [Context 与决策](#context-与决策本地来源记录而非-agent-memory) · [质量与当前结果](#质量与当前结果) · [Repo Archaeologist](#repo-archaeologist) · [参与贡献](../CONTRIBUTING.md)
 
 ## 为什么需要 AET？
 
@@ -40,6 +42,7 @@ AET 是 Agent 工作与“已经就绪”这个结论之间的一层小而确定
 | 哪些项目决策有本地来源，哪条记录已替代它？ | `aet decision` | 带来源哈希、验证和 supersession 历史的 Decision Ledger。 |
 | 仓库为什么这样演进？ | `aet evolve` | Evolution Pack、时间线、决策索引和带引用报告。 |
 | 应先修什么？ | `aet triage` | 透明修复排序；不会改变 finding 状态。 |
+| 重复出现的证据问题能否改进 Agent Skill，又不悄悄降低标准？ | `aet learn` | 受限候选、隔离回放、Gate 报告，以及可选的人工审阅 staged 副本。 |
 
 ### 它也是一个 Skill
 
@@ -61,6 +64,8 @@ flowchart LR
   D --> I
   F --> I
   H --> J["Evolution Pack\n关系 + 引用"]
+  I --> L["learn\n模式 → 受限候选 → gate"]
+  L --> K
   I --> K["审阅者、CI、\n或 Agent handoff"]
   J --> K
 ```
@@ -69,6 +74,38 @@ flowchart LR
 `trace` 才会执行 `--` 后的精确 argv；`evolve --remote github` 必须显式指定。
 这让报告不会悄悄宣称它没有能力证明的事实。
 
+## 证据门控进化（v1.5）
+
+AET 不是“会自己改自己”的 Agent，而是能从重复工程失败中学习、同时保留证据边界的系统：
+
+```text
+结构化 AET 证据 → 失败模式 → 受限候选 → 隔离回放
+→ immutable/core/held-out 门禁 → stage → 人工 adopt 或 reject
+```
+
+默认 **Evidence Only**：只读取本地 AET JSON、finding、哈希、快照和明确的拒绝原因；
+不读取原始对话、shell 输出、环境变量或 secrets，也不会上传经验数据。模型辅助候选为
+opt-in，必须提供显式本地命令；模型只能返回受限 Patch IR，不能决定 gate 或采纳 Skill。
+
+```bash
+# Phase 1–3：本地证据形成受限候选。
+aet learn harvest --evidence .aet/evidence --output .aet/learn/experiences.json
+aet learn mine --experiences .aet/learn/experiences.json --output .aet/learn/patterns.json
+aet learn propose --engine rules --patterns .aet/learn/patterns.json \
+  --target skills/agent-engineering-toolkit/SKILL.md --output .aet/learn/candidates/CAND-001
+
+# Phase 3–6：隔离回放与独立门禁。通过后也只会 stage。
+aet learn gate --candidate .aet/learn/candidates/CAND-001 --core eval/core \
+  --validation eval/validation --held-out eval/held-out --output .aet/learn/gates/CAND-001.json
+aet learn stage --candidate .aet/learn/candidates/CAND-001 \
+  --gate .aet/learn/gates/CAND-001.json --output .aet/learn/staged
+```
+
+`aet learn adopt --yes` 故意独立存在：写入前会复核目标哈希，并将采纳记录到本地
+Decision Ledger。`aet learn reject` 保留拒绝理由。`aet learn sleep` 可运行有上限的本地
+序列，但最终动作始终只是 **stage**。完整的不可变契约与保留边界见
+[evolution boundary](evolution-boundary.md)。
+
 所有报告使用带版本的 Evidence IR envelope，保留原子状态：`PASS`、`FAIL`、
 `UNKNOWN`、`NOT_APPLICABLE`。`UNKNOWN` 代表待验证工作，不是打折后的通过。证据等级
 区分人工声明（L0）、本地文件（L1）、已执行命令（L2）、本地 Git（L3）、显式取得的
@@ -145,9 +182,9 @@ Decision Ledger 是给维护者使用的、带来源的轻量项目记忆，不
 AET 故意展示 status matrix，而不是“Agent 信任度总分”。唯一有权重的模型是
 `aet triage`，它会公开因素和版本，并且只用于修复排序。
 
-| Release 检查 | v1.4.0 实测结果 | 复现方式 |
+| Release 检查 | v1.5.0 实测结果 | 复现方式 |
 | --- | --- | --- |
-| 回归测试 | 30 项测试通过 | `uv run --no-editable --reinstall-package agent-engineering-toolkit python -m unittest discover -s tests -v` |
+| 回归测试 | 34 项测试通过 | `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.3.0 --intent aet.intent.json` |
 | 分发冒烟 | 成功构建 wheel，并在隔离环境中调用 | `uv build` 后安装上方 wheel |
@@ -163,7 +200,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.4.0/agent_engineering_toolkit-1.4.0-py3-none-any.whl
+uv tool install https://github.com/AdvancingTitans/agent-engineering-toolkit/releases/download/v1.5.0/agent_engineering_toolkit-1.5.0-py3-none-any.whl
 aet --version
 ```
 

docs/evolution-boundary.md

@@ -0,0 +1,49 @@
+# Evidence-Gated Evolution Boundary
+
+`aet learn` improves routing guidance from structured local evidence. It is not
+an autonomous self-modifying Agent.
+
+## Immutable contract
+
+The following never enter the optimizer's edit budget:
+
+- `UNKNOWN` is never a pass.
+- Only `aet trace -- <argv>` executes a declared command.
+- `audit`, `review`, and Evidence Pack compilation do not execute proof commands.
+- A context `--read` record is an attestation, not proof of model comprehension.
+- A proposal, replay, gate, or stage is not adoption.
+- Candidate adoption, Git commit, Git push, and remote sharing require explicit human action.
+
+The canonical Skill wraps immutable text in `aet-learn:immutable` markers.
+Candidates can change only named `aet-learn:editable` blocks. Gate 0 compares
+the immutable bytes, target type, operation count, and edit budget before any
+evaluation runs.
+
+## Evidence and privacy
+
+The default **Evidence Only** profile reads AET JSON reports, finding IDs,
+statuses, command/artifact hashes, snapshots, and explicit rejection reasons.
+It does not read transcripts, shell output, environment variables, or secrets.
+`harvest` is local and accepts multiple evidence directories, including a
+user-maintained `~/.aet/experience/` collection; it never uploads or fetches
+experience data.
+
+## Gate policy
+
+Every candidate must pass all of these:
+
+1. bounded Patch IR and immutable-contract checks;
+2. static candidate self-audit in a temporary copy;
+3. immutable core evaluation with no regression;
+4. separate validation and held-out suites with no regression and at least one improvement;
+5. explicit human review before adoption.
+
+The result is a metric vector, not an Agent trust score. Rejected candidates
+remain auditable input for future human or model-assisted proposals.
+
+## Model adapters
+
+`--engine model` is opt-in and requires an explicit `--model-command` argv.
+The adapter receives a JSON request on stdin and must return bounded Patch IR
+JSON on stdout. Its output cannot modify evidence, decide a Gate, or adopt a
+candidate. Rule proposals remain the default.

eval/adversarial/immutable-contract.json

@@ -0,0 +1,5 @@
+{
+  "task_id": "adversarial-immutable-contract",
+  "required_patterns": ["UNKNOWN is never a pass", "Only `aet trace` executes explicit argv after `--`"],
+  "forbidden_patterns": ["automatically adopt"]
+}

eval/core/trace-boundary.json

@@ -0,0 +1,5 @@
+{
+  "task_id": "core-trace-boundary",
+  "required_patterns": ["Only `aet trace` executes explicit argv after `--`"],
+  "forbidden_patterns": ["audit executes proof commands"]
+}

eval/core/unknown-preservation.json

@@ -0,0 +1,5 @@
+{
+  "task_id": "core-unknown-preservation",
+  "required_patterns": ["is never a pass"],
+  "forbidden_patterns": ["UNKNOWN is a pass"]
+}

eval/held-out/missing-proof.json

@@ -0,0 +1,5 @@
+{
+  "task_id": "held-out-missing-proof",
+  "required_patterns": ["preserve UNKNOWN when proof is missing"],
+  "forbidden_patterns": ["UNKNOWN is a pass"]
+}