patchwarden 1.5.0 → 1.5.1

package/docs/roadmap-execution-and-acceptance.md

@@ -0,0 +1,365 @@
+# PatchWarden Roadmap Execution And Acceptance Plan
+
+> Created: 2026-07-09
+> Source document: `C:\Users\zengjie\Downloads\PatchWarden_项目推进与外部PR路线图.docx`
+> Scope: feasibility check, executable steps, and acceptance commands for PatchWarden-first ecosystem work.
+
+## Conclusion
+
+The roadmap is feasible, but it needs two corrections before execution:
+
+1. `v1.5.1` is not published yet. Local source is `1.5.1`, but GitHub Release and npm `latest` are still `v1.5.0`.
+2. Goal Session is not a greenfield feature. PatchWarden already has Goal/Subgoal tools; the next valuable work is final report export, Spec Kit import, and better evidence mapping.
+
+Therefore the execution order should be:
+
+1. P0: close and publish `v1.5.1` safely.
+2. P1: finish Evidence Pack v2 and public-facing docs.
+3. P2: submit external PRs in low-risk order: MCP Inspector, AgentSeal, then Spec Kit.
+4. P3: move to OpenCode/OpenHands/Aider integration docs after PatchWarden has published evidence to point at.
+
+Codex is responsible for implementation submission and acceptance verification. The user only needs to approve destructive, credentialed, or external-write actions when required by local policy.
+
+## Current Verified State
+
+Checked from `D:\ai_agent\Reasonix\reasonix_program\PatchWarden` on 2026-07-09:
+
+- Branch: `codex/patchwarden-v1.5.0`
+- HEAD: `cc27e6a Add OSS application evidence materials`
+- Worktree: dirty before this plan was added; preserve existing user changes.
+- `package.json`: `patchwarden@1.5.1`
+- GitHub Release latest: `v1.5.0`
+- npm `patchwarden`: `version=1.5.0`, `dist-tags.latest=1.5.0`
+- PR #24: open draft, CI passing, branch behind `main`
+- Local gates run successfully:
+  - `npm.cmd run build`
+  - `npm.cmd run test:unit`
+  - `npm.cmd run doctor:ci`
+  - `npm.cmd run verify:package`
+
+## P0: v1.5.1 Trusted Release
+
+### Objective
+
+Make `v1.5.1` a real published version, not just a local source version.
+
+### Execution
+
+```powershell
+git status --short --branch
+gh pr view 24 --repo jiezeng2004-design/PatchWarden --json number,title,state,isDraft,mergeStateStatus,headRefName,headRefOid,baseRefName,statusCheckRollup,url
+npm.cmd view patchwarden version dist-tags --json --cache "$env:TEMP\patchwarden-npm-cache"
+gh release view --repo jiezeng2004-design/PatchWarden --json tagName,name,isDraft,isPrerelease,publishedAt,url
+```
+
+If PR #24 is still behind `main`, update the branch without overwriting local work:
+
+```powershell
+git fetch origin main
+git rebase origin/main
+```
+
+If `git fetch` fails with Windows credential errors, stop and repair Git credential/proxy state before retrying. Do not work around it by force-pushing or resetting.
+
+After branch update:
+
+```powershell
+npm.cmd ci
+npm.cmd run build
+npm.cmd run test:unit
+npm.cmd run test:mcp
+npm.cmd run test:http-mcp
+npm.cmd run doctor:ci
+npm.cmd run verify:package
+npm.cmd test
+npm.cmd run pack:clean
+```
+
+### Submission
+
+Codex owns:
+
+- push updated branch
+- mark PR #24 ready for review only after local gates pass
+- monitor GitHub Actions
+- merge only through PR when checks are green
+- create tag and GitHub Release for `v1.5.1`
+- publish npm package only after npm auth is confirmed without exposing tokens
+
+### Acceptance
+
+```powershell
+gh pr view 24 --repo jiezeng2004-design/PatchWarden --json state,mergeStateStatus,statusCheckRollup
+gh release view v1.5.1 --repo jiezeng2004-design/PatchWarden --json tagName,name,isDraft,isPrerelease,publishedAt,url
+npm.cmd view patchwarden version dist-tags --json --cache "$env:TEMP\patchwarden-npm-cache"
+```
+
+Pass criteria:
+
+- PR merged.
+- GitHub Release `v1.5.1` exists and is not draft.
+- npm `version` is `1.5.1`.
+- npm `dist-tags.latest` is `1.5.1`.
+- release notes do not claim anything not verified by CI/GitHub/npm.
+
+## P1: Evidence Pack v2
+
+### Objective
+
+Make Evidence Pack the project signature capability: bounded human summary plus structured machine-readable evidence.
+
+### Current Gap
+
+Current export writes:
+
+- `.patchwarden/evidence-packs/<lineage_id>/evidence.json`
+- `.patchwarden/evidence-packs/<lineage_id>/EVIDENCE.md`
+
+The roadmap asks for richer named artifacts:
+
+- `risk.json`
+- `verify.json`
+- `diffstat.json`
+- `lineage.json`
+- `attestation.json`
+- `redactions.json`
+
+This is feasible as an incremental schema upgrade, not a rewrite.
+
+### Execution
+
+Primary files:
+
+- `src/tools/evidencePack.ts`
+- `src/tools/taskLineage.ts`
+- `src/tools/registry.ts`
+- `src/tools/toolRegistry.ts`
+- `src/test/unit/evidence-pack.test.ts` or existing v1.5 evidence tests
+- `docs/evidence-pack-schema.md`
+- `docs/lineage-evidence-pack-workflow.md`
+
+Implementation rules:
+
+- Keep exports bounded.
+- Do not include full stdout, stderr, full diff, secrets, `.env`, tokens, cookies, browser state, or credential paths.
+- Store redaction metadata as categories and reasons, not raw hidden values.
+- Include PatchWarden version, commit, package version, Node version, OS, tool profile, and schema epoch in attestation.
+
+### Acceptance
+
+```powershell
+npm.cmd run build
+npm.cmd run test:unit
+npm.cmd run doctor:ci
+npm.cmd run verify:package
+```
+
+Additional manual acceptance:
+
+- Run or reuse a `run_task_loop` lineage.
+- Export Evidence Pack.
+- Confirm all v2 files exist.
+- Confirm `EVIDENCE.md` is readable and bounded.
+- Confirm `redactions.json` does not contain raw secrets.
+- Confirm no `.patchwarden/evidence-packs` output is included in npm package.
+
+## P1: README And Docs Readiness
+
+### Objective
+
+Make the repository understandable to external users before sending traffic from external PRs.
+
+### Execution
+
+Add or align these docs:
+
+- `docs/why-patchwarden.md`
+- `docs/evidence-pack-schema.md`
+- `docs/spec-kit-integration.md`
+- `docs/agentseal-integration.md`
+- `docs/mcp-inspector-testing.md`
+- `docs/opencode-worker.md`
+- `docs/openhands-worker.md`
+- `docs/threat-model.md` already exists; update instead of duplicating.
+
+README front page should preserve these sections:
+
+1. one-line positioning
+2. architecture diagram
+3. why PatchWarden is not a remote shell
+4. five-minute demo
+5. Evidence Pack screenshot or text sample
+6. supported agents
+7. safety boundaries
+8. ecosystem adaptation
+
+### Acceptance
+
+```powershell
+npm.cmd run build
+npm.cmd run check:brand
+npm.cmd run doctor:ci
+npm.cmd run verify:package
+```
+
+Pass criteria:
+
+- README does not say `v1.5.1` is published until npm and GitHub confirm it.
+- Docs explain safety boundaries before external integrations.
+- Examples use placeholders for published versions unless release truth exists.
+
+## P2: External PR Batch 1
+
+### 1. MCP Inspector
+
+Why first: it is directly relevant, low-risk, and the upstream project is a testing tool for MCP servers.
+
+PR shape:
+
+- `docs: add CLI smoke testing example for MCP servers`
+- Generic first; PatchWarden only as one example if appropriate.
+
+Execution:
+
+```powershell
+git clone https://github.com/modelcontextprotocol/inspector.git
+cd inspector
+git checkout -b docs/cli-smoke-testing-example
+```
+
+Codex then inspects upstream contribution rules, edits docs only, runs upstream docs/lint/test commands, pushes fork branch, opens PR, and monitors CI.
+
+Acceptance:
+
+- Upstream tests or docs checks pass.
+- PR avoids promotional wording.
+- PR can stand alone without PatchWarden.
+
+### 2. AgentSeal
+
+Why second: AgentSeal scans dangerous agent skills and MCP configs, which matches PatchWarden policy/config detection.
+
+PR shape:
+
+- `feat: detect PatchWarden MCP configs and project policies`
+- or `docs: add guarded local agent execution pattern` if code detector scope is too broad.
+
+Execution:
+
+```powershell
+git clone https://github.com/getagentseal/agentseal.git
+cd agentseal
+git checkout -b detect/patchwarden-policy
+```
+
+Codex then inspects `CONTRIBUTING.md`, existing probes, and tests before choosing code or docs scope.
+
+Acceptance:
+
+- Detector recognizes `.patchwarden/config.json` and `project-policy.json` without reading secrets.
+- Tests cover positive and negative fixtures.
+- PR describes a general safety pattern, not just PatchWarden marketing.
+
+### 3. PatchWarden Compatibility Docs
+
+Why third: after first two external drafts, PatchWarden should document how to reproduce those workflows.
+
+Execution:
+
+```powershell
+npm.cmd run build
+npm.cmd run doctor:ci
+```
+
+Add:
+
+- `docs/mcp-inspector-testing.md`
+- `docs/agentseal-integration.md`
+
+Acceptance:
+
+- Commands are runnable on Windows PowerShell.
+- Docs link to real upstream PRs or issues after submission.
+
+## P2: External PR Batch 2
+
+### Spec Kit
+
+Why after Evidence Pack v2: Spec Kit is a strong fit, but PatchWarden needs a stable evidence schema before proposing integration.
+
+PR shape:
+
+- `docs: add evidence pack pattern for spec-driven development`
+- or `walkthrough: verify implemented tasks with an external MCP safety layer`
+
+Execution:
+
+```powershell
+git clone https://github.com/github/spec-kit.git
+cd spec-kit
+git checkout -b docs/evidence-verification-pattern
+```
+
+Acceptance:
+
+- PR maps spec -> tasks -> implementation -> evidence verification.
+- PatchWarden appears only as an example implementation.
+- Upstream docs checks pass.
+
+## P3: External PR Batch 3
+
+### OpenCode / OpenHands / Aider
+
+These are feasible but should not be first:
+
+- OpenCode has high traffic and a large repo; start with docs-only external supervisor pattern.
+- OpenHands is transitioning source ownership; inspect current repo structure before choosing target.
+- Aider is mature CLI tooling; a safe wrapper pattern is useful but should follow a published PatchWarden example.
+
+Acceptance for each:
+
+- Upstream contribution rules inspected.
+- PR is useful without requiring PatchWarden.
+- CI or documented local checks pass.
+- PatchWarden README links back only after PR exists.
+
+## Issue Backlog To Create
+
+Create these as GitHub issues after P0 release truth is clean:
+
+1. `fix: close v1.5.1 release truth gap`
+2. `feat: add Evidence Pack v2 artifact schema`
+3. `docs: add Evidence Pack v2 schema reference`
+4. `feat: export goal final report`
+5. `feat: import Spec Kit tasks into Goal Session`
+6. `docs: add MCP Inspector CLI smoke testing guide`
+7. `docs: add AgentSeal compatibility guide`
+8. `docs: add OpenCode worker integration guide`
+9. `docs: add OpenHands worker integration guide`
+10. `docs: add external PR roadmap and ecosystem compatibility matrix`
+
+## Global Acceptance Rules
+
+For every internal PatchWarden PR:
+
+```powershell
+npm.cmd run build
+npm.cmd run test:unit
+npm.cmd run test:mcp
+npm.cmd run test:http-mcp
+npm.cmd run doctor:ci
+npm.cmd run verify:package
+```
+
+Before release:
+
+```powershell
+npm.cmd ci
+npm.cmd test
+npm.cmd run pack:clean
+gh pr checks <PR_NUMBER> --repo jiezeng2004-design/PatchWarden --watch
+gh release view v<version> --repo jiezeng2004-design/PatchWarden --json tagName,isDraft,publishedAt,url
+npm.cmd view patchwarden version dist-tags --json --cache "$env:TEMP\patchwarden-npm-cache"
+```
+
+Never mark release work complete unless GitHub Release and npm registry truth both match the intended version.

package/docs/spec-kit-integration.md

@@ -0,0 +1,131 @@
+# Spec Kit 集成模式
+
+> 本文基于 v1.5.1 源码编写；安装时请使用已验证发布的 <published-version>。
+> 说明：本文描述的是 PatchWarden 与 Spec Kit 的集成模式建议，**不是** Spec Kit 的官方功能。
+> Spec Kit 是 GitHub 维护的独立项目，本文不声称任何官方集成关系。
+
+## Spec Kit 是什么
+
+Spec Kit 是 GitHub 推出的 spec-driven development（规格驱动开发）工具集，
+用于在代码实现之前先定义、版本化、验证规格（spec）。典型流程为：
+
+1. **Spec**：用结构化方式描述功能需求与验收标准。
+2. **Tasks**：将 spec 拆解为可执行的任务列表。
+3. **Implementation**：由人或 Agent 执行任务。
+4. **Verification**：根据 spec 的验收标准验证实现结果。
+
+Spec Kit 的核心价值在于把“要做什么”与“怎么做”显式分离，让验收有据可依。
+
+## PatchWarden 在 Spec Kit 流程中的位置
+
+PatchWarden 不替代 Spec Kit 的规格定义能力，而是承担 Spec Kit 流程中
+“Implementation”与“Verification”两个阶段的**安全执行与证据收集**角色：
+
+```
+Spec Kit: spec → tasks → implementation → verification
+                              ↑                ↑
+                              PatchWarden 在此执行并产出 Evidence Pack v2
+```
+
+- **Implementation 阶段**：PatchWarden 以 MCP 安全桥接器身份接收任务，
+  在 workspace 隔离、命令允许列表、范围违规检测下执行。
+- **Verification 阶段**：PatchWarden 导出 Evidence Pack v2，作为 spec
+  验收的结构化证据。
+
+## Evidence Pack v2 作为 spec 验收证据
+
+Spec Kit 的验收标准通常是自然语言描述。PatchWarden 的 Evidence Pack v2
+提供机器可读的对应物，便于自动化对齐：
+
+| Evidence Pack 文件 | Spec 验收对应物 |
+| --- | --- |
+| `evidence.json` | 任务整体证据，含 lineage、policy、catalog 摘要 |
+| `EVIDENCE.md` | 人类可读摘要，便于 spec reviewer 阅读 |
+| `risk.json` | 实现过程中识别的风险项，对应 spec 的风险条款 |
+| `verify.json` | 每轮迭代的结构化验证记录 |
+| `diffstat.json` | 文件级改动统计，对应 spec 声明的改动范围 |
+| `lineage.json` | 任务谱系，证明实现源自哪条 spec task |
+| `attestation.json` | 任务签名与证明 |
+| `redactions.json` | 已脱敏内容清单 |
+
+## 集成流程示例
+
+### 1. 在 Spec Kit 中定义 spec 与 tasks
+
+在 Spec Kit 仓库中编写 spec 与 task 清单，例如：
+
+```json
+{
+  "spec": "add-rate-limit-middleware",
+  "tasks": [
+    { "id": "T1", "desc": "implement rate limiter", "files": ["src/middleware/rate.ts"] },
+    { "id": "T2", "desc": "add tests", "files": ["test/middleware/rate.test.ts"] }
+  ],
+  "acceptance": ["T1 passes", "T2 passes", "no changes outside declared files"]
+}
+```
+
+### 1.5 批量导入 Spec Kit tasks 为 PatchWarden subgoal
+
+PatchWarden 提供 `import_speckit_tasks` 工具，可将 Spec Kit 的 tasks 批量导入为 Goal 下的 subgoal：
+
+- 每个 Spec Kit task 创建一个对应 subgoal，title 取自 task.desc
+- task.files 映射为 subgoal 的 scope_hints（声明改动范围提示）
+- task.depends_on 映射为 subgoal 间的依赖关系
+- Spec Kit 的 acceptance[] 存入 Goal 的 acceptance_criteria 字段
+- 支持幂等导入：重复导入同一 Spec Kit JSON 不会创建重复 subgoal
+
+### 2. 通过 PatchWarden 执行任务
+
+将 Spec Kit 的 task 通过 MCP 客户端交给 PatchWarden：
+
+```powershell
+# 假设 PatchWarden MCP server 已启动
+# MCP 客户端调用 PatchWarden 工具，传入 task 描述与声明的文件范围
+```
+
+PatchWarden 会在执行时：
+
+- 校验改动是否仅在 `src/middleware/rate.ts` 与 `test/middleware/rate.test.ts`。
+- 阻断任何越界文件改动或未注册命令。
+- 在每轮迭代后记录结构化验证。
+
+### 3. 导出 Evidence Pack 并与 spec 对齐
+
+任务完成后导出 Evidence Pack v2：
+
+```powershell
+# 通过 MCP 工具 export_task_evidence_pack 导出
+# 产物位于 .patchwarden/evidence-packs/<lineage_id>/
+```
+
+随后可用脚本将 `diffstat.json` 与 spec 声明的 `files` 对齐，
+将 `verify.json` 与 spec `acceptance` 对齐。
+
+### 4. Spec 验收
+
+reviewer 阅读 `EVIDENCE.md` 与 `verify.json`，
+确认实现满足 spec 验收标准后标记 spec 为已验收。
+
+## 配置要点
+
+- PatchWarden 的 `workspaceRoot` 应覆盖 Spec Kit 仓库根目录。
+- Spec Kit 的 task 中声明的文件范围应与 PatchWarden Project Policy 的
+  allowed paths 一致，避免执行时被范围违规检测阻断。
+- Evidence Pack v2 的 `lineage.json` 可用于回溯到 Spec Kit 的 task id，
+  建议在任务描述中包含 Spec Kit task id。
+
+## 边界与注意事项
+
+- PatchWarden 不解析 Spec Kit 的 spec 格式本身，只处理 tasks 与 acceptance 字段并产出证据。
+- Spec Kit 的 spec 验收逻辑由 Spec Kit 自身或 reviewer 负责，
+  PatchWarden 只提供证据材料。
+- 本集成模式不修改 Spec Kit 的任何行为，仅在流程上配合使用。
+- 如 Spec Kit task 要求读取 `.env` 或敏感文件，PatchWarden 会按安全契约阻断，
+  此时需要重新设计 task 以避免触碰敏感资源。
+
+## 相关文档
+
+- `docs/evidence-pack-schema.md`：Evidence Pack v2 文件结构。
+- `docs/threat-model.md`：PatchWarden 安全契约。
+- `docs/why-patchwarden.md`：PatchWarden 定位与动机。

package/docs/task-safe-review-workflow.md

@@ -0,0 +1,98 @@
+# 任务 Safe 验收工作流
+
+> 本文基于 v1.5.1 源码编写；安装时请使用已验证发布的 <published-version>。
+> 相关页面：Tasks、Task Detail
+
+## 目的
+
+在不暴露完整日志、diff、test log 的前提下，用一组 safe 摘要接口完成对单个任务的
+验收判断。完整产物仅在确认需要时才从折叠的“高级区”按需加载。
+
+## 核心概念
+
+- **safe_result**：任务结果摘要，包含 status、acceptance_status、verification 概要、
+  warnings、fail_checks、manual_verification_required、recommended_next_actions。
+- **safe_test_summary**：测试摘要，只包含通过/失败计数和失败用例名称，不含完整 stdout。
+- **safe_diff_summary**：diff 摘要，包含变更文件数、新增/删除/修改行数统计、
+  受保护路径命中情况，不含完整 diff。
+- **safe_audit**：审计摘要，包含 artifact 完整性、scope_changes、命令白名单合规性
+  的有界摘要。
+- **acceptance_status**：任务的验收状态，比 `status` 更能反映“是否真的通过”。
+- **Advanced 区**：折叠区域，包含完整 result / diff / test_log，需手动展开。
+
+## 验收工作流
+
+### 1. 在 Tasks 列表筛选目标任务
+
+Tasks 页支持按 `repo_path` / `status` / `acceptance_status` / `warning_type` /
+`agent` / date range 过滤。建议优先关注：
+
+- `acceptance_status` 为 `pending` 或 `failed_verification` 的任务
+- 带有 warning 的任务（warning_type 列会高亮）
+
+### 2. 使用行内快捷操作预览
+
+每行任务提供以下快捷操作，无需进入详情页即可快速判断：
+
+- `safe_result` — 查看任务结果摘要
+- `safe_test_summary` — 查看测试摘要
+- `safe_diff_summary` — 查看变更摘要
+- `safe_audit` — 查看审计摘要
+- `open detail` — 进入 Task Detail 页
+- `copy id` — 复制完整 task_id
+
+### 3. 进入 Task Detail 进行完整 safe 验收
+
+Task Detail 默认展示 safe 摘要视图：
+
+- **safe_result** 区：status、acceptance_status、verification headline、warnings、
+  fail_checks、manual_verification_required、recommended_next_actions
+- **safe_test_summary** 区：通过/失败计数、失败用例名
+- **safe_diff_summary** 区：变更文件数、行数统计、受保护路径命中
+- **safe_audit** 区：artifact 完整性、scope_changes、命令合规性
+
+### 4. 仅在必要时展开高级区
+
+只有当 safe 摘要无法定论时（例如 `manual_verification_required` 为 true，
+或 `fail_checks` 指向某个具体失败），才展开高级区查看完整产物：
+
+- 完整 result（JSON）
+- 完整 diff
+- 完整 test_log
+
+> 高级区内容不会自动加载，必须手动点击展开。展开不会触发任何写操作。
+
+### 5. 根据 recommended_next_actions 决定下一步
+
+safe_result 的 `recommended_next_actions` 会给出建议，例如：
+
+- 验收通过 → 导出 Evidence Pack 或进行 Direct 独立验证
+- 验收失败 → 基于 `run_task_loop` 创建修复任务
+- 需要人工确认 → 标记 `manual_verification_required` 后人工复核
+
+## Stale 任务处理
+
+Stale 任务卡片会给出 explanation 和 next_action：
+
+- **view detail** — 查看 safe 摘要判断是否需要重建
+- **copy task_id** — 复制 id 用于后续命令
+- **hide** — 调用 `POST /api/tasks/:taskId/hide-stale` 从 stale 列表隐藏
+- **recreate task** — 基于原任务参数创建新任务
+
+## 安全边界
+
+- safe 接口返回有界摘要，不含完整 stdout/stderr、完整 diff、密钥、token。
+- 完整产物仅在高级区手动展开后加载，且不离开本机。
+- 验收操作不触发远程写（不 publish、不 push、不 tag、不 release）。
+- `acceptance_status` 由 watcher 与 verification 流程计算，不能从 UI 直接伪造。
+
+## 相关 API 端点
+
+- `GET /api/tasks` — 任务列表（支持 repo_path / status / acceptance_status /
+  agent / warning_type 过滤）
+- `GET /api/tasks/:taskId/safe-result` — safe_result 摘要
+- `GET /api/tasks/:taskId/safe-test-summary` — safe_test_summary 摘要
+- `GET /api/tasks/:taskId/safe-diff-summary` — safe_diff_summary 摘要
+- `GET /api/tasks/:taskId/safe-audit` — safe_audit 摘要
+- `GET /api/tasks/stale` — stale 任务列表（含 explanation / next_action）
+- `POST /api/tasks/:taskId/hide-stale` — 隐藏 stale 任务

package/docs/threat-model.md

@@ -0,0 +1,79 @@
+# PatchWarden Threat Model
+
+PatchWarden is a local MCP bridge for AI coding workflows. Its core security
+goal is to let an MCP client request bounded maintainer tasks without turning
+the local machine into a general-purpose remote shell.
+
+## Assets Protected
+
+- source repositories under the configured workspace
+- release artifacts and checksums
+- task evidence under `.patchwarden/`
+- local configuration files
+- `.env` files, API keys, tokens, SSH keys, cookies, browser state, and
+  credential stores
+- maintainer time and trust in verification evidence
+
+## Trust Boundaries
+
+PatchWarden assumes the upstream model or MCP client can be wrong, overbroad, or
+prompt-injected. It should not be trusted with unrestricted command execution,
+arbitrary filesystem reads, or release authority.
+
+Trusted local configuration includes:
+
+- `workspaceRoot`
+- registered agents and their command templates
+- `allowedTestCommands`
+- project policy files reviewed by the maintainer
+
+Human maintainer confirmation remains required for high-risk actions such as
+publishing, pushing, creating releases, changing live services, or approving
+local confirmation tickets.
+
+## Main Threats
+
+| Threat | Example | Mitigation |
+| --- | --- | --- |
+| Arbitrary shell execution | A prompt asks the MCP server to run a custom command. | PatchWarden exposes task tools, not a general shell; verification commands must exactly match allowlists. |
+| Path traversal | A task tries to edit `../other-project` or user home files. | Task paths are resolved under `workspaceRoot`; out-of-scope changes are reported as violations. |
+| Secret exfiltration | A task asks to read `.env`, SSH keys, cookies, or credentials. | Sensitive path names are blocked and docs require redacted logs. |
+| Prompt injection | Repository text instructs the model to ignore safety constraints. | Safety is enforced by local code and configuration, not by prompt instructions alone. |
+| Unsafe release claims | A local build passes and the agent claims npm/GitHub publish is complete. | Release docs require separate verification of PR/CI, GitHub Release, npm version, and `dist-tags.latest`. |
+| Evidence overload | A client requests full logs, diffs, or private task history by default. | Safe summary tools and bounded evidence packs are the preferred review surfaces. |
+| Live-service disruption | A task restarts tunnels, watchers, or unrelated processes. | Project rules forbid blanket process kills; live cutover must be explicit and separately approved. |
+
+## Security Invariants
+
+PatchWarden changes should preserve these invariants:
+
+- no general-purpose remote shell
+- all task repositories stay under `workspaceRoot`
+- agents are explicitly registered before use
+- model input cannot define arbitrary agent launch commands
+- verification commands use exact allowlist matching
+- sensitive paths remain blocked
+- task artifacts remain auditable and redacted where appropriate
+- scope violations are surfaced, not silently accepted
+- publish, push, tag, release, and live-service operations remain
+  confirmation-gated
+
+## Non-Goals
+
+PatchWarden is not a full sandbox, container runtime, endpoint security product,
+or secret scanner. It adds policy, task evidence, verification, and review
+records around local agent work. It should be used with normal operating-system
+permissions, Git review, CI, and maintainer judgment.
+
+## Review Checklist For Security-Sensitive Changes
+
+- [ ] Does the change weaken workspace confinement?
+- [ ] Does it expand command execution beyond exact allowlists?
+- [ ] Does it expose full logs, diffs, task history, or file contents where a
+      safe summary would be enough?
+- [ ] Does it read or persist credentials, tokens, cookies, browser state, or
+      `.env` content?
+- [ ] Does it auto-push, auto-publish, auto-tag, or restart live services?
+- [ ] Does it add or update smoke coverage for changed behavior?
+- [ ] Does it keep README, examples, tool manifests, package metadata, and
+      migration docs aligned?