Add evidence contract and agentic evaluation loop

.github/workflows/test.yml

@@ -19,3 +19,5 @@ jobs:
         run: python -m py_compile audit-local-files/scripts/*.py
       - name: Run smoke test
         run: python tests/smoke_test.py
+      - name: Run contract test
+        run: python tests/contract_test.py

README.md

@@ -94,6 +94,27 @@ python3 audit-local-files/scripts/compare_reports.py \
 
 The comparison highlights disk usage, target areas, Codex workspace counts, Git dirty changes, and rebuildable artifacts that changed. Keep snapshots local unless you review their paths first.
 
+## Evidence, Not Guesswork
+
+The JSON report now carries a small decision contract:
+
+- `measurement_status` distinguishes measured, timeout, error, missing, and unknown;
+- `coverage` records which target families were actually measured;
+- `findings` links each recommendation to evidence, owner, risk, confidence, and rollback/rebuild guidance;
+- `action_gate` keeps the result in `review_only` when evidence is incomplete or dirty Git work must be preserved.
+
+Validate a saved snapshot before handing it to another Agent:
+
+```bash
+python3 audit-local-files/scripts/validate_report.py snapshots/before.json
+```
+
+Artifact rows are candidate subsets. They may already be included in a parent workspace total, so the report does not present them as additive reclaimable space.
+
+## How We Iterate The Skill
+
+The project uses a maintainer-only evaluation loop: run a real local audit, aggregate and redact the evidence, ask independent roles to review it, synthesize the smallest change, then run contract and fixture tests before publishing. Raw local reports never enter the repository. See [the evaluation loop](audit-local-files/references/agentic-evaluation.md).
+
 ## What A Useful Result Looks Like
 
 The report is designed to turn raw measurements into a next step:
@@ -204,10 +225,16 @@ python3 audit-local-files/scripts/audit_local_files.py \
 
 保存 JSON 快照后，可以用 `audit-local-files/scripts/compare_reports.py` 比较两次审计，观察哪些区域在增长。
 
+交给其他 Agent 之前，可以先运行 `python3 audit-local-files/scripts/validate_report.py snapshots/before.json` 校验报告契约。
+
+JSON 报告还会区分 `measured`、`timeout`、`error`、`missing` 和 `unknown`，记录 coverage、证据关联的 findings，以及是否因为证据不足或 Git dirty 状态而只能停留在 `review_only`。artifact 可能已经包含在父工作区大小中，不会被当成可回收空间重复相加。
+
 ### 隐私与安全
 
 扫描器只读取路径、占用大小、修改时间和可选的 Git 状态计数；不会读取聊天、浏览器历史、邮件正文、文档正文、源码、凭据或 keychain。默认把 home 目录显示为 `~`，默认不输出 Git origin URL。任何公开分享前，都应检查项目名和文件夹名。
 
+项目维护时会使用真实本机审计的聚合匿名证据包，让不同 Agent 角色独立评审，再通过确定性 fixture 和 schema 测试后发布；原始本机报告不会进入仓库。
+
 ### 依赖
 
 Python 3.9+；macOS/Linux 上的 `du`；只有在进行 Git 检查时才需要 `git`。不需要第三方 Python 包。

audit-local-files/SKILL.md

@@ -41,7 +41,13 @@ python3 scripts/audit_local_files.py \
   --format markdown
 ```
 
-Use `--output` to save a report. Use JSON when saving a snapshot for comparison. Read `references/target-taxonomy.md` when adding or interpreting app patterns. Read `references/action-playbook.md` when turning findings into an action plan.
+Use `--output` to save a report. Use JSON when saving a snapshot for comparison. Read `references/target-taxonomy.md` when adding or interpreting app patterns. Read `references/report-schema.md` when consuming JSON or building an evidence-linked decision. Read `references/action-playbook.md` when turning findings into an action plan.
+
+Before comparing or sharing a JSON snapshot with another Agent, run:
+
+```bash
+python3 scripts/validate_report.py report.json
+```
 
 ### 3. Interpret the evidence
 
@@ -56,6 +62,8 @@ Organize the explanation in this order:
 
 Do not equate “large” with “safe to delete.” A large app container may contain user data; a small untracked file may be important.
 
+Treat `measurement_status: timeout|error|unknown` as unknown, never as zero. Treat artifact rows as candidate subsets that may already be included in a parent workspace total. Use `coverage`, `findings`, and `action_gate` to preserve what was measured, why a conclusion was made, and whether exact cleanup review is blocked.
+
 ### 4. Produce a decision-ready report
 
 Lead with a short organization conclusion. Then include:
@@ -86,6 +94,8 @@ If the user requests cleanup, present an approval table before changing anything
 
 Prefer reversible moves to Trash for user-visible folders when the user approves them. Never bulk-delete app containers, cloud-sync roots, dirty repositories, or unknown paths.
 
+If the report's `action_gate.status` is `review_only`, do not produce an executable cleanup plan. Resolve the listed evidence blockers first. The scanner itself never performs cleanup, even when the gate is `approval_required`.
+
 ## Snapshot Comparison
 
 The JSON report is intentionally suitable for local snapshots:
@@ -100,6 +110,10 @@ python3 scripts/compare_reports.py before.json after.json
 
 The comparison script reports changes in disk usage, target areas, Codex counts, Git buckets, and artifacts. It preserves whatever redaction was present in the input reports and never reads file contents.
 
+## Maintainer Evaluation Loop
+
+For a repeatable skill iteration using local evidence and independent roles, read `references/agentic-evaluation.md`. Keep raw reports in a temporary local directory, pass only an aggregated redacted packet to reviewers, record timed-out roles as incomplete, then require contract and fixture tests before publishing.
+
 ## Failure Handling
 
 - If a size probe times out, report it as unknown or timed out. Do not silently treat it as zero.

audit-local-files/references/agentic-evaluation.md

@@ -0,0 +1,37 @@
+# Agentic Evaluation Loop
+
+Use this loop when improving the skill. It is a maintainer workflow, not a user cleanup workflow.
+
+```text
+real local audit
+  -> aggregate and redact evidence packet
+  -> independent role reviews
+  -> main-agent synthesis
+  -> bounded code/doc change
+  -> deterministic fixture and contract tests
+  -> public release
+```
+
+## Evidence Packet
+
+Create a temporary packet containing only aggregate counts, sizes, statuses, and scanner limitations. Remove project names, repository names, exact paths, Git origins, prompts, and file contents. Keep the raw report local and never commit it.
+
+## Recommended Roles
+
+- **Audit operator**: check coverage, timeouts, duplicate counting, and whether conclusions are supported.
+- **Privacy guardian**: check redaction, content boundaries, origin URLs, command scope, and report sharing risk.
+- **First-time user**: check whether the Agent can start quickly and produce a decision instead of a raw size list.
+- **Loop architect**: check whether findings have evidence references, confidence, coverage state, and regression tests.
+
+Require each role to return findings, evidence, severity, and the smallest concrete improvement. A role that times out is recorded as incomplete, not as approval.
+
+## Acceptance Gates
+
+Before publishing an iteration:
+
+1. No cleanup or migration was executed during evaluation.
+2. Non-measured sizes are represented as `null` with an explicit status.
+3. Coverage and findings are linked to evidence.
+4. Parent and artifact sizes are not summed as independent reclaimable space.
+5. Privacy defaults and synthetic fixtures pass regression tests.
+6. The README explains the user-facing outcome and the Agent handoff.

audit-local-files/references/report-schema.md

@@ -0,0 +1,51 @@
+# Report Contract
+
+The JSON report is a local evidence artifact, not a cleanup authorization. `schema_version` is incremented when the contract changes.
+
+## Core Fields
+
+| Field | Meaning |
+| --- | --- |
+| `settings.scope_id` | Logical scan scope. The default home scan uses `home`. Do not combine reports with different scopes without saying so. |
+| `settings.size_kind` | `allocated_bytes`; these are filesystem allocation estimates, not apparent file size. |
+| `target_areas[]` | Discovered known roots. `allocated_bytes` may be `null`. |
+| `target_areas[].measurement_status` | `measured`, `timeout`, `error`, `missing`, or `unknown`. Never treat a non-measured row as zero. |
+| `coverage[]` | Coverage ledger for configured target families, including matches, unknown rows, measured bytes, and status. |
+| `findings[]` | Evidence-linked decision records with owner, risk, confidence, recommendation, and rollback/rebuild guidance. |
+| `action_gate` | Whether the report is `review_only` or only `approval_required`. The scanner never authorizes or executes cleanup. |
+
+## Finding Contract
+
+Every finding should preserve these fields:
+
+```json
+{
+  "finding_id": "target-opaque-id",
+  "scope_id": "home",
+  "path_redacted": "~/example",
+  "category": "workspace",
+  "owner": "project or agent workflow",
+  "size_bytes": 123,
+  "status": "measured",
+  "evidence_refs": ["target_areas[0]"],
+  "confidence": "strong_inference",
+  "risk": "user-data",
+  "recommendation": "Review and promote durable outputs before archiving.",
+  "approval_required": true,
+  "rollback_or_rebuild": "Restore from the archive or original project location."
+}
+```
+
+Confidence is deliberately qualitative:
+
+- `confirmed`: direct local metadata supports the claim, such as a Git status count;
+- `strong_inference`: a known path pattern and metadata support the classification;
+- `low`: timeout, error, or incomplete evidence prevents a reliable conclusion.
+
+## Overlap Rules
+
+Target areas are containers. Artifacts are candidate subsets and may already be included in a parent target's size. Use `parent_target_id`, `counted_in_total`, and `nested_artifact` to avoid adding parent and child bytes together as reclaimable space.
+
+## Action Gate
+
+`review_only` is required when any target or artifact is not measured, Git status is missing, or dirty Git changes exist. Even without blockers, `approval_required` remains true. App-state and cloud-sync findings remain owner-managed.