patchwarden 1.1.0 → 1.5.1

package/docs/agentseal-integration.md

@@ -0,0 +1,150 @@
+# AgentSeal 集成模式
+
+> 本文基于 v1.5.1 源码编写；安装时请使用已验证发布的 <published-version>。
+> 说明：本文描述的是 PatchWarden 与 AgentSeal 的集成模式建议，**不是** AgentSeal 的官方功能。
+> AgentSeal 是独立的 agent 安全检测项目，本文不声称任何官方集成关系。
+
+## AgentSeal 是什么
+
+AgentSeal 是面向 AI 编程 Agent 的安全检测工具，主要职能包括：
+
+- 识别项目级安全策略（哪些文件可改、哪些命令可执行、哪些路径禁止访问）。
+- 对 Agent 的执行行为进行策略比对与违规告警。
+- 为 Agent 工作流提供可配置的策略层。
+
+AgentSeal 侧重于“策略声明与检测”，本身不强制执行；
+PatchWarden 侧重于“强制执行与证据收集”。两者互补。
+
+## 集成定位
+
+```
+AgentSeal:   声明策略 → 检测违规 → 告警
+                            ↓ 策略对齐
+PatchWarden: 接收任务 → 强制执行 → 证据收集
+```
+
+- AgentSeal 负责**策略侧**：识别并校验项目安全策略。
+- PatchWarden 负责**执行侧**：在执行任务时强制遵守策略，并产出可审计证据。
+
+## 配置文件关系
+
+PatchWarden 与 AgentSeal 共享两个关键配置文件，但职责不同：
+
+| 文件 | AgentSeal 角色 | PatchWarden 角色 |
+| --- | --- | --- |
+| `.patchwarden/config.json` | 读取并识别 PatchWarden 运行配置 | 运行时核心配置入口 |
+| `project-policy.json` | 校验项目策略合规性 | 执行时强制遵守的 allowed paths / commands |
+
+### `.patchwarden/config.json`
+
+PatchWarden 的运行配置，典型字段包括：
+
+```json
+{
+  "workspaceRoot": "D:\\repos\\my-project",
+  "agents": ["opencode", "codex"],
+  "evidencePackVersion": 2,
+  "safeResult": { "maxBytes": 4096 }
+}
+```
+
+AgentSeal 可读取此文件以了解 PatchWarden 的 workspace 边界与 agent 注册情况，
+用于检测配置是否与项目策略一致。
+
+### `project-policy.json`
+
+项目级安全策略，声明允许的路径与命令：
+
+```json
+{
+  "allowedPaths": ["src/**", "test/**"],
+  "allowedCommands": ["npm.cmd test", "npm.cmd run build", "git status"],
+  "blockedFiles": [".env", ".env.*", "id_rsa", "cookies.db"],
+  "scopeRules": { "enforceDeclaredFiles": true }
+}
+```
+
+- AgentSeal 将此文件作为策略基准进行检测。
+- PatchWarden 将此文件作为执行时的强制约束。
+- 两者读取同一份文件，保证“检测基准”与“执行约束”一致。
+
+## 集成流程示例
+
+### 1. 编写项目安全策略
+
+在仓库根目录放置 `project-policy.json`（与 `.patchwarden/config.json` 配合）：
+
+```json
+{
+  "allowedPaths": ["src/**", "docs/**"],
+  "allowedCommands": ["npm.cmd run build", "npm.cmd test"],
+  "blockedFiles": [".env", "*.key", "*.pem"],
+  "scopeRules": { "enforceDeclaredFiles": true }
+}
+```
+
+### 2. AgentSeal 识别并校验策略
+
+```powershell
+# AgentSeal 扫描项目，识别 .patchwarden/config.json 与 project-policy.json
+# 输出策略合规报告
+agentseal scan --project D:\repos\my-project
+```
+
+AgentSeal 输出策略快照，作为后续违规比对的基准。
+
+### 3. PatchWarden 执行任务时强制遵守
+
+当 MCP 客户端通过 PatchWarden 执行任务时：
+
+```powershell
+# PatchWarden 启动时加载 project-policy.json
+# 执行任务时对每条命令与文件改动进行策略校验
+```
+
+PatchWarden 的强制行为：
+
+- 命令必须在 `allowedCommands` 列表中（精确匹配）。
+- 文件改动必须在 `allowedPaths` 范围内。
+- 命中 `blockedFiles` 的访问被立即阻断。
+- `enforceDeclaredFiles` 为 true 时，未声明文件的改动触发范围违规检测。
+
+### 4. 证据对齐与回溯
+
+任务完成后，PatchWarden 导出 Evidence Pack v2：
+
+```powershell
+# 产物位于 .patchwarden/evidence-packs/<lineage_id>/
+```
+
+其中：
+
+- `verify.json` 记录每轮迭代的策略校验结果，可与 AgentSeal 的策略快照对齐。
+- `risk.json` 聚合执行中识别的风险项。
+- `redactions.json` 记录已脱敏内容，证明未泄露敏感信息。
+
+AgentSeal 可读取这些文件，作为策略执行情况的回溯证据。
+
+## 安全边界
+
+- PatchWarden 不依赖 AgentSeal 运行。即使 AgentSeal 未启动，
+  PatchWarden 仍会按 `project-policy.json` 强制执行策略。
+- AgentSeal 不修改 PatchWarden 的运行时行为，仅提供策略检测与告警。
+- 两者共享 `project-policy.json` 作为单一策略真源，避免策略漂移。
+- 若 AgentSeal 检测到策略与 PatchWarden 配置不一致，
+  应由人工修正配置，不应自动放宽 PatchWarden 的约束。
+
+## 注意事项
+
+- 本集成模式不修改 AgentSeal 的任何行为，仅在配置与流程上配合。
+- `project-policy.json` 的字段定义以 PatchWarden 实际加载逻辑为准，
+  AgentSeal 侧应按相同 schema 解析。
+- 如策略允许读取 `.env` 等敏感文件，PatchWarden 仍会按安全契约阻断，
+  此时需要重新设计策略以避免触碰敏感资源。
+
+## 相关文档
+
+- `docs/threat-model.md`：PatchWarden 安全契约与敏感文件清单。
+- `docs/evidence-pack-schema.md`：Evidence Pack v2 文件结构。
+- `docs/why-patchwarden.md`：PatchWarden 定位与动机。
+- 上游草稿 PR：https://github.com/getagentseal/agentseal/pull/35

package/docs/architecture.md

@@ -0,0 +1,63 @@
+# PatchWarden Architecture
+
+PatchWarden is designed as a narrow control layer between an MCP client and
+local coding agents.
+
+## Roles
+
+```text
+ChatGPT / Codex / OpenCode / another MCP client
+                    |
+                    v
+          PatchWarden MCP Server
+                    |
+          save_plan / create_task
+                    |
+                    v
+       .patchwarden/tasks/<task_id>/
+                    |
+              Watcher finds task
+                    |
+                    v
+       Local agent (OpenCode / Codex)
+                    |
+                    v
+ result.json / diff.patch / verify.json / status.json
+                    |
+                    v
+       MCP client reads safe summaries and audit evidence
+```
+
+## Core Components
+
+| Component | Responsibility |
+| --- | --- |
+| MCP server | Exposes constrained planning, task, summary, audit, and status tools. |
+| Watcher | Polls queued tasks and starts preconfigured local agents. |
+| Agent registry | Defines trusted agent commands and argument templates. |
+| Command guard | Allows only exact verification commands from trusted configuration. |
+| Path guard | Keeps task paths under `workspaceRoot` and reports out-of-scope changes. |
+| Sensitive path guard | Blocks known credential and private-data file names. |
+| Evidence writer | Records status, result, verification, changed files, and audit artifacts. |
+| Control Center | Provides safe-first local review pages for tasks, direct sessions, lineage, warnings, and evidence packs. |
+
+## Data Flow
+
+1. A client saves a plan or creates a task with an explicit `repo_path`.
+2. PatchWarden validates the repository path and requested verification
+   commands.
+3. The task is written under `.patchwarden/tasks/<task_id>/`.
+4. The Watcher starts the selected registered agent.
+5. PatchWarden captures task status, changed files, Git diff evidence where
+   available, verification output, and audit summaries.
+6. The client reviews safe summaries first and asks for deeper artifacts only
+   when needed.
+
+## Safety Design
+
+PatchWarden treats model instructions as untrusted input. The local maintainer
+controls the workspace root, allowed commands, registered agents, and release
+process. The project intentionally keeps push, publish, tag, GitHub Release,
+and live service changes outside ordinary task execution.
+
+For the security model, see `docs/threat-model.md`.

package/docs/chatgpt-usage.md

@@ -92,6 +92,37 @@ safety boundaries and complete evidence.
 7. Changes remain uncommitted for review; commit, push, and publish are outside
    the ordinary task scope.
 
+For routine guarded work, `run_task_loop` can perform the assess-only preflight,
+task creation, waiting, safe summary review, audit, and bounded `fix_tests`
+follow-up cycle in one tool call. It still uses the existing Watcher and
+allow-listed verification commands, stops at local confirmation boundaries, and
+returns a `lineage_id` for `get_task_lineage` instead of full logs or diffs.
+
+For v1.4 Direct-assisted verification, set `direct_verify=true` only when the
+local Direct profile is enabled and the desired Direct verification commands are
+already allow-listed. The loop creates a Direct session after the normal task
+and audit have succeeded, runs verification, safe-finalizes, safe-audits, and
+stores bounded Direct evidence in lineage. It does not call Direct patching
+tools, publish, push, tag, create releases, or restart live services.
+
+For v1.5 isolated loop work, set `agent="auto"` when you want PatchWarden to
+pick from configured local agents using bounded routing, and set
+`isolation_mode="worktree"` only when the target repo is a git repository and
+you want the task to run in an isolated worktree. Worktree mode records evidence
+in lineage but never auto-merges or auto-deletes the worktree. After a loop
+finishes, call `export_task_evidence_pack(lineage_id)` to write bounded
+`evidence.json` and `EVIDENCE.md` files without stdout/stderr tails, full diffs,
+verification logs, or sensitive file content.
+
+For v1.3 policy-aware work, call `get_project_policy` before release-oriented
+changes. It reads the bounded effective `.patchwarden/project-policy.json`
+summary and release readiness without granting new command permissions. Release
+mode tools are full-profile only: `release_check` wraps the existing release
+gate, `release_prepare` runs only already allow-listed local commands,
+`release_verify` performs read-only npm/GitHub/CI checks, and `release_cleanup`
+defaults to dry run. None of these tools publish, push, tag, create GitHub
+Releases, restart live tunnels/watchers, or return full logs/diffs.
+
 `needs_confirm` assessments must be confirmed locally with
 `patchwarden-confirm <full_assessment_id>`. The confirmation command is not an
 MCP tool. A `blocked` assessment cannot be confirmed.

package/docs/control-center/README.md

@@ -27,6 +27,15 @@ automation-friendly commands.
 
 ## Design Notes
 
+- v1.3 Dashboard panels show bounded task lineage, project policy, and release
+  readiness summaries. The backing APIs are read-only and do not expose full
+  stdout/stderr, full diffs, long logs, or secret-bearing files.
+- v1.4 extends the lineage panel with Direct-assisted verification status and
+  exposes a safe Direct session summary API without stdout/stderr tails or diffs.
+- v1.5 adds an Evidence Pack dashboard card plus read-only
+  `/api/evidence-packs` and `/api/evidence-packs/:lineage_id` routes. These
+  APIs return bounded lineage/policy/catalog evidence and omit stdout/stderr,
+  full diffs, verification logs, and sensitive file content.
 - `control-center-mvp.md`: first Web dashboard scope.
 - `control-center-phase2.md`: follow-up management and diagnostics scope.
 - `control-center-daily-driver.md`: current daily-use contract.

package/docs/dashboard-overview.md

@@ -0,0 +1,86 @@
+# Dashboard 概览
+
+> 本文基于 v1.5.1 源码编写；安装时请使用已验证发布的 <published-version>。
+> 入口：`PatchWarden-Control.cmd` 或托盘菜单中的 "Open Control Center"。
+
+## 目的
+
+PatchWarden Dashboard（Control Center）把本地 Agent 工作流从“只能看的状态面板”
+升级为“可操作的工作流控制中心”。所有操作默认走 safe 摘要接口，完整日志、diff、
+test log 仅在折叠的“高级区”按需加载，不改变 PatchWarden 的安全边界。
+
+## 核心概念
+
+- **Safe-first**：默认展示 `safe_result` / `safe_audit` / `safe_test_summary` /
+  `safe_diff_summary` / `safe_direct_summary` 等有界摘要，避免直接渲染完整产物。
+- **Repo selector**：顶部下拉列出 workspace 根目录及其一级项目目录（带 package.json
+  版本标记）。切换 repo 会刷新 Project Policy、Release、Recent Tasks、Lineage、
+  Evidence Pack、Direct Sessions。
+- **Health Score**：综合 watcher / tunnel / agents / stale 任务 / 失败任务 /
+  policy 有效性 / release readiness / direct profile 状态计算出的健康分，
+  状态为 `healthy` / `warning` / `degraded` / `blocked`。
+- **Bound to lineage**：Evidence Pack 与 Lineage 绑定，只有 `run_task_loop` 产生
+  lineage 后才能导出证据包。
+
+## 主要页面
+
+| 页面 | 主要内容 |
+| --- | --- |
+| Dashboard | Repo selector、Health Score、服务状态、Release 卡片、Project Policy、Lineage、Evidence Pack、Stale 任务提示、最近任务列表、系统状态（含 Copy diagnostics） |
+| Tasks | 任务列表，支持按 repo_path / status / acceptance_status / warning_type / agent / date range 过滤 |
+| Task Detail | safe 摘要默认视图 + 折叠的高级区（完整 result / diff / test_log） |
+| Direct Sessions | 按 active / finalized / audited / expired 分组的 Direct 会话 |
+| Audit / Warnings | 按 warning 类型聚合的诊断页 |
+| Workspace | workspace 一级目录与项目列表 |
+| Logs | Core / Direct / Watcher / Control Center 日志尾部 |
+
+## 推荐工作流
+
+1. 在 Dashboard 顶部选择目标 repo。
+2. 查看 Health Score，确认系统健康（`healthy` 或 `warning`）。
+3. 在 Release 卡片确认发布就绪状态；若 `blocked`，按 `blocked_reason` 修复。
+4. 在最近任务列表点击 `safe_result` 快捷查看任务摘要。
+5. 打开 Task Detail 进行 safe-first 验收（详见
+   [task-safe-review-workflow.md](task-safe-review-workflow.md)）。
+6. 使用 Lineage Detail 查看 `run_task_loop` 成功/失败原因（详见
+   [lineage-evidence-pack-workflow.md](lineage-evidence-pack-workflow.md)）。
+7. 验收完成后导出 Evidence Pack。
+8. Direct 会话用于独立验证，完成后 finalize + audit（详见
+   [direct-session-workflow.md](direct-session-workflow.md)）。
+9. 遇到问题时点击 **Copy diagnostics** 复制诊断信息，发给 ChatGPT / Codex / opencode 排查。
+
+## 卡片速查
+
+### Release 卡片
+
+显示 package name、version_source、version、version_consistent、required_commands
+（每条命令的 allowed + blocked_reason）、commands_blocked_count、
+ready/unknown/blocked 状态及 blocked 原因。`next_action` 会引导使用
+`release_check` 模板。
+
+### Stale 任务卡片
+
+不再是简单的“过期任务列表”，而是可解释、可操作的健康建议卡片，包含 task_id、
+repo_path、status、error、人类可读的 explanation、next_action，以及快捷操作
+（查看详情、复制 task_id、隐藏、重建任务）。
+
+### Project Policy 卡片
+
+只读展示 auto_cleanup、protected_paths 数量、high_risk_commands 数量、
+release_mode 摘要。
+
+## 安全边界
+
+- 所有 safe 接口返回有界摘要，不包含完整日志、stdout/stderr tail、diff、密钥内容。
+- 完整 result / diff / test_log 只在折叠的高级区按需加载，永不自动加载。
+- Project Policy 卡片只读，不能从 UI 修改策略。
+- 不执行远程写操作（npm publish / git push / git tag / gh release）。
+- Diagnostics 输出经过 `redactSensitiveContent` 脱敏。
+
+## 相关 API 端点
+
+- `GET /api/workspace/repos` — Repo selector 数据源
+- `GET /api/diagnostics` — Copy diagnostics 数据源
+- `GET /api/warnings` — Warnings 页数据源
+- `GET /api/release/status` — Release 卡片数据源
+- `GET /api/tasks/stale` — Stale 任务卡片数据源（含 explanation / next_action）

package/docs/demo.md

@@ -3,6 +3,14 @@
 This is a privacy-safe demo flow for GitHub. It uses placeholder workspace
 names and avoids real tunnel IDs, account names, API keys, or local user paths.
 
+## Animated OSS Demo
+
+This scripted GIF summarizes the public maintainer workflow without showing
+private accounts, real API keys, real task history, or local user paths. It is a
+demo asset, not third-party adoption evidence.
+
+![PatchWarden OSS demo](assets/patchwarden-oss-demo.gif)
+
 ## Demo: ChatGPT Lists A Workspace
 
 Prompt in ChatGPT with the PatchWarden connector selected:

package/docs/direct-session-workflow.md

@@ -0,0 +1,98 @@
+# Direct 会话工作流
+
+> 本文基于 v1.5.1 源码编写；安装时请使用已验证发布的 <published-version>。
+> 相关页面：Direct Sessions
+
+## 目的
+
+Direct 会话（Direct Session）是 PatchWarden 提供给 ChatGPT 等 Direct agent 的
+独立验证通道：在 watcher 守护的任务流程之外，对一个 repo 做独立的文件查看、
+命令执行和验证。Direct 不会自动 patch 文件、不会绕过命令守卫，所有操作仍受
+workspace 隔离、敏感路径拦截和审计约束。
+
+## 核心概念
+
+- **Direct session**：绑定到某个 repo_path 的一次独立会话，有 session_id、
+  title、created_at、expires_at。
+- **会话状态分组**：`active` / `finalized` / `audited` / `expired`。
+  expired 默认折叠。
+- **safe_direct_summary**：Direct 会话的有界摘要，包含 changed_files_total、
+  verification status，不含完整 diff 或 stdout。
+- **finalize**：把 active 会话标记为已完成（finalized），冻结变更记录。
+- **audit**：对 finalized 会话做审计，生成审计摘要（audited 状态）。
+- **verification bundle**：`run_direct_verification_bundle` 一次性跑测试 + diff +
+  验收检查的成组操作。
+
+## 生命周期
+
+### 1. 创建 Direct 会话
+
+通过 Direct profile 的 MCP 工具创建会话（如 `start_direct_session`），指定
+repo_path 和 title。会话会进入 `active` 状态，并记录 created_at 与 expires_at。
+
+### 2. 在 Direct Sessions 页查看
+
+Direct Sessions 页按状态分组展示所有会话：
+
+- **active** — 进行中
+- **finalized** — 已 finalize，待 audit
+- **audited** — 已完成审计
+- **expired** — 已过期（默认折叠）
+
+每个会话显示 session_id、repo_path、title、created_at、expires_at、finalized、
+audited、changed_files_total、verification status。
+
+### 3. 执行独立验证
+
+在 active 会话中，使用 Direct 工具进行独立验证：
+
+- 查看文件（受敏感路径拦截）
+- 执行允许的命令（受白名单约束）
+- 调用 `run_direct_verification_bundle` 一次跑完测试 + diff + 验收检查
+
+或直接在 Direct Sessions 页点击 **run_direct_verification_bundle** 快捷操作。
+
+### 4. 查看 safe 摘要
+
+点击 **safe_direct_summary** 查看会话的有界摘要：
+
+- changed_files_total
+- verification status
+- 是否命中受保护路径
+
+> 完整 diff 与 stdout 不会自动加载，仅在高级区按需查看。
+
+### 5. Finalize 会话
+
+验证完成后点击 **safe_finalize_direct_session**（或调用
+`POST /api/direct-sessions/:sessionId/finalize`），把会话标记为 `finalized`，
+冻结变更记录，准备进入审计。
+
+### 6. Audit 会话
+
+对 finalized 会话点击 **safe_audit_direct_session**（或调用
+`POST /api/direct-sessions/:sessionId/audit`），生成审计摘要，会话进入
+`audited` 状态。审计摘要可用于归档或与 lineage 的 direct_verification 对照。
+
+### 7. 处理过期会话
+
+超过 expires_at 的会话进入 `expired` 状态，默认折叠。可执行：
+
+- **copy session_id** — 复制 id 用于追溯
+- **hide expired** — 调用 `POST /api/direct-sessions/:sessionId/hide` 隐藏
+
+## 安全边界
+
+- Direct 会话仍受 workspace 隔离、命令白名单、敏感路径拦截约束。
+- Direct 不会自动 patch 文件，所有写操作都需要显式确认。
+- safe 摘要不含完整 diff / stdout / 密钥内容。
+- finalize 与 audit 只修改本地会话状态，不触发远程写。
+- Direct 不执行 `npm publish` / `git push` / `git tag` / `gh release`。
+
+## 相关 API 端点
+
+- `GET /api/direct-sessions` — 会话列表（按状态分组）
+- `GET /api/direct-sessions/:sessionId` — 单个会话详情
+- `POST /api/direct-sessions/:sessionId/finalize` — finalize 会话
+- `POST /api/direct-sessions/:sessionId/audit` — audit 会话
+- `POST /api/direct-sessions/:sessionId/hide` — 隐藏过期会话

package/docs/evidence-pack-schema.md

@@ -0,0 +1,215 @@
+# Evidence Pack v2 文件结构
+
+> 本文基于 v1.5.1 源码编写；安装时请使用已验证发布的 <published-version>。（Evidence Pack v2）
+> 相关页面：`export_task_evidence_pack` MCP 工具、Lineage 与 Evidence Pack 工作流
+
+## 概述
+
+`export_task_evidence_pack` 导出 8 个有界文件到
+`.patchwarden/evidence-packs/<lineage_id>/`。每个文件只包含有界摘要，
+**不**包含完整 stdout/stderr/diff/secrets/.env/token/cookie/凭据路径。
+
+## 文件清单
+
+| 文件 | 用途 |
+| --- | --- |
+| `evidence.json` | 完整有界证据包（机器可读），含 lineage、policy、catalog 摘要。 |
+| `EVIDENCE.md` | 人类可读的 Markdown 证据摘要。 |
+| `risk.json` | 聚合的风险项与严重度（high/medium/low）。 |
+| `verify.json` | 每轮迭代和 direct session 的结构化验证记录。 |
+| `diffstat.json` | 文件级增删统计（路径、增删行数），不含完整 diff。 |
+| `lineage.json` | lineage 有界摘要（goal、final_status、stop_reason、task 计数）。 |
+| `attestation.json` | 版本、commit、Node/OS、tool profile、schema epoch 等溯源信息。 |
+| `redactions.json` | 本次导出中脱敏的类别与计数（不存原始隐藏值）。 |
+
+## risk.json
+
+从 lineage 的 rounds（`fail_checks` / `warn_checks`）和 `warnings` 聚合风险项。
+
+```json
+{
+  "risks": [
+    {
+      "source": "round",
+      "task_id": "task-main",
+      "severity": "high",
+      "category": "fail_check",
+      "detail": "verification failed: npm test exited with code 1"
+    },
+    {
+      "source": "round",
+      "task_id": "task-main",
+      "severity": "medium",
+      "category": "warn_check",
+      "detail": "minor scope drift"
+    },
+    {
+      "source": "lineage",
+      "severity": "low",
+      "category": "warning",
+      "detail": "diff.patch was truncated"
+    }
+  ],
+  "count": 3,
+  "by_severity": { "high": 1, "medium": 1, "low": 1 }
+}
+```
+
+**严重度映射**：
+
+- `high` — round 的 `fail_checks`
+- `medium` — round 的 `warn_checks`
+- `low` — lineage 的 `warnings`
+
+如果 lineage 无风险信息，写 `{"risks": [], "count": 0, "by_severity": {"high": 0, "medium": 0, "low": 0}}`。
+
+## verify.json
+
+从 lineage 的 rounds 和 direct_sessions 提取结构化验证记录。
+
+```json
+{
+  "records": [
+    {
+      "source": "round",
+      "task_id": "task-main",
+      "role": "main",
+      "verification_status": "passed",
+      "audit_verdict": "pass",
+      "passed": true
+    },
+    {
+      "source": "direct_session",
+      "session_id": "direct-one",
+      "verification_status": "passed",
+      "audit_verdict": "pass",
+      "passed": true,
+      "command_count": 3,
+      "passed_commands": 3,
+      "failed_commands": 0
+    }
+  ],
+  "count": 2,
+  "summary": { "total": 2, "passed": 2, "failed": 0 },
+  "latest_status": "passed",
+  "overall_passed": true
+}
+```
+
+**有界规则**：不含 stdout_tail/stderr_tail/完整验证日志，只保留状态与计数摘要。
+
+如果 lineage 无验证信息，写空 records 数组。
+
+## diffstat.json
+
+从 lineage 引用的 task 目录（`<tasksDir>/<task_id>/file-stats.json`）聚合文件级增删统计。
+
+```json
+{
+  "files": [
+    {
+      "path": "src/index.ts",
+      "status": "modified",
+      "additions": 12,
+      "deletions": 3,
+      "task_id": "task-main"
+    }
+  ],
+  "count": 1,
+  "totals": { "additions": 12, "deletions": 3 }
+}
+```
+
+**有界规则**：只存文件路径与行级增删计数，**不**含完整 diff 内容。所有路径经过
+`redactSensitiveValue` 脱敏处理。如果 task 目录不存在或 file-stats.json 缺失，写空数组。
+
+## lineage.json
+
+lineage 的有界摘要，不含完整 rounds 详情或 warnings/errors 原文。
+
+```json
+{
+  "lineage_id": "lineage_20260709_120000_a1b2c3d4",
+  "goal": "Fix authentication bug",
+  "final_status": "accepted",
+  "stop_reason": "success",
+  "iterations_count": 1,
+  "task_counts": {
+    "main": 1,
+    "fix": 0,
+    "cleanup": 0,
+    "direct_sessions": 1
+  },
+  "verification": { "latest_status": "passed", "passed": true },
+  "worktree": { "isolation_mode": "worktree", "status": "active" },
+  "agent_routing": { "selected_agent": "codex" },
+  "warnings_count": 0,
+  "errors_count": 0,
+  "truncated": false
+}
+```
+
+## attestation.json
+
+记录生成此证据包时的环境与版本溯源信息。
+
+```json
+{
+  "patchwarden_version": "1.5.1",
+  "package_version": "1.5.1",
+  "commit": "bc950a2",
+  "node_version": "v20.11.0",
+  "os": { "platform": "win32", "arch": "x64" },
+  "tool_profile": "full",
+  "schema_epoch": "2026-07-05-v13",
+  "generated_at": "2026-07-09T12:00:00.000Z"
+}
+```
+
+**字段说明**：
+
+- `patchwarden_version` — `src/version.ts` 中的 `PATCHWARDEN_VERSION`
+- `package_version` — `package.json` 中的 version（与 patchwarden_version 一致）
+- `commit` — `git rev-parse --short HEAD` 获取的 short hash；非 Git 环境为 `"unknown"`
+- `node_version` — `process.version`
+- `os` — `process.platform` 与 `process.arch`
+- `tool_profile` — 当前工具目录快照的 profile
+- `schema_epoch` — `TOOL_SCHEMA_EPOCH`
+
+## redactions.json
+
+记录本次导出中脱敏的类别、原因与计数。**不存原始隐藏值**。
+
+```json
+{
+  "redactions": [
+    {
+      "category": "known_token_format",
+      "reason": "matched known token format",
+      "count": 1
+    }
+  ],
+  "total_redacted": 1,
+  "bounded": true,
+  "note": "Only categories and counts are recorded; original secret values are never persisted."
+}
+```
+
+**脱敏类别**：
+
+| category | 匹配内容 |
+| --- | --- |
+| `private_key` | PEM 私钥块 |
+| `bearer_token` | `Bearer <token>` 格式 |
+| `npm_token` | npm `_?authToken=` 赋值 |
+| `credential_assignment` | `api_key=` / `secret=` / `password=` 等凭据赋值 |
+| `known_token_format` | `sk_` / `ghp_` / `github_pat_` 前缀的 token |
+
+## 安全边界
+
+- 所有 v2 文件经过 `redactSensitiveValue` 处理后才写入磁盘。
+- `redactions.json` 只记录类别 + 原因 + 计数，**永不**持久化原始密钥值。
+- `diffstat.json` 只存文件路径与行级计数，不含 diff 正文。
+- `verify.json` 只存状态摘要，不含 stdout/stderr tail。
+- `.patchwarden/evidence-packs/` 不进入 npm 包（package.json `files` 已排除）。
+- MCP 工具 `export_task_evidence_pack` 的输入参数无破坏性变更，只是输出多了文件。