@mokuyoaxis/agent-guard 0.2.7 → 0.2.9

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/docs/README.md CHANGED
@@ -1,16 +1,28 @@
1
1
  # Documentation / 文档导航
2
2
 
3
3
  Start with [getting started](guides/getting-started.md) for installation and
4
- setup. The three main paths are [recovery protection](../skills/delete-guard/SKILL.md),
5
- [disclosure checks](../skills/exfil-guard/SKILL.md), and
6
- [behaviour experiments](lab/guard-lab.md). Use the
4
+ setup. The three main capabilities are **Exfil-guard**, **Delete-guard** and
5
+ **Guard-lab**. Use the
7
6
  [harness capability matrix](guides/harness-capabilities.md) for observed coverage
8
7
  and the [architecture](design/architecture.md) for the shared Core.
9
8
 
10
- This documentation covers [0.2.7](releases/release-notes-0.2.7.md): Cleanup
11
- plans, deletion admission and optional local MCP tools. Before installing,
12
- check the exact [GitHub release](https://github.com/mokuyoaxis/agent-guard/releases/tag/0.2.7)
13
- and [npm version](https://www.npmjs.com/package/@mokuyoaxis/agent-guard/v/0.2.7)
9
+ | Main capability / 主要功能 | Included functions and guides / 下属功能与指南 |
10
+ |---|---|
11
+ | **Exfil-guard** | [Text checks and redaction](../skills/exfil-guard/SKILL.md) · [Safe config view](../skills/exfil-guard/SKILL.md#safe-config-view) |
12
+ | **Delete-guard** | [Recoverable deletion](../skills/delete-guard/SKILL.md) · [Cleanup Copilot](guides/cleanup-plan.md) · [Deletion limits](guides/deletion-limits.md) · [Recovery and GC](guides/recovery-feedback.md) · [MCP tools](guides/mcp.md) · [MCP doctor (0.2.8)](guides/mcp.md#diagnose-a-local-service-028) |
13
+ | **Guard-lab** | [Controlled experiments and evidence](lab/guard-lab.md) · [Four zero-model controls](lab/blue-team-calibration.md) · [Defensive research](research/README.md) |
14
+
15
+ Cleanup Copilot, deletion admission and the current MCP tools/doctor are
16
+ Delete-guard functions. [Recovery-audit](../skills/recovery-audit/SKILL.md)
17
+ is an auxiliary incident-recovery workflow.
18
+
19
+ Version [0.2.9](releases/release-notes-0.2.9.md) adds read-only Cleanup
20
+ inventory and selected-scope measurement through CLI and MCP, faster plan
21
+ scans and a repository-corpus test fix. The earlier
22
+ [0.2.8](releases/release-notes-0.2.8.md) adds MCP diagnosis and recovery validation.
23
+ Before installing 0.2.9,
24
+ check the exact [GitHub release](https://github.com/mokuyoaxis/agent-guard/releases/tag/0.2.9)
25
+ and [npm version](https://www.npmjs.com/package/@mokuyoaxis/agent-guard/v/0.2.9)
14
26
  for availability. A checkout or manifest does not establish publication or
15
27
  the current npm `latest` channel.
16
28
  The opt-in `rc` line remains [0.2.5-rc3](releases/release-notes-0.2.5-rc3.md), and `hotfix` is the
@@ -23,9 +35,15 @@ its doctor checks, Kimi 2.3.0 root-Bash compatibility, DSH Lab preflight
23
35
  diagnostics and alpha.4 default deletion compatibility. Existing 0.2.5 installations
24
36
  need an upgrade to acquire those additions; see its [version notes](releases/release-notes-0.2.6.md).
25
37
 
26
- 先看入门指南,再按恢复保护、外发检测、Lab 验测选择入口。测试报告按所测版本与配置保留;发布记录、
38
+ 先看入门指南,再按 Exfil-guard、Delete-guard、Guard-lab 三大功能选择入口。
39
+ Cleanup、删除限制与当前 MCP 工具/doctor 归入 Delete-guard。测试报告按所测版本与配置保留;发布记录、
27
40
  历史设计和外部案例各自归档,不能据此扩展当前产品的承诺。
28
41
 
42
+ 0.2.9 新增[目录概况与计量](guides/cleanup-plan.md#directory-overview-and-measurement-029)
43
+ 及两个[只读 MCP 工具](guides/mcp.md#cleanup-observations-unreleased),仍归属 Cleanup Copilot;
44
+ 0.2.8 不含这些新增能力。[变更摘要](releases/unreleased.md#current-unreleased-scope)
45
+ 汇总当前范围与验证,历史失败和各版发行记录在其后保留。
46
+
29
47
  | Category / 分类 | Contents / 内容 |
30
48
  |---|---|
31
49
  | [Guides](#guides) / 使用指南 | 宿主接入证据、漂移检查、维护者发布指南 |
@@ -45,9 +63,12 @@ ALLOW_NOOP 覆盖边界及准确 GC 用法;纳入 0.2.5。
45
63
  |---|---|
46
64
  | [Getting started](guides/getting-started.md) | 安装路径、Agent 接入提示词与最短验证流程 |
47
65
  | [Status and cleanup feedback](guides/recovery-feedback.md) | Python/插件状态、ALLOW_NOOP、保留空间与手动 GC |
48
- | [Cleanup Copilot](guides/cleanup-plan.md) | 0.2.7:零写入计划、四类候选、大小与显式确认执行 |
49
- | [Deletion limits](guides/deletion-limits.md) | 0.2.7:隔离容量、会话预算、频率、保护路径与批量确认 |
50
- | [Local MCP tools](guides/mcp.md) | 0.2.7本地stdio:安全删除、普通恢复、事务/状态和GC预览;不替代hook |
66
+ | [Cleanup Copilot](guides/cleanup-plan.md) | Delete-guard,0.2.7:零写入计划、四类候选、大小与显式确认执行 |
67
+ | [Directory overview and measurement](guides/cleanup-plan.md#directory-overview-and-measurement-029) | Delete-guard,0.2.9:先概况、再按范围发现/计量;没有执行许可 |
68
+ | [Deletion limits](guides/deletion-limits.md) | Delete-guard,0.2.7:隔离容量、会话预算、频率、保护路径与批量确认 |
69
+ | [Local MCP tools](guides/mcp.md) | Delete-guard,0.2.7:本地 stdio 安全删除、普通恢复、事务/状态和 GC 预览;不替代 hook |
70
+ | [Read-only cleanup MCP](guides/mcp.md#cleanup-observations-029) | Delete-guard,0.2.9:cleanup_discover/cleanup_measure、固定工作区与部分观察状态 |
71
+ | [MCP diagnosis](guides/mcp.md#diagnose-a-local-service-028) | Delete-guard,0.2.8:选定本地服务的依赖、握手、工作区绑定与只读调用检查 |
51
72
  | [Harness capabilities](guides/harness-capabilities.md) | 当前接入范围、证据等级与未验证路径 |
52
73
  | [Host drift](guides/host-drift.md) | 宿主版本、配置与本地基线检查 |
53
74
  | [Trash locations](guides/trash-index.md) | 0.2.4 的只读位置查询、Agent/前端共享 JSON 契约 |
@@ -55,7 +76,9 @@ ALLOW_NOOP 覆盖边界及准确 GC 用法;纳入 0.2.5。
55
76
  | [Publishing from ephemeral environments](guides/publishing-from-ephemeral-environments.md) | 临时环境中的 GitHub 发布操作参考 |
56
77
 
57
78
  Adapter setup remains in [adapters/](../adapters/INTEGRATION.md). Skill contracts
58
- remain in [skills/](../skills/delete-guard/SKILL.md).
79
+ are documented separately for [Exfil-guard](../skills/exfil-guard/SKILL.md) and
80
+ [Delete-guard](../skills/delete-guard/SKILL.md); the [Guard-lab guide](lab/guard-lab.md)
81
+ describes the user-controlled experiment CLI.
59
82
 
60
83
  We currently focus on DSH and Kimi Code. Claude Code's adapter and past
61
84
  reports remain available; testing new Claude versions is paused. For other
@@ -125,9 +148,11 @@ coverage rather than treating every historical result as current acceptance.
125
148
 
126
149
  | Document / 文档 | Scope / 范围 |
127
150
  |---|---|
151
+ | [0.2.9](releases/release-notes-0.2.9.md) | 目录概况/计量、两只读 MCP 工具、扫描提速与语料门修复 |
152
+ | [0.2.8](releases/release-notes-0.2.8.md) | MCP 接入诊断、真实协议中断验证、安装与验收边界 |
128
153
  | [0.2.7](releases/release-notes-0.2.7.md) | Cleanup、删除准入与MCP的版本范围、升级影响和准备阶段验证 |
129
154
  | [0.2.6](releases/release-notes-0.2.6.md) | 正式版范围、升级影响与验收;Kimi 反馈/doctor、DSH 预检与版本扩展 |
130
- | [Changes and maintenance details](releases/unreleased.md) | 0.2.7增量及0.2.6维护历史,保留原验收边界 |
155
+ | [Changes and maintenance details](releases/unreleased.md) | 0.2.9 范围与本地验证;其后保留0.2.8、0.2.7及更早维护历史 |
131
156
  | [0.2.5](releases/release-notes-0.2.5.md) | 正式版范围;累计 RC 维护、明确反馈与升级影响 |
132
157
  | [0.2.4-hotfix.1](https://github.com/mokuyoaxis/agent-guard/releases/tag/0.2.4-hotfix.1) | 已发布的稳定线回收站保护回补;不含完整 RC 累计内容 |
133
158
  | [0.2.5-rc3](releases/release-notes-0.2.5-rc3.md) | 已发布的研究/文档预发布版与零模型示例 |
@@ -2,19 +2,32 @@
2
2
 
3
3
  ## Positioning
4
4
 
5
- agent-guard is **Agent Reliability Infrastructure**: it lowers the
6
- probability that an autonomous agent causes irreversible loss through a
7
- misjudged deletion, a mis-expanded command, or mistaken context - and it
8
- leaves a recovery path and an evidence trail when anything destructive does
9
- happen. It is explicitly *not* a sandbox or security boundary (see
10
- `threat-model.md`).
5
+ agent-guard is **Agent Reliability Infrastructure** with three main
6
+ capabilities: Exfil-guard checks text for disclosure risks, Delete-guard
7
+ preserves recovery paths for supported destructive operations, and Guard-lab
8
+ provides controlled experiments with bounded evidence. The
9
+ [threat model](threat-model.md) describes the trust and coverage limits.
11
10
 
12
- The shared Core, Decision Protocol, and Skills are the product boundary.
13
- Harness adapters are replaceable translations onto host-native hooks; DSH,
14
- Claude Code, Codex, or any future host is a compatibility target rather than
15
- the identity of the project.
11
+ The shared Core, Decision Protocol, Skills and Lab CLI define these workflows.
12
+ Adapters connect them to host-native hooks or explicit tools. DSH, Claude
13
+ Code, Codex and other hosts have separate compatibility and coverage evidence;
14
+ see the [capability matrix](../guides/harness-capabilities.md).
16
15
 
17
- ## The four pillars and where they live
16
+ ## Three functional areas
17
+
18
+ | Main capability | Functions and implementation | Contract and guides |
19
+ |---|---|---|
20
+ | **Exfil-guard** | Text detection/redaction in `core/redaction.py`, disclosure decisions in `core/policy.py`, and safe config views in `core/safe_view.py` | [Exfil-guard Skill](../../skills/exfil-guard/SKILL.md) |
21
+ | **Delete-guard** | Classification, authorization, recovery and audit; Cleanup Copilot includes read-only inventory/measurement and delegates reviewed execution to `safe_delete`; MCP exposes explicit tools while its doctor performs read-only state queries | [Delete-guard Skill](../../skills/delete-guard/SKILL.md) · [Cleanup](../guides/cleanup-plan.md) · [Limits](../guides/deletion-limits.md) · [MCP](../guides/mcp.md) |
22
+ | **Guard-lab** | `guard_lab.py` and `core/lab.py` provide a user-controlled diagnostic plane: calibration, declared-channel observation and matched comparisons | [Lab workflow and evidence](../lab/guard-lab.md) |
23
+
24
+ Core and adapters provide shared infrastructure. The
25
+ [recovery-audit Skill](../../skills/recovery-audit/SKILL.md) supplies an auxiliary
26
+ workflow for reconstructing workspaces and auditing incident recovery.
27
+
28
+ <a id="the-four-pillars-and-where-they-live"></a>
29
+
30
+ ## Delete-guard's four pillars
18
31
 
19
32
  | Pillar | Question it answers | Component |
20
33
  |---|---|---|
@@ -278,6 +291,30 @@ FORBIDDEN (BLOCK, never askable).
278
291
  feed a Lab observation into Core policy or claim to ban model calls. A real
279
292
  block would require a host hook or request gateway that owns the call.
280
293
 
294
+ <a id="read-only-cleanup-observations-unreleased"></a>
295
+
296
+ ## Read-only cleanup observations (0.2.9)
297
+
298
+ `core/cleanup_groups.py` supplies bounded directory-group discovery and
299
+ explicit-scope measurement to the Cleanup CLI. The MCP adapter delegates its
300
+ two new read-only tools to that same CLI, keeping one implementation and a
301
+ fixed original workspace. This addition starts in 0.2.9 and is absent from 0.2.8.
302
+
303
+ Discovery reads a shallow frontier, recognizes environments before cache
304
+ markers, and groups application-managed caches without expanding them.
305
+ Path hints prioritize work within the existing budget; incomplete frontiers
306
+ and unknown sizes stay explicit. A follow-up scope is a new bounded
307
+ observation, not a whole-workspace completion claim. Measurement streams
308
+ metadata into a digest and per-scope/global inode maps, omits protected
309
+ subtrees, and never follows links. Observed subset completeness is separate
310
+ from whole-size completeness.
311
+
312
+ Independent observation schemas and IDs cannot be used as executable Cleanup
313
+ plans. All rows remain nonselectable. A shared Core projection for complete
314
+ ordinary artifacts does not check admission or grant approval. The existing
315
+ plan confirmation and safe_delete pipeline remains responsible for mutation.
316
+ See [result and limit contracts](../guides/cleanup-plan.md#directory-overview-and-measurement-unreleased).
317
+
281
318
  ## Read-only quarantine queries
282
319
 
283
320
  core/trash_index.py exposes list_trash_locations for CLI, agent and future
@@ -305,9 +342,21 @@ order of value:
305
342
 
306
343
  ## Delivery status and design directions
307
344
 
308
- This document covers version [0.2.7](../releases/release-notes-0.2.7.md), which
309
- adds reviewed Cleanup plans, shared deletion admission and optional local
310
- MCP tools. Confirm availability through the exact GitHub release and npm
345
+ Version [0.2.9](../releases/release-notes-0.2.9.md) adds read-only directory
346
+ observations and two MCP tools, speeds up existing planning, and corrects
347
+ the normal-corpus test boundary. The original five operations and mutation
348
+ contracts remain in place. The version decision is recorded in
349
+ [compatibility](compatibility.md#029-cleanup-maintenance-decision).
350
+
351
+ Version [0.2.8](../releases/release-notes-0.2.8.md) adds MCP connection
352
+ diagnosis and protocol-interruption validation. The existing five tools,
353
+ deletion policy and recovery format
354
+ retain their contracts. Direct-service diagnosis, actual-host connection,
355
+ model use and native interception have separate evidence requirements.
356
+
357
+ Version [0.2.7](../releases/release-notes-0.2.7.md) introduced reviewed Cleanup
358
+ plans, shared deletion admission and optional local MCP tools. Confirm
359
+ availability through the exact GitHub release and npm
311
360
  version links in those notes; a source version does not establish publication.
312
361
  Earlier stable 0.2.6/0.2.5, opt-in 0.2.4-hotfix.1 and prerelease 0.2.5-rc3
313
362
  retain their separate artifacts and evidence.
@@ -4,9 +4,13 @@ agent-guard's promise is recoverability. A promise is only as good as its
4
4
  stability over time - this page states exactly what may change and what
5
5
  may not, per release class.
6
6
 
7
- This contract covers [0.2.7](../releases/release-notes-0.2.7.md). Use its exact
8
- GitHub release and npm version links to confirm availability; a version in
9
- source or a local tarball does not establish publication.
7
+ Version [0.2.9](../releases/release-notes-0.2.9.md) adds read-only Cleanup
8
+ inventory and measurement, faster planning and a repository-corpus test fix.
9
+ Version [0.2.8](../releases/release-notes-0.2.8.md) adds diagnosis and
10
+ reliability maintenance to the published
11
+ [0.2.7](../releases/release-notes-0.2.7.md) baseline. Use exact GitHub release
12
+ and npm version links to confirm availability; a version in source or a local
13
+ tarball does not establish publication.
10
14
  Earlier release [0.2.6](../releases/release-notes-0.2.6.md) carries cumulative
11
15
  RC maintenance and the feedback/diagnostic additions below. The opt-in
12
16
  prerelease [0.2.5-rc3](../releases/release-notes-0.2.5-rc3.md), earlier stable
@@ -19,6 +23,11 @@ earlier releases.
19
23
  The maintainer selected **0.2.7** for Cleanup Copilot, deletion admission and
20
24
  optional MCP tools. The bounded versioning decision is recorded below; the
21
25
  separate 0.3.0 plan remains paused.
26
+ The later **0.2.8** selection is independently scoped to MCP diagnosis and
27
+ reliability maintenance, as recorded below; earlier exceptions do not grant
28
+ permission to change unrelated policy under a patch number.
29
+ The **0.2.9** selection has its own bounded decision for the Cleanup
30
+ observation interfaces and accompanying performance/test maintenance below.
22
31
 
23
32
  RC3 publishes defensive research and an example around the existing four
24
33
  zero-model controls. Experimental disclosure labels and private delegation
@@ -26,13 +35,70 @@ methods are not additions to the Decision Protocol or native-hook contract.
26
35
  No production dependency, policy verdict or storage/configuration migration
27
36
  is introduced by the research documentation.
28
37
 
38
+ <a id="unreleased-cleanup-observation-additions"></a>
39
+
40
+ ## Cleanup observation additions (0.2.9)
41
+
42
+ Version 0.2.9 adds independent read-only discovery/measurement schemas,
43
+ CLI modes and MCP tools. They are absent from published 0.2.8 and cannot
44
+ produce an executable plan or approval. Its MCP server advertises seven
45
+ tools; its doctor verifies that set and invokes only the original three
46
+ state queries. Published 0.2.8 retains its five-tool contract. Use doctor and
47
+ server from the same installation; identical version text in a working
48
+ checkout does not establish identical bytes or tools.
49
+
50
+ Existing default Cleanup plans, execution confirmation, original five MCP
51
+ tools, deletion policy and recovery formats retain their interfaces. No
52
+ dependency, configuration or storage migration is introduced.
53
+ See [new observation semantics](../guides/mcp.md#cleanup-observations-029).
54
+ The versioned checkpoints below describe their original release scope.
55
+
56
+ The new CLI modes, independent observation JSON and two MCP tools are
57
+ additive public interfaces, even though they grant no deletion permission.
58
+ The maintainer selected 0.2.9 through the new bounded decision below;
59
+ earlier patch-version exceptions do not authorize it. The paused 0.3.0
60
+ research roadmap is a separate scope decision and is not resumed.
61
+
29
62
  ## The adapter contract (frozen surface)
30
63
 
64
+ <a id="mcp-doctor-028-development"></a>
65
+
66
+ ### MCP doctor (0.2.8)
67
+
68
+ `doctor.py mcp` is an explicit local diagnosis path. It accepts the selected
69
+ Python interpreter, existing workspace, optional reviewed server script and
70
+ a diagnostic timeout; it does not parse or rewrite host configuration. It
71
+ checks the optional pinned SDK and its imports, service handshake/name/version,
72
+ the five-tool set and query annotations, workspace/quarantine binding and
73
+ successful status/transactions/gc_plan calls. The selected service version
74
+ must match the doctor's package version. It does not call a model or execute
75
+ deletion, restore, GC or budget-reset tools.
76
+
77
+ Its independent `schema_version: 1` report uses fixed `status`, `stage`, `code`,
78
+ `message`, `guidance` and `checks` fields rather than raw child stderr,
79
+ configuration contents or recovery/audit records. It keeps `host_connection`,
80
+ `model_delivery` and `host_interception` at `UNVERIFIED`: direct service
81
+ diagnosis cannot certify another client's loading or behavior. Exit `0` means
82
+ PASS, `1` means diagnostic failure and `2` remains argument-usage failure.
83
+ Diagnostic codes belong to this report, not the Decision Protocol reason-code
84
+ namespace. Existing Kimi/Claude doctor interfaces retain their semantics.
85
+ `diagnostic_stderr_bytes` is a count, not raw stderr. A successful status check
86
+ also records `deletion_admission` as `BLOCKED` or `READABLE`; the latter means
87
+ the information was inspected, not that deletion is authorized. A connection
88
+ PASS can coexist with blocked admission, which the text renderer highlights.
89
+ The 5–120 second diagnostic deadline defaults to 30 seconds; service-process
90
+ shutdown can add up to three seconds of process waits and one second of reader-thread waiting.
91
+
92
+ The SDK remains separately optional, including when invoking Core/CLI or
93
+ doctor help. Changing package/helper bytes can change existing doctor runtime
94
+ fingerprints and produce `DRIFTED`; an old baseline is not automatically
95
+ replaced. See [options, result scope and recovery after a lost response](../guides/mcp.md#diagnose-a-local-service-028).
96
+
31
97
  <a id="local-mcp-tools-027-candidate"></a>
32
98
 
33
99
  ### Local MCP tools (0.2.7)
34
100
 
35
- The checkout adds an optional local stdio MCP server with five explicit tools:
101
+ The 0.2.7 release introduced an optional local stdio MCP server with five explicit tools:
36
102
  safe_delete, ordinary restore, transactions, status and GC-plan preview.
37
103
  It invokes existing CLI operations without a shell, preserves policy/audit/
38
104
  recovery semantics and binds workspace/session identity at trusted startup.
@@ -55,7 +121,9 @@ and did not run Node; its cause remains undetermined. The second full run
55
121
  passed 1123 Python cases and both Node groups in 1143.435 seconds, with no
56
122
  failures, errors, skips or timeouts. Neither invoked npm directly or changed
57
123
  the runtime/tests. A 154-file offline installation and three real Kimi 2.3.0
58
- native-MCP trials passed; Claude/Cursor/Codex setup examples remain docs-only.
124
+ native-MCP trials passed; at that checkpoint Claude/Cursor/Codex setup examples
125
+ were docs-only. Later Codex 0.165.0 acceptance of the published 0.2.7 package
126
+ is recorded separately in the [MCP guide](../guides/mcp.md#codex-01650-with-published-027).
59
127
  Without the optional SDK, seven protocol tests skip. The added SDK-backed
60
128
  Python 3.10/3.13 CI job had no remote execution at the 2026-10-29 local
61
129
  preparation checkpoint. See
@@ -233,6 +301,54 @@ While the major version is `0`:
233
301
  | check.py CLI flags removed or re-semanticized | major + MIGRATION.md |
234
302
  | Default policy verdict changes for an existing shape | minor + entry in docs/history/friction.md |
235
303
 
304
+ <a id="029-cleanup-maintenance-decision"></a>
305
+
306
+ ### 0.2.9: bounded Cleanup maintenance decision
307
+
308
+ The maintainer selected **0.2.9** for read-only directory discovery and
309
+ measurement, planning performance and the normal-corpus test correction.
310
+ The new CLI modes, version-1 observation schemas and two MCP tools are
311
+ additive public interfaces carried as this release's explicit maintenance
312
+ exception. The general release-class promises remain in force; this decision
313
+ does not authorize other patch releases or resume the 0.3.0 research plan.
314
+
315
+ Upgrade both doctor and server from the same package: 0.2.9 expects seven
316
+ tools, while 0.2.8 expects five. Existing installations need an explicit
317
+ upgrade. Changed package/helper bytes may make an older doctor fingerprint
318
+ baseline `DRIFTED`; review it rather than silently replacing it.
319
+
320
+ The original five MCP operations, default executable plans and confirmation,
321
+ Decision classes/reasons, default deletion rules, budgets, recovery manifests,
322
+ ordinary restore and preview-only MCP GC retain their contracts. Observation
323
+ IDs and policy projections cannot authorize deletion. No dependency or
324
+ configuration/storage migration is introduced. See the
325
+ [release notes](../releases/release-notes-0.2.9.md).
326
+
327
+ <a id="028-diagnosis-maintenance-decision"></a>
328
+
329
+ ### 0.2.8: bounded diagnosis maintenance decision
330
+
331
+ The maintainer selected **0.2.8** for the explicit MCP doctor path, real
332
+ protocol-interruption checks and their documentation. Earlier doctor drift
333
+ and live-sentinel additions were classified as minor below. The new optional
334
+ diagnostic surface is carried as this version's bounded maintenance decision;
335
+ the 0.2.7 exception is not inherited and the general release-class promises
336
+ remain in force.
337
+
338
+ The independent MCP doctor parameters, version-1 diagnosis report and exit
339
+ codes are the upgrade-visible additions. Package/helper changes may affect
340
+ existing doctor fingerprints. The five MCP tools and their arguments,
341
+ Decision classes/reasons, default deletion policy, persistent accounting,
342
+ recovery manifests, ordinary restore and preview-only MCP GC retain their
343
+ contracts. No configuration/storage migration or default SDK installation is
344
+ introduced. The diagnosis checks a selected service; it adds no native host
345
+ interception or client configuration management. The 0.3.0 and commercial
346
+ plans are not resumed.
347
+
348
+ Source validation, installed-package and workflow results retain their
349
+ separate checkpoints in the
350
+ [0.2.8 notes](../releases/release-notes-0.2.8.md#validation-status).
351
+
236
352
  <a id="027-candidate-bounded-maintainer-selected-exception"></a>
237
353
 
238
354
  ### 0.2.7: bounded maintainer-selected exception
@@ -14,6 +14,82 @@ layout or Git exclude rules. It also suppresses project bytecode creation.
14
14
  Planning does not call `safe_delete --dry-run`, whose metadata side effects
15
15
  remain documented in the [policy reference](../../skills/delete-guard/references/policy.md#assessment-and-dry-run-side-effects).
16
16
 
17
+ <a id="directory-overview-and-measurement-unreleased"></a>
18
+
19
+ ## Directory overview and measurement (0.2.9)
20
+
21
+ These modes are introduced in **0.2.9**, not included in the published 0.2.8
22
+ package. They share the stdlib-only Core with two new
23
+ [read-only MCP tools](mcp.md#cleanup-observations-029). The existing
24
+ default plan and explicit execution workflow below keep their interfaces.
25
+ This addition remains part of Delete-guard's Cleanup Copilot.
26
+
27
+ Start with a bounded overview, then inspect a specific unexpanded directory
28
+ or measure explicit scopes, always keeping the original workspace root:
29
+
30
+ ```sh
31
+ python3 /absolute/path/to/agent-guard/skills/delete-guard/scripts/cleanup.py \
32
+ --root /absolute/path/to/project --discover --json
33
+ python3 /absolute/path/to/agent-guard/skills/delete-guard/scripts/cleanup.py \
34
+ --root /absolute/path/to/project --discover --scope .work --json
35
+ python3 /absolute/path/to/agent-guard/skills/delete-guard/scripts/cleanup.py \
36
+ --root /absolute/path/to/project --measure --scope build --scope .pytest_cache --json
37
+ ```
38
+
39
+ Scopes are literal, non-overlapping directories below that fixed root;
40
+ directory-link components, protected scopes, outside paths and the workspace
41
+ root itself are refused. Without scopes, discovery starts at the root.
42
+ Measurement requires scopes. Quote spaces; use `--scope=-name` for a leading
43
+ dash. A scoped discovery starts a new bounded observation rather than a
44
+ cursor or a claim that previous results now cover the entire workspace.
45
+
46
+ | Mode | Default limits | Output |
47
+ |---|---|---|
48
+ | `--discover` | Depth 4 per selected root, 10000 entries total, 256 expanded directories, 512 entries per directory | Compact overview; JSON includes all observed groups, review branches and unexpanded paths; all sizes unknown |
49
+ | `--measure` | Depth 32 per scope, 20000 entries shared across scopes | Logical file/link sizes with inode deduplication, protected roots, issues and completeness per scope |
50
+
51
+ `--max-entries` and `--max-depth` override their mode's positive limits in the
52
+ CLI. The MCP tools only allow lowering the stated defaults. These new modes
53
+ have been exercised on Linux ARM64/PRoot; their no-follow cache-marker opening
54
+ uses POSIX facilities and has no Windows acceptance evidence.
55
+
56
+ Discovery recognizes protected boundaries before runtime markers, cache
57
+ markers and known artifact patterns. A regular `pyvenv.cfg` takes precedence
58
+ over `CACHEDIR.TAG`; it identifies an environment hint, not an unused runtime.
59
+ A valid cache signature and the name `uv` provide an ownership hint only.
60
+ Managed caches stay grouped without suggesting their internal build fragments.
61
+ Cache/artifact path hints affect queue order, not permission or proof of
62
+ obsolescence. No age or filename heuristic declares content discarded.
63
+
64
+ JSON uses independent `cleanup_group_discovery/v1` and
65
+ `cleanup_group_measurement/v1` schemas with an `observation_id`, **no
66
+ executable `plan_id`**. Every observation has `execution_supported: false`
67
+ and every group has `selectable: false`. Discovery's `frontier_complete`
68
+ only describes its bounded frontier; `workspace_scan_complete` stays false.
69
+ Inspect `coverage.unexpanded`, limits and issues before choosing a scope.
70
+
71
+ Measurement never follows links. Protected subtrees and external/protected
72
+ link boundaries are omitted; `size_bytes: null` means unknown, not zero.
73
+ `observed_bytes` counts the observed subset and does not predict freed disk
74
+ space. `observed_subset_complete` may be true while `size_complete` and
75
+ `interior_checked` are false because protection prevents a whole-size claim.
76
+ The metadata digest is not a content hash or atomic snapshot. Scans read
77
+ metadata and at most 43 bytes per examined cache tag, plus existing Guard
78
+ configuration and Git facts; they do not parse database or cache payloads.
79
+
80
+ For complete ordinary artifact scopes, `core_policy` may show a shared Core
81
+ projection. Approval remains `NOT_GRANTED`, budget `NOT_CHECKED`, and the
82
+ projection does not grant execution. Application-managed caches remain
83
+ subject to their own consistency and locking protocol.
84
+
85
+ Exit 0 means the requested frontier or observed measurement subset completed;
86
+ 1 retains partial observations after limits, I/O errors or observed source
87
+ changes; 2 means invalid options or refusal. A protected unknown whole size
88
+ can therefore coexist with measurement exit 0. None authorizes deletion.
89
+ `--scope` requires these new modes; they reject `--discard`, `--protect`,
90
+ `--execute`, `--plan-id` and `--select`. To delete, produce a separate reviewed
91
+ plan using the existing workflow; an observation cannot be promoted into one.
92
+
17
93
  ## Review a plan
18
94
 
19
95
  From the intended workspace, run:
@@ -63,6 +139,17 @@ Unknown subtrees collapse into review rows unless generated, discarded or
63
139
  protected descendants need to be shown. Candidate directories and their
64
140
  children are not offered as overlapping selections.
65
141
 
142
+ The planner reuses ordinary-file metadata and its batched Git facts within
143
+ one scan. Directory and link boundaries still receive full checks. This does
144
+ not make a partial scan complete or change the scan limits. Execution still
145
+ rescans the plan and reads current policy and Git facts.
146
+
147
+ A regenerable classification does not verify an application's cache protocol.
148
+ For example, [uv documents its cache consistency and locking requirements](https://docs.astral.sh/uv/concepts/cache/#cache-safety)
149
+ and warns against directly changing cache contents. Review such managed
150
+ caches separately; the planner does not coordinate their application locks
151
+ or automatically invoke native cache-cleaning commands.
152
+
66
153
  ## Confirm and execute
67
154
 
68
155
  Copy the plan's full `plan_id`, select exact rows marked `selectable`, and
@@ -125,6 +212,10 @@ retrying. No automatic purge or rollback runs.
125
212
 
126
213
  ## Sizes, limits and output
127
214
 
215
+ This section describes plan JSON and the confirmation workflow. The
216
+ [read-only observation modes](#directory-overview-and-measurement-unreleased)
217
+ have their own schemas and limits.
218
+
128
219
  Sizes are logical file bytes, with hardlinks counted once per entry and per
129
220
  category summary. Directory metadata is omitted; links use their own size
130
221
  and directory links are not traversed. Protected subtree sizes are unknown.
@@ -170,6 +261,12 @@ before writing a new baseline at a new path.
170
261
 
171
262
  ## 中文摘要
172
263
 
264
+ 0.2.9 新增 `--discover` 目录概况、`--measure --scope PATH` 指定范围计量,
265
+ 并提供对应的 `cleanup_discover`/`cleanup_measure` MCP 工具;已发布 0.2.8
266
+ 不含这些能力。按范围继续发现仍保持原工作区,未展开部分和大小未知必须保留。
267
+ 这些观察不生成可执行计划或删除许可,MCP 的 `ok: true, partial: true` 也不代表
268
+ 完整扫描。执行仍需另外生成并审阅下面的既有计划。
269
+
173
270
  本功能自 0.2.7 加入。默认扫描只输出计划,不修改工作区;“明确废弃”仅来自
174
271
  调用者显式声明,旧文件/未跟踪文件不会自动变为垃圾。执行必须提供计划 ID、选定
175
272
  具体条目并由操作者在终端确认,确认后复查,再逐项走现有 safe_delete。普通文件
@@ -10,10 +10,11 @@ Agent Guard 提供恢复保护、外发检测和用户控制的行为验测。
10
10
 
11
11
  ## Select the package root
12
12
 
13
- This guide covers [0.2.7](../releases/release-notes-0.2.7.md), with Cleanup
14
- plans, deletion admission limits and optional local MCP tools. Confirm the
15
- exact [GitHub release](https://github.com/mokuyoaxis/agent-guard/releases/tag/0.2.7)
16
- and [npm version](https://www.npmjs.com/package/@mokuyoaxis/agent-guard/v/0.2.7)
13
+ This guide covers [0.2.9](../releases/release-notes-0.2.9.md), with read-only
14
+ Cleanup inventory and measurement, faster plan scans, MCP connection
15
+ diagnosis and the existing deletion/recovery tools. Confirm the
16
+ exact [GitHub release](https://github.com/mokuyoaxis/agent-guard/releases/tag/0.2.9)
17
+ and [npm version](https://www.npmjs.com/package/@mokuyoaxis/agent-guard/v/0.2.9)
17
18
  are available before installing from the registry. A checkout or manifest
18
19
  does not establish publication or the current npm `latest` channel.
19
20
 
@@ -26,7 +27,7 @@ backports quarantine protection onto the stable line.
26
27
  Once the exact version is available, use a user-selected stable prefix:
27
28
 
28
29
  ```sh
29
- npm install --prefix /absolute/path/to/agent-guard-install @mokuyoaxis/agent-guard@0.2.7
30
+ npm install --prefix /absolute/path/to/agent-guard-install @mokuyoaxis/agent-guard@0.2.9
30
31
  ```
31
32
 
32
33
  The package root is
@@ -42,7 +43,7 @@ If that version is unavailable, use a reviewed source checkout or a checked
42
43
  local tarball. Install the tarball into a separate prefix:
43
44
 
44
45
  ```sh
45
- npm install --offline --ignore-scripts --legacy-peer-deps --no-audit --no-fund --prefix /absolute/path/to/agent-guard-review /absolute/path/to/mokuyoaxis-agent-guard-0.2.7.tgz
46
+ npm install --offline --ignore-scripts --legacy-peer-deps --no-audit --no-fund --prefix /absolute/path/to/agent-guard-review /absolute/path/to/mokuyoaxis-agent-guard-0.2.9.tgz
46
47
  ```
47
48
 
48
49
  The review package root is
@@ -1,6 +1,6 @@
1
1
  # Harness capability and evidence matrix
2
2
 
3
- This matrix accompanies [0.2.7](../releases/release-notes-0.2.7.md).
3
+ This matrix accompanies [0.2.9](../releases/release-notes-0.2.9.md).
4
4
  Confirm availability through the exact GitHub release and npm version links
5
5
  in those notes; a source version does not establish publication.
6
6
  Published prerelease, checked on 2026-10-19:
@@ -97,9 +97,26 @@ is separate from the standard-library Core/CLI requirements.
97
97
 
98
98
  The guide records the 0.2.7 installed-package/protocol checks and the earlier
99
99
  bounded Kimi Code 2.3.0 root-agent native-MCP trials with their original
100
- checkpoint and gateway limits. These observations do not expand the native
101
- hook rows above or establish live Claude/Cursor/Codex, subagent or additional
102
- platform coverage. Client setup examples remain documentation guidance.
100
+ checkpoint and gateway limits. A separate
101
+ [Codex 0.165.0 acceptance](mcp.md#codex-01650-with-published-027) used published
102
+ 0.2.7: three actual-client groups and three real-model tasks, with 16 model MCP
103
+ calls. Its recorded results and incomplete native-client exit metadata retain
104
+ their stated limits. These cooperative MCP observations do not expand the
105
+ native-hook rows above or establish live Claude/Cursor, arbitrary subagent,
106
+ other-version or additional-platform coverage. Untested client setup examples
107
+ remain documentation guidance.
108
+
109
+ The [MCP doctor introduced in 0.2.8](mcp.md#diagnose-a-local-service-028)
110
+ checks a selected service through handshake and read-only calls. Its PASS
111
+ does not establish host connection, model use or native interception; those
112
+ remain separate evidence levels.
113
+
114
+ Version 0.2.9 adds the read-only `cleanup_discover` and `cleanup_measure`
115
+ tools. Local source checks include real-project stdio observations and one
116
+ bounded Kimi Code inventory task in a synthetic workspace (three MCP calls).
117
+ That task covers the new observation path, not a fresh cross-host acceptance
118
+ of the published package or native interception. See the
119
+ [0.2.9 validation](../releases/release-notes-0.2.9.md#validation).
103
120
 
104
121
  ## Acceptance for each native adapter
105
122