@mokuyoaxis/agent-guard 0.2.8 → 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.
@@ -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,11 +10,11 @@ Agent Guard 提供恢复保护、外发检测和用户控制的行为验测。
10
10
 
11
11
  ## Select the package root
12
12
 
13
- This guide covers [0.2.8](../releases/release-notes-0.2.8.md), with MCP
14
- connection diagnosis and recovery validation, plus the Cleanup plans,
15
- deletion admission limits and optional tools introduced in 0.2.7. Confirm the
16
- exact [GitHub release](https://github.com/mokuyoaxis/agent-guard/releases/tag/0.2.8)
17
- and [npm version](https://www.npmjs.com/package/@mokuyoaxis/agent-guard/v/0.2.8)
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)
18
18
  are available before installing from the registry. A checkout or manifest
19
19
  does not establish publication or the current npm `latest` channel.
20
20
 
@@ -27,7 +27,7 @@ backports quarantine protection onto the stable line.
27
27
  Once the exact version is available, use a user-selected stable prefix:
28
28
 
29
29
  ```sh
30
- npm install --prefix /absolute/path/to/agent-guard-install @mokuyoaxis/agent-guard@0.2.8
30
+ npm install --prefix /absolute/path/to/agent-guard-install @mokuyoaxis/agent-guard@0.2.9
31
31
  ```
32
32
 
33
33
  The package root is
@@ -43,7 +43,7 @@ If that version is unavailable, use a reviewed source checkout or a checked
43
43
  local tarball. Install the tarball into a separate prefix:
44
44
 
45
45
  ```sh
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.8.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
47
47
  ```
48
48
 
49
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.8](../releases/release-notes-0.2.8.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:
@@ -111,6 +111,13 @@ checks a selected service through handshake and read-only calls. Its PASS
111
111
  does not establish host connection, model use or native interception; those
112
112
  remain separate evidence levels.
113
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).
120
+
114
121
  ## Acceptance for each native adapter
115
122
 
116
123
  1. Pin host version, profile/configuration, tool name, shell dialect, and
@@ -15,6 +15,11 @@ and protocol-interruption validation; see the
15
15
  The later [Codex 0.165.0 acceptance](#codex-01650-with-published-027) below used
16
16
  the published 0.2.7 package and is separate from both development checkpoints.
17
17
 
18
+ Version **0.2.9** adds `cleanup_discover` and `cleanup_measure`.
19
+ Version 0.2.8 retains the original five tools. The new read-only workflow
20
+ and its separate partial-result contract are described
21
+ [below](#cleanup-observations-029).
22
+
18
23
  MCP gives a supporting coding-agent client an explicit way to use the existing
19
24
  safe deletion and recovery operations. It does **not** intercept shell `rm`,
20
25
  scripts, editor deletion or tools that bypass this server. Keep a compatible
@@ -85,7 +90,7 @@ this server alone does not provide that bridge. Existing
85
90
 
86
91
  ## Diagnose a local service (0.2.8)
87
92
 
88
- From a 0.2.8 installation or checkout, run:
93
+ From a 0.2.8 or later installation or checkout, run:
89
94
 
90
95
  ```sh
91
96
  python3 -B /absolute/path/to/agent-guard/doctor.py mcp \
@@ -109,7 +114,10 @@ The checks cover:
109
114
  1. The selected interpreter, pinned SDK metadata and actual SDK imports.
110
115
  2. A classic `2025-06-18` stdio handshake, the `agent-guard` service identity
111
116
  and a service version matching the doctor's package version.
112
- 3. The five expected tools and read-only annotations for the query tools.
117
+ 3. The expected tools and query annotations for this installation: five in
118
+ 0.2.8, seven in 0.2.9. Use doctor and server
119
+ from the same installation; matching package version text alone does not
120
+ establish an identical tool set.
113
121
  4. Successful `status`, `transactions` and `gc_plan` calls, including the
114
122
  requested workspace and its local quarantine binding reported by `status`.
115
123
 
@@ -175,6 +183,8 @@ or atomic rollback. Final candidate results are recorded in the
175
183
  | `transactions` | none | List the selected workspace's recovery transactions |
176
184
  | `status` | optional integer `tail` (0–100, default 10) | Inspect recovery state, limits and recent audit information |
177
185
  | `gc_plan` | none | Preview the existing transaction GC plan; never execute it |
186
+ | `cleanup_discover` (0.2.9) | optional literal directory `scopes`, `max_entries` (1–10000), `max_depth` (1–4) | Bounded read-only overview; no executable plan |
187
+ | `cleanup_measure` (0.2.9) | required directory `scopes`, optional `max_entries` (1–20000), `max_depth` (1–32) | Read-only metadata measurement; protected whole sizes stay unknown |
178
188
 
179
189
  Paths are literal names, relative to the fixed workspace or absolute; the
180
190
  Core still refuses outside targets. Glob characters name actual files rather
@@ -221,6 +231,50 @@ cancellation means nothing moved. Do not automatically retry a mutating call
221
231
  after a client timeout or disconnection. The existing recovery, concurrency
222
232
  and same-UID boundaries remain; this server is not an OS sandbox.
223
233
 
234
+ <a id="cleanup-observations-unreleased"></a>
235
+
236
+ ## Cleanup observations (0.2.9)
237
+
238
+ First call `cleanup_discover` with `{}`. Its compact `overview` accompanies
239
+ the complete observed `groups`, `review_branches` and `coverage.unexpanded`
240
+ lists. Choose exact directory scopes for a follow-up discovery or measurement:
241
+
242
+ ```json
243
+ {"name":"cleanup_discover","arguments":{"scopes":[".work"]}}
244
+ ```
245
+
246
+ ```json
247
+ {"name":"cleanup_measure","arguments":{"scopes":["build",".pytest_cache"]}}
248
+ ```
249
+
250
+ Scopes accept at most 64 strings, stay below the same workspace, and cannot
251
+ overlap, cross protection or contain directory links. Omitting discovery
252
+ scopes starts at the root; measurement requires a nonempty selection. No
253
+ workspace, environment, approval, plan ID or execution override is accepted.
254
+ The limits are shared across all scopes in one call. A follow-up scope starts
255
+ a fresh observation rather than completing or authorizing an old one.
256
+
257
+ Both tools are read-only and preserve source files, audit and recovery state.
258
+ They do not call advisory safe_delete, which can write normal guard metadata.
259
+ Their results use the independent observation schemas described in the
260
+ [Cleanup guide](cleanup-plan.md#directory-overview-and-measurement-unreleased).
261
+ Runtime and managed-cache labels are hints; all groups remain nonselectable.
262
+ Do not treat a Core policy projection or successful inspection as approval.
263
+
264
+ A valid partial observation returns `ok: true`, `partial: true` and is not an
265
+ MCP `isError`. The original CLI exit code remains present, including exit 1
266
+ for a limited frontier or incomplete observed subset. `partial` also remains
267
+ true when measurement exit 0 has a protected unknown whole size. Inspect the
268
+ underlying coverage, issues, protected roots and completeness fields; `ok`
269
+ means the tool returned usable observations, not that the workspace is fully
270
+ scanned or a target may be deleted. Invalid options, unavailable subprocesses
271
+ and protocol failures remain errors. These semantics do not change the
272
+ original five tools' error or mutation contracts.
273
+
274
+ The doctor verifies the two new tool annotations but continues to invoke
275
+ only `status`, `transactions` and `gc_plan`; diagnosis does not silently start
276
+ directory discovery or measurement.
277
+
224
278
  ## Configure a client
225
279
 
226
280
  The following examples register a local server; they do not run deletion or
@@ -296,8 +350,10 @@ installed version rather than copying another client's configuration shape.
296
350
 
297
351
  ## Verify and report
298
352
 
299
- 1. Confirm the interpreter starts the server and the client discovers the five
300
- tools. Check stderr when a dependency or executable cannot be found.
353
+ 1. Confirm the interpreter starts the server and the client discovers the
354
+ tools for that installation: five in 0.2.8, seven in 0.2.9.
355
+ Check stderr when a dependency or executable cannot
356
+ be found, and reconnect after changing the selected installation.
301
357
  2. Call `status`, `transactions` and `gc_plan` in a disposable project; confirm
302
358
  preview leaves recovery payloads intact.
303
359
  3. Create a small synthetic valuable file, call `safe_delete`, verify a real
@@ -308,6 +364,14 @@ installed version rather than copying another client's configuration shape.
308
364
  results and unverified paths. A raw protocol test, a real client call and a
309
365
  real-model trial are different evidence levels.
310
366
 
367
+ For the 0.2.9 observation tools, separately call `cleanup_discover`
368
+ and `cleanup_measure` on explicit synthetic directory scopes. Check that
369
+ source files and recovery state stay unchanged, unknown sizes remain null,
370
+ and a limited result can have `ok: true, partial: true` without execution
371
+ permission. A successful query or the old five-tool acceptance records do
372
+ not establish that the new tools reached a model; see the
373
+ [current source validation](../releases/unreleased.md#current-validation-checkpoint).
374
+
311
375
  ## Recorded validation and remaining limits
312
376
 
313
377
  ### Codex 0.165.0 with published 0.2.7
@@ -335,7 +399,7 @@ tool exchanges supported the reported behavior, and the recorded process IDs
335
399
  were absent at the final check; the missing lifecycle metadata was not
336
400
  reconstructed. This limitation is separate from the three completed model
337
401
  tasks. These results apply to that published 0.2.7 artifact, exact Codex
338
- version and cooperative MCP path, not the 0.2.8 artifact, native
402
+ version and cooperative MCP path, not later artifacts, native
339
403
  shell/editor interception, arbitrary subagents or all Codex releases.
340
404
 
341
405
  ### Earlier preparation and Kimi checkpoints
@@ -0,0 +1,68 @@
1
+ # 0.2.9 — Cleanup inventory and faster scans
2
+
3
+ Cleanup Copilot can now show a bounded directory overview before a detailed
4
+ scan. Pick the directories that matter, measure those scopes, then decide
5
+ whether to prepare a cleanup plan. Both steps are available through CLI and MCP.
6
+
7
+ 本版主要改善清理前的盘点:先看目录概况,再计量选定范围。既有计划扫描也做了提速,
8
+ 删除仍按原来的计划、确认和 safe_delete 流程执行。
9
+
10
+ ## Changes
11
+
12
+ - `agent-guard-cleanup --discover` groups directory hints and reports areas
13
+ left unexpanded. `--measure --scope PATH` measures selected directories.
14
+ - MCP adds the read-only `cleanup_discover` and `cleanup_measure` tools.
15
+ Partial observations remain usable; incomplete coverage and unknown whole
16
+ sizes are explicit in the result.
17
+ - Plan scans reuse ordinary-file metadata and batch Git queries instead of
18
+ repeating them for every candidate.
19
+ - Cleanup previews keep recovery parents protected when reached through
20
+ directory aliases.
21
+ - The normal-corpus regression test uses Git-index paths and current file
22
+ contents. Private untracked experiments no longer enter that metric;
23
+ tracked and newly staged unsafe content still fails it.
24
+
25
+ ```sh
26
+ agent-guard-cleanup --discover --json
27
+ agent-guard-cleanup --measure --scope build --json
28
+ ```
29
+
30
+ Inventory results cannot authorize deletion. Cache labels are hints, and
31
+ protected or unmeasured whole sizes stay unknown. Scanning does not coordinate
32
+ application cache locks. See the
33
+ [Cleanup guide](https://github.com/mokuyoaxis/agent-guard/blob/0.2.9/docs/guides/cleanup-plan.md#directory-overview-and-measurement-029)
34
+ and [MCP guide](https://github.com/mokuyoaxis/agent-guard/blob/0.2.9/docs/guides/mcp.md#cleanup-observations-029).
35
+
36
+ ## Upgrade
37
+
38
+ Install the exact version after checking its
39
+ [GitHub release](https://github.com/mokuyoaxis/agent-guard/releases/tag/0.2.9)
40
+ and [npm page](https://www.npmjs.com/package/@mokuyoaxis/agent-guard/v/0.2.9):
41
+
42
+ ```sh
43
+ npm install --prefix /absolute/path/to/agent-guard-install @mokuyoaxis/agent-guard@0.2.9
44
+ ```
45
+
46
+ Upgrade doctor and server together: 0.2.9 expects seven MCP tools; 0.2.8
47
+ expects five. Older doctor fingerprint baselines may report `DRIFTED` after
48
+ the upgrade and need review. The optional `mcp==2.3.0` SDK remains a separate
49
+ installation; Core/CLI still needs Python 3.9+ and Git.
50
+
51
+ The maintainer selected 0.2.9 as a
52
+ [bounded maintenance exception](https://github.com/mokuyoaxis/agent-guard/blob/0.2.9/docs/design/compatibility.md#029-cleanup-maintenance-decision)
53
+ for these additions. The original five MCP operations, deletion rules,
54
+ budgets and recovery formats retain their contracts. There is no data or
55
+ configuration migration. The separate 0.3.0 research plan stays paused.
56
+
57
+ ## Validation
58
+
59
+ Before CI corrections, a local 0.2.9 candidate passed `npm test`: 1197 Python cases and both Node
60
+ groups, with the optional MCP SDK enabled and no failures, errors or skips.
61
+ All 16 real MCP protocol, doctor and interruption cases executed. Follow-up
62
+ alias and test-fixture regressions are checked separately; CI and Release
63
+ enforce the updated 1198-case suite before publication.
64
+
65
+ Earlier local checks also covered real-project stdio inventory and one Kimi
66
+ Code task in a synthetic workspace. That single task used three MCP calls;
67
+ it does not establish general host reliability, native shell interception or
68
+ application-cache deletion safety.
@@ -1,4 +1,158 @@
1
- # 0.2.8 and earlier maintenance history
1
+ # Unreleased changes and maintenance history
2
+
3
+ <a id="current-unreleased-scope"></a>
4
+
5
+ ## Current scope: 0.2.9
6
+
7
+ The maintainer selected **0.2.9** for the changes below. Confirm exact-version
8
+ availability through the [release notes](release-notes-0.2.9.md) before installation.
9
+ Cleanup Copilot and its observation tools remain part of **Delete-guard**.
10
+ The separate disclosure-authorization roadmap and commercial work stay paused.
11
+
12
+ | Area | Change | Entry |
13
+ |---|---|---|
14
+ | Directory inventory | Bounded overview, explicit-scope discovery and metadata measurement | [CLI workflow](../guides/cleanup-plan.md#directory-overview-and-measurement-unreleased) |
15
+ | MCP observations | `cleanup_discover` and `cleanup_measure`; partial data is distinct from a failed call | [Tool contract](../guides/mcp.md#cleanup-observations-unreleased) |
16
+ | Planning performance | Reuse ordinary-file metadata and batch Git facts within one plan | [Planner boundaries](../guides/cleanup-plan.md#review-a-plan) |
17
+ | Corpus regression | Define the normal text corpus by Git-index paths and current working-tree contents | [Contributor workflow](../../CONTRIBUTING.md) |
18
+
19
+ The default executable-plan workflow, original five MCP operations, deletion
20
+ policy, budgets and recovery formats retain their contracts. Overview and
21
+ measurement never grant execution permission. Use doctor and server from the
22
+ same installation; published 0.2.8 has five tools, this checkout has seven.
23
+ See the [latest local validation](#current-validation-checkpoint) before
24
+ interpreting historical counts or host evidence.
25
+
26
+ <a id="cleanup-directory-observations-and-mcp-unreleased"></a>
27
+
28
+ ## Cleanup directory observations and MCP (0.2.9)
29
+
30
+ Version 0.2.9 adds shared-Core directory discovery and selected-scope
31
+ measurement, exposed by `agent-guard-cleanup --discover|--measure` and the
32
+ MCP tools `cleanup_discover` / `cleanup_measure`. These additions are absent
33
+ from published 0.2.8. They remain under
34
+ Delete-guard's Cleanup Copilot, with no new production dependency or storage
35
+ migration.
36
+
37
+ Discovery groups runtime/cache hints, prioritizes cache/artifact path hints
38
+ within fixed limits, and records unexpanded areas. Explicit scopes continue
39
+ discovery under the same workspace. Measurement omits protected subtrees and
40
+ keeps unknown whole sizes distinct from observed bytes. All observations
41
+ remain nonselectable and produce no executable plan ID or approval; the
42
+ existing default plan and confirmed safe_delete workflow remain separate.
43
+
44
+ The MCP adapter returns valid partial observations with `ok: true` and
45
+ `partial: true`, preserving the CLI exit code and completeness details. The
46
+ original five tools retain their contracts. The source doctor expects seven
47
+ tools but still invokes only the original three read-only state queries.
48
+ Use doctor and server from the same installation.
49
+
50
+ See [CLI workflow and result fields](../guides/cleanup-plan.md#directory-overview-and-measurement-unreleased)
51
+ and [MCP partial-result semantics](../guides/mcp.md#cleanup-observations-unreleased).
52
+
53
+ <a id="cleanup-planning-performance-unreleased"></a>
54
+
55
+ ## Cleanup planning performance (0.2.9)
56
+
57
+ Version 0.2.9 reduces repeated ordinary-file path and metadata checks
58
+ and reuses batched Git facts when projecting candidate verdicts. Shared
59
+ decision rules retain their live execution entrypoint; deleting files still
60
+ checks current Git and protection settings. Scan limits, categories, plan
61
+ fingerprints, confirmation and deletion budgets keep their contracts.
62
+
63
+ This performance change is not part of the published 0.2.8 package. On its
64
+ own it changes no recognition rules or MCP tools; the separate observation
65
+ addition above supplies directory groups and read-only MCP entrypoints.
66
+ Neither coordinates application locks. See the [cleanup guide](../guides/cleanup-plan.md)
67
+ for planning and managed-cache boundaries. The earlier validation records
68
+ below retain their original versions and results.
69
+
70
+ <a id="repository-corpus-noise-regression-unreleased"></a>
71
+
72
+ ## Repository corpus noise regression (0.2.9)
73
+
74
+ The repository's normal-corpus test now reads current regular UTF-8 files
75
+ named by its own Git index. Tracked modifications and newly staged files are
76
+ included; untracked private adversarial experiments are outside this metric.
77
+ Git failures, a borrowed parent index and unreadable tracked files are not
78
+ silently accepted. Binary files and link targets are outside the text corpus.
79
+
80
+ This corrects the test's collection boundary without changing Exfil rules,
81
+ exemptions or private examples. Regressions check that unsafe tracked and new
82
+ staged content still fails, untracked examples still BLOCK when scanned
83
+ directly, and staging an example brings it into the corpus gate. New files
84
+ must be staged intentionally before this versioned-corpus pre-commit check;
85
+ it is not a whole-workspace safety scan. See the
86
+ [current validation](#current-validation-checkpoint); earlier failed
87
+ checkpoints remain recorded below.
88
+
89
+ ## Current validation checkpoint
90
+
91
+ Before the CI corrections below, the versioned 0.2.9 public candidate passed the literal `npm test`: 1197
92
+ Python cases and both Node groups, with no failures, errors or skips.
93
+ All 16 real MCP protocol/doctor/interruption cases executed with the existing
94
+ pinned SDK. The candidate's 227 public source files stayed unchanged during
95
+ the run. This is local candidate validation; remote CI and publication are
96
+ separate checks, available through the [0.2.9 notes](release-notes-0.2.9.md).
97
+
98
+ The first cross-version CI then exposed a test-fixture issue on Python 3.9
99
+ and 3.10: mocking `os.stat` did not inject the intended metadata error through
100
+ those versions' `Path.lstat` implementation. The fixture now injects at
101
+ `Path.lstat` and verifies that the fault was reached, retaining the original
102
+ error/incompleteness assertions. Further macOS logs exposed a preview fast
103
+ path that missed a configured recovery parent through a directory alias.
104
+ It now checks both recovery-path spellings before skipping classification;
105
+ a new alias regression reproduces the pre-fix failure. The HOME fixture uses
106
+ the scanner's physical path, and the read-only fixture disables detached Git
107
+ maintenance before its baseline commit. These corrections retain deletion
108
+ policy and live execution checks. The full run above keeps its original
109
+ checkpoint; subsequent validation uses 1198 public cases and is recorded
110
+ separately.
111
+
112
+ Before the version alignment, local `npm test` passed all 1504 Python cases (1197 in public
113
+ test modules and 307 existing private development cases) and both Node
114
+ groups, with the existing optional MCP SDK enabled. There were no failures,
115
+ errors, skips or automatic retries; the 214 frozen code/configuration inputs
116
+ remained unchanged. Eight new collection-boundary controls and direct scans
117
+ of the original eleven private samples confirm that the detector still BLOCKs
118
+ those samples. Exfil rules and the allowfile were not changed.
119
+
120
+ These are local working-tree results, not acceptance of the versioned
121
+ release or fresh remote CI. The source suite includes private development
122
+ cases absent from a public checkout; public-module and private counts are
123
+ listed separately. The subsequent Markdown consolidation changed no
124
+ production code or tests and did not repeat model trials. Versioned release
125
+ checks are recorded separately in the [0.2.9 notes](release-notes-0.2.9.md#validation).
126
+
127
+ Local checks include actual stdio discovery/measurement against a real
128
+ project and one bounded real Kimi Code inventory task in a synthetic
129
+ workspace (four model requests, three native MCP calls). The latter completed
130
+ scoped discovery and measurement, preserved unknown UV whole size and mixed
131
+ data uncertainty, and left fixture files unchanged. This is one host/task
132
+ sample, not general reliability, application-cache deletion safety or shell
133
+ interception evidence.
134
+
135
+ The overview remains bounded and may leave an incomplete frontier. Finding
136
+ registered roots does not establish a complete workspace scan. The model
137
+ trial's source/task boundaries remain separate from native shell interception
138
+ and application-cache deletion safety.
139
+
140
+ ### Earlier source checkpoints
141
+
142
+ At the earlier pre-corpus-fix checkpoint, the full local `npm test` run
143
+ completed 1496 Python cases (1189 in public test modules and 307 existing
144
+ private development cases), with one corpus
145
+ gate failure caused by existing private experiment files. The saved
146
+ pre-change view reproduced the same eleven hits; the then-current public-only
147
+ view passed that single gate. The two Node commands were then run separately
148
+ and passed. That original npm run remains recorded as failed; the public-only
149
+ gate check is not a second full-suite PASS. No Exfil exemption, production rule or
150
+ private fixture was changed to suppress it. The final 25 directory-group
151
+ controls and actual MCP/host checks passed; the earlier targeted run's
152
+ runpy-bootstrap fixture failure was corrected with its log retained.
153
+
154
+ These earlier results retain their failures and scope. They are not the
155
+ latest candidate's outcome; the successful follow-up run is recorded above.
2
156
 
3
157
  <a id="028-development-and-earlier-maintenance-history"></a>
4
158
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@mokuyoaxis/agent-guard",
3
- "version": "0.2.8",
3
+ "version": "0.2.9",
4
4
  "description": "Harness-neutral reliability infrastructure for AI coding agents: recoverable destructive actions, disclosure checks, controlled synthetic behaviour experiments, and a shared Core with optional native adapters.",
5
5
  "type": "module",
6
6
  "engines": {
@@ -51,11 +51,37 @@ Globs passed to `safe_delete` are expanded explicitly before anything moves.
51
51
  That is why `safe_delete '*.log'` works while `rm *.log` is blocked: the
52
52
  guard refuses opaque target sets, not cleanup work.
53
53
 
54
+ <a id="read-only-cleanup-inventory-unreleased-checkout"></a>
55
+
56
+ ## Read-only cleanup inventory (0.2.9)
57
+
58
+ From a 0.2.9 installation or checkout, start a cleanup
59
+ investigation with a bounded directory overview:
60
+
61
+ ```bash
62
+ python3 /absolute/path/to/agent-guard/skills/delete-guard/scripts/cleanup.py --discover --json
63
+ python3 /absolute/path/to/agent-guard/skills/delete-guard/scripts/cleanup.py --measure --scope build --json
64
+ ```
65
+
66
+ Keep the same workspace root when selecting scopes. Use
67
+ `--discover --scope PATH` to inspect an unexpanded directory. Environment and managed-cache
68
+ labels are hints; all groups remain nonselectable. Unknown whole sizes stay
69
+ null, and a complete observed subset is not a complete workspace scan.
70
+ The corresponding MCP tools are `cleanup_discover` and `cleanup_measure`;
71
+ `ok: true, partial: true` is usable partial data, never execution permission.
72
+
73
+ These modes are absent from published 0.2.8. For that package, use its
74
+ existing plan workflow below. With the new modes, produce a separate reviewed
75
+ plan before any execution; `observation_id` cannot replace `plan_id`. Review
76
+ application-managed cache consistency separately. See
77
+ [observation limits](../../docs/guides/cleanup-plan.md#directory-overview-and-measurement-unreleased)
78
+ and [MCP semantics](../../docs/guides/mcp.md#cleanup-observations-unreleased).
79
+
54
80
  <a id="cleanup-proposals-027-candidate"></a>
55
81
 
56
82
  ## Cleanup proposals (0.2.7)
57
83
 
58
- When asked to investigate workspace cleanup, start with a read-only plan:
84
+ To propose concrete executable candidates, produce a separate read-only plan:
59
85
 
60
86
  ```bash
61
87
  python3 /absolute/path/to/agent-guard/skills/delete-guard/scripts/cleanup.py --json