@mokuyoaxis/agent-guard 0.2.4 → 0.2.5-rc1

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/SECURITY.md ADDED
@@ -0,0 +1,53 @@
1
+ # Security policy
2
+
3
+ ## Reporting
4
+
5
+ Open a GitHub issue for non-sensitive issues, or contact the maintainer
6
+ directly for anything you believe is exploitable. Please include the
7
+ verdict JSON and audit lines involved.
8
+
9
+ ## What agent-guard claims to be
10
+
11
+ Reliability infrastructure: it makes destructive actions reversible by
12
+ default and records evidence. It is **not a security sandbox** - an agent
13
+ with the same OS privileges as the guard can bypass it. See
14
+ [docs/design/threat-model.md](docs/design/threat-model.md) before relying on it.
15
+
16
+ ## Expected scanner hits on this repository
17
+
18
+ This repository documents, tests, and demonstrates destructive commands -
19
+ that is its subject matter. Static scanners (including `dsh-plugin-gate`)
20
+ will therefore report hits such as:
21
+
22
+ - `rm_recursive` / command patterns inside `README*`, `docs/`, and
23
+ especially `tests/` fixtures, which must contain real command strings to
24
+ exercise the classifier;
25
+ - `dynamic_require` in `core/policy.py` (the `subprocess` call backing
26
+ `git check-ignore`);
27
+ - credential-adjacent wording in `docs/guides/publishing-from-ephemeral-environments.md`
28
+ (a guide about *avoiding* credential leaks).
29
+
30
+ As of v0.1.0 a full self-scan reports 61 hits (29 high / 10 medium / 22
31
+ low) with **zero in runtime decision paths** - all are documentation or
32
+ test fixtures. If you find a hit outside docs/tests/fixtures, please
33
+ report it.
34
+
35
+ ## Data handling
36
+
37
+ The command guards store recovery and audit data locally. The default bucket
38
+ is the workspace's `.agent-trash/`; `AGENT_GUARD_TRASH` can select a custom or
39
+ external bucket. Recovery may also write Git metadata, including local exclude
40
+ rules and retained stashes. Linked worktrees can share Git metadata outside
41
+ the selected worktree. Diagnostics and Lab commands use their declared output
42
+ locations. A dry-run assessment can still write metadata.
43
+
44
+ There is no automatic telemetry. Built-in Lab controls call no model and use
45
+ only bounded loopback observation. Explicit live-host/model tests can contact
46
+ the configured provider through the host and consume quota; they are separate
47
+ from local command checks and require a selected experiment scope.
48
+
49
+ Recovery manifests, CLI diagnostics and historical audit records can contain
50
+ exact paths or other private text. Audit minimization in the 0.2.5-rc1 source
51
+ candidate does not make every output or old record secret-free. The exfil text
52
+ CLIs return decisions/plans or sanitized stdout; they do not automatically
53
+ persist egress audit events. Review and redact evidence before sharing it.
@@ -42,8 +42,10 @@ call. It must never silently become allow. Treat malformed payloads and
42
42
  adapter failures conservatively **when the adapter is invoked**; this does
43
43
  not protect a call when the host never starts the hook. For a shell tool,
44
44
  `check.py --enforce` may relocate files or snapshot Git state, so use it only
45
- in an authorized execution path; use advisory mode for non-mutating policy
46
- checks.
45
+ in an authorized execution path. Advisory mode assesses without changing
46
+ command targets, but may initialize quarantine/audit metadata and a Git local
47
+ exclude rule. Its exit 0 does not authorize a BLOCK or ASK decision. See the
48
+ [assessment contract](../skills/delete-guard/references/policy.md#assessment-and-dry-run-side-effects).
47
49
 
48
50
  ## 3. Configure and verify without destructive trials
49
51
 
@@ -129,6 +129,13 @@ is forwarded verbatim rather than swapped for POSIX, so `check.py` returns
129
129
 
130
130
  ## Notes
131
131
 
132
+ The [0.2.4 official Flash/PTC report](../../docs/reports/test-report-dsh-0.2.4-ptc.md)
133
+ also observed sampled root/child SDK Bash collision refusals. Its original root
134
+ PTC task failed; a separate summary completed. This does not establish general
135
+ PTC Node API mediation or injection L2. The 0.2.5-rc1 documentation update adds
136
+ no new native-host/model result; use the
137
+ [capability matrix](../../docs/guides/harness-capabilities.md) for the full scope.
138
+
132
139
  - Deletion commands inherit the caller's sandbox policy per invocation
133
140
  (`exec.agent.session`) through the native shell executor.
134
141
  - Once the adapter has registered its pre-execute listener, Core process and
@@ -0,0 +1,19 @@
1
+ <svg xmlns="http://www.w3.org/2000/svg" width="1000" height="160" viewBox="0 0 1000 160" role="img" aria-labelledby="title desc">
2
+ <title id="title">LINUX DO community link</title>
3
+ <desc id="desc">A project-made banner linking to the LINUX DO community, not an official endorsement.</desc>
4
+ <defs>
5
+ <linearGradient id="background" x2="1" y2="1">
6
+ <stop offset="0" stop-color="#111827"/>
7
+ <stop offset="1" stop-color="#263b55"/>
8
+ </linearGradient>
9
+ </defs>
10
+ <rect width="1000" height="160" rx="18" fill="url(#background)"/>
11
+ <rect x="0" y="0" width="12" height="160" rx="6" fill="#f59e0b"/>
12
+ <rect x="40" y="33" width="11" height="11" fill="#f59e0b"/>
13
+ <rect x="55" y="33" width="11" height="11" fill="#f59e0b"/>
14
+ <rect x="40" y="48" width="11" height="11" fill="#f59e0b"/>
15
+ <rect x="55" y="48" width="11" height="11" fill="#f59e0b"/>
16
+ <text x="86" y="79" fill="#ffffff" font-family="Arial, Helvetica, sans-serif" font-size="49" font-weight="700" letter-spacing="2">LINUX DO</text>
17
+ <text x="87" y="115" fill="#cbd5e1" font-family="Arial, Helvetica, sans-serif" font-size="22">COMMUNITY LINK · 社区友链</text>
18
+ <path d="M790 80h145m-27-27 27 27-27 27" fill="none" stroke="#f59e0b" stroke-width="5" stroke-linecap="round" stroke-linejoin="round"/>
19
+ </svg>
@@ -33,7 +33,7 @@ import shlex
33
33
  from dataclasses import dataclass, field
34
34
  from typing import List, Optional, Tuple
35
35
 
36
- from . import dialects
36
+ from . import AUDIT_NAME, MANIFEST_NAME, STATE_NAME, dialects
37
37
 
38
38
  # ---------------------------------------------------------------- vocabulary
39
39
 
@@ -192,6 +192,7 @@ class PathSpec:
192
192
  inside_trash: bool = False
193
193
  protected: Optional[str] = None # None | ancestor-root | workspace-root
194
194
  # | outside-workspace | git-metadata
195
+ # | quarantine-control
195
196
  error: Optional[str] = None
196
197
 
197
198
  # ------------------------------------------------------------- path analysis
@@ -250,6 +251,26 @@ def _physical_keep_final(path: str) -> str:
250
251
  return os.path.join(os.path.realpath(parent), name)
251
252
 
252
253
 
254
+ def _quarantine_control_path(absolute: str, physical: str,
255
+ trash_root: str, trash_physical: str,
256
+ workspace: str) -> bool:
257
+ """Protect storage access and root metadata, retaining leaf-link location."""
258
+ # A configured final link is also the access path to an external bucket.
259
+ # Deleting its parent would sever that access even if storage is elsewhere.
260
+ if (inside_path(physical, workspace) and
261
+ any(inside_path(storage, physical) for storage in
262
+ (trash_physical, _physical_keep_final(trash_root)))):
263
+ return True
264
+ controls = {MANIFEST_NAME, AUDIT_NAME, STATE_NAME, STATE_NAME + ".tmp",
265
+ "sessions"}
266
+ for candidate in (physical, _physical_keep_final(absolute)):
267
+ if inside_path(candidate, trash_physical):
268
+ relative = os.path.relpath(candidate, trash_physical)
269
+ if relative.split(os.sep)[0] in controls:
270
+ return True
271
+ return False
272
+
273
+
253
274
  def workspace_boundary_root(workspace: str) -> str:
254
275
  """Physical form of a workspace root, for callers that compare roots."""
255
276
  return _physical(os.path.normpath(os.path.abspath(workspace)))
@@ -365,6 +386,9 @@ def classify_paths(
365
386
  # content. `rm -rf .` stays a hard BLOCK. (When no trash_root is
366
387
  # given, trash_physical is None and cannot match a real path.)
367
388
  spec.protected = "workspace-root"
389
+ elif trash_root and _quarantine_control_path(
390
+ absolute, physical, trash_root, trash_physical, workspace):
391
+ spec.protected = "quarantine-control"
368
392
  elif not spec.inside_workspace:
369
393
  spec.protected = "outside-workspace"
370
394
  else:
package/core/policy.py CHANGED
@@ -166,8 +166,10 @@ EXPLANATIONS: Dict[str, str] = {
166
166
  "/usr, /etc, ...), regardless of the "
167
167
  "workspace setting. Hard boundary - not "
168
168
  "askable.",
169
- CODE_BLOCK_PROTECTED_PATH: "Target is the workspace root or git "
170
- "metadata. Hard boundary - not askable.",
169
+ CODE_BLOCK_PROTECTED_PATH: "Target is a protected workspace, Git or "
170
+ "quarantine control path. Hard boundary - "
171
+ "not askable; quarantine transaction cleanup "
172
+ "uses the explicit GC entry point.",
171
173
  CODE_BLOCK_WILDCARD: "Glob target sets are opaque; use safe_delete, "
172
174
  "which expands globs explicitly.",
173
175
  CODE_BLOCK_RESTRICTED_MODE: "This session is in RESTRICTED mode; the "
@@ -497,7 +499,20 @@ def decide_path_batch(specs: List[PathSpec], ctx: PolicyContext,
497
499
  [f"protected filesystem root: {s.raw}"
498
500
  for s in protected_ancestor[:5]])
499
501
 
502
+ # Housekeeping never overrides root, control-file or Git protection.
503
+ protected_other = [s for s in specs
504
+ if s.protected in ("workspace-root", "git-metadata",
505
+ "quarantine-control")]
506
+ if protected_other:
507
+ return Verdict(DECISION_BLOCK, CODE_BLOCK_PROTECTED_PATH,
508
+ [f"protected: {s.protected} ({s.raw})"
509
+ for s in protected_other[:5]])
510
+
500
511
  if specs and all(s.inside_trash for s in specs):
512
+ if any(s.wildcard for s in specs):
513
+ return Verdict(DECISION_BLOCK, CODE_BLOCK_WILDCARD,
514
+ ["quarantine globs may include protected evidence; "
515
+ "enumerate explicitly with safe_delete"])
501
516
  return Verdict(DECISION_ALLOW, CODE_ALLOW_TRASH_GC)
502
517
 
503
518
  protected_outside = [s for s in specs
@@ -507,13 +522,6 @@ def decide_path_batch(specs: List[PathSpec], ctx: PolicyContext,
507
522
  [f"outside workspace boundary: {s.raw}"
508
523
  for s in protected_outside[:5]])
509
524
 
510
- protected_other = [s for s in specs
511
- if s.protected in ("workspace-root", "git-metadata")]
512
- if protected_other:
513
- return Verdict(DECISION_BLOCK, CODE_BLOCK_PROTECTED_PATH,
514
- [f"protected: {s.protected} ({s.raw})"
515
- for s in protected_other[:5]])
516
-
517
525
  wild = [s for s in specs if s.wildcard]
518
526
  if wild:
519
527
  return Verdict(DECISION_BLOCK, CODE_BLOCK_WILDCARD,
package/core/recovery.py CHANGED
@@ -831,9 +831,13 @@ class RecoveryEngine:
831
831
  return None
832
832
 
833
833
  def tx_inventory(self) -> List[Dict[str, Any]]:
834
- """Per-transaction age/size facts for retention decisions."""
834
+ """Active transaction age/size facts; purged history stays in the manifest."""
835
835
  inventory: List[Dict[str, Any]] = []
836
836
  for txid, tx in self.transactions().items():
837
+ # A tombstone ends our ownership for planning. A directory later
838
+ # recreated under this ID is unmanaged, not another purge target.
839
+ if tx.get("purged"):
840
+ continue
837
841
  tx_dir = os.path.join(self.trash_root, txid)
838
842
  total = 0
839
843
  for root, _dirs, names in os.walk(tx_dir):
package/core/redaction.py CHANGED
@@ -896,6 +896,7 @@ class ScanResult:
896
896
  truncated: bool = False
897
897
  size_bytes: int = 0
898
898
  exempted: int = 0
899
+ exemption_info: Dict[str, Any] = field(default_factory=dict)
899
900
 
900
901
  @property
901
902
  def found(self) -> bool:
@@ -1006,6 +1007,29 @@ def _secret_source_reference(text: str) -> Optional[Tuple[str, int, int, str]]:
1006
1007
 
1007
1008
  DEFAULT_ALLOWFILE = ".agent-guard/exfil-allow.toml"
1008
1009
  DEFAULT_IGNOREFILE = ".agent-guardignore"
1010
+ EXEMPTION_DIAGNOSTIC_LIMIT = 32
1011
+ EXEMPTION_DIAGNOSTICS = {
1012
+ "EXEMPTION_IGNORED_LINE": "Line has no assignment or preceding value key; gitignore syntax is unsupported.",
1013
+ "EXEMPTION_UNKNOWN_KEY": "Unknown top-level key; its values are ignored.",
1014
+ "EXEMPTION_UNKNOWN_SECTION": "Unknown section; recognized legacy keys may still apply.",
1015
+ "EXEMPTION_LEGACY_SECTION_KEY": "Nonstandard key uses the legacy section fallback; its values still apply.",
1016
+ "EXEMPTION_MALFORMED_SECTION": "Malformed section header uses legacy parsing; inspect the configuration.",
1017
+ "EXEMPTION_INVALID_HASH": "Value is not a lowercase sha256 digest of 64 hexadecimal characters; it cannot match.",
1018
+ "EXEMPTION_UNSUPPORTED_NEGATION": "Leading ! is a literal pattern character, not gitignore negation.",
1019
+ "EXEMPTION_READ_FAILED": "Configuration could not be read; the next candidate is tried.",
1020
+ "EXEMPTION_ENCODING_INVALID": "Configuration is not UTF-8; the next candidate is tried.",
1021
+ "EXEMPTION_SHADOWED": "This file is not loaded because the preferred file was readable, even if empty or malformed.",
1022
+ }
1023
+ _EXEMPTION_RULE_KEYS = frozenset({"rule", "rules", "disable"})
1024
+ _EXEMPTION_PATH_KEYS = frozenset({"path", "paths", "ignore"})
1025
+ _EXEMPTION_HASH_KEYS = frozenset({"sha256", "hash", "hashes"})
1026
+
1027
+
1028
+ def _safe_exemption_source(source: str) -> Optional[str]:
1029
+ """Only fixed workspace-relative filenames may leave the process."""
1030
+ if source in (DEFAULT_ALLOWFILE, DEFAULT_IGNOREFILE):
1031
+ return source
1032
+ return "<provided>" if source else None
1009
1033
 
1010
1034
 
1011
1035
  @dataclass
@@ -1016,6 +1040,41 @@ class Exemption:
1016
1040
  paths: List[str] = field(default_factory=list)
1017
1041
  hashes: List[str] = field(default_factory=list)
1018
1042
  source: str = ""
1043
+ diagnostics: List[Dict[str, Any]] = field(default_factory=list)
1044
+ diagnostics_omitted: int = 0
1045
+
1046
+ def diagnose(self, code: str, source: str, line: int = 0) -> None:
1047
+ """Bounded, static diagnostics; never copy keys, values or exceptions."""
1048
+ if code not in EXEMPTION_DIAGNOSTICS:
1049
+ return
1050
+ if len(self.diagnostics) >= EXEMPTION_DIAGNOSTIC_LIMIT:
1051
+ self.diagnostics_omitted += 1
1052
+ return
1053
+ row = {"code": code, "source": _safe_exemption_source(source)}
1054
+ if type(line) is int and line > 0:
1055
+ row["line"] = line
1056
+ self.diagnostics.append(row)
1057
+
1058
+ def safe(self) -> Dict[str, Any]:
1059
+ """Provenance and counts, never the exemption patterns or hashes."""
1060
+ rows = []
1061
+ for row in self.diagnostics[:EXEMPTION_DIAGNOSTIC_LIMIT]:
1062
+ code = row.get("code")
1063
+ if code not in EXEMPTION_DIAGNOSTICS:
1064
+ continue
1065
+ safe = {"code": code,
1066
+ "source": _safe_exemption_source(row.get("source", ""))}
1067
+ if type(row.get("line")) is int and row["line"] > 0:
1068
+ safe["line"] = row["line"]
1069
+ rows.append(safe)
1070
+ return {
1071
+ "source": _safe_exemption_source(self.source),
1072
+ "active": self.active,
1073
+ "counts": {"rules": len(self.rules), "paths": len(self.paths),
1074
+ "hashes": len(self.hashes)},
1075
+ "diagnostics": rows,
1076
+ "diagnostics_omitted": self.diagnostics_omitted,
1077
+ }
1019
1078
 
1020
1079
  @property
1021
1080
  def active(self) -> bool:
@@ -1059,35 +1118,51 @@ def _parse_allowfile(text: str, source: str) -> Exemption:
1059
1118
 
1060
1119
  Continuation lines are supported: a key whose value starts on its own
1061
1120
  line keeps consuming the indented lines that follow, which is how the
1062
- lists in `.agent-guard/exfil-allow.toml` stay readable. Malformed input
1063
- is ignored rather than fatal - a broken allowfile must never quietly
1064
- turn the guard off.
1121
+ lists in `.agent-guard/exfil-allow.toml` stay readable. Preserve legacy
1122
+ matching while diagnosing ignored or nonstandard constructs. Warnings
1123
+ are not whole-file rejection; recognized entries can still apply.
1065
1124
  """
1066
1125
  exemption = Exemption(source=source)
1067
1126
  section = ""
1068
1127
  key = ""
1069
- values: List[str] = []
1128
+ values: List[Tuple[str, int]] = []
1129
+ key_line = 0
1070
1130
 
1071
1131
  def flush():
1072
1132
  if not key:
1073
1133
  return
1074
- items = [v.strip().strip("'\"") for v in values if v.strip("'\"")]
1075
- if key in ("rule", "rules", "disable") or section == "rules":
1076
- exemption.rules.extend(items)
1077
- elif key in ("path", "paths", "ignore") or section == "paths":
1078
- exemption.paths.extend(items)
1079
- elif key in ("sha256", "hash", "hashes") or section == "values":
1080
- exemption.hashes.extend(items)
1081
-
1082
- def push(raw: str):
1134
+ if key in _EXEMPTION_RULE_KEYS or section == "rules":
1135
+ target = exemption.rules
1136
+ elif key in _EXEMPTION_PATH_KEYS or section == "paths":
1137
+ target = exemption.paths
1138
+ elif key in _EXEMPTION_HASH_KEYS or section == "values":
1139
+ target = exemption.hashes
1140
+ else:
1141
+ exemption.diagnose("EXEMPTION_UNKNOWN_KEY", source, key_line)
1142
+ return
1143
+ if key not in (_EXEMPTION_RULE_KEYS | _EXEMPTION_PATH_KEYS |
1144
+ _EXEMPTION_HASH_KEYS):
1145
+ exemption.diagnose("EXEMPTION_LEGACY_SECTION_KEY", source, key_line)
1146
+ for value, line in values:
1147
+ if not value.strip("'\""):
1148
+ continue
1149
+ item = value.strip().strip("'\"")
1150
+ target.append(item)
1151
+ if target is exemption.hashes:
1152
+ if not re.fullmatch(r"sha256:[0-9a-f]{64}", item):
1153
+ exemption.diagnose("EXEMPTION_INVALID_HASH", source, line)
1154
+ elif item.startswith("!"):
1155
+ exemption.diagnose("EXEMPTION_UNSUPPORTED_NEGATION", source, line)
1156
+
1157
+ def push(raw: str, line: int):
1083
1158
  """Split one value chunk on commas/whitespace, ignoring [] and ''."""
1084
1159
  chunk = raw.strip().strip("[]")
1085
1160
  for item in re.split(r"[,\s]+", chunk):
1086
1161
  item = item.strip().strip("'\"")
1087
1162
  if item:
1088
- values.append(item)
1163
+ values.append((item, line))
1089
1164
 
1090
- for raw_line in text.splitlines():
1165
+ for line_number, raw_line in enumerate(text.splitlines(), 1):
1091
1166
  line = raw_line.split("#", 1)[0].rstrip()
1092
1167
  if not line.strip():
1093
1168
  continue
@@ -1095,32 +1170,57 @@ def _parse_allowfile(text: str, source: str) -> Exemption:
1095
1170
  flush()
1096
1171
  key, values = "", []
1097
1172
  section = line.strip().strip("[]").strip().lower()
1173
+ if not re.fullmatch(r"\[[^\[\]]+\]", line.strip()):
1174
+ exemption.diagnose("EXEMPTION_MALFORMED_SECTION", source, line_number)
1175
+ if section not in ("rules", "paths", "values"):
1176
+ exemption.diagnose("EXEMPTION_UNKNOWN_SECTION", source, line_number)
1098
1177
  continue
1099
1178
  if "=" in line:
1100
1179
  flush()
1101
1180
  values = []
1102
1181
  key, _, value = line.partition("=")
1103
1182
  key = key.strip().lower()
1104
- push(value)
1183
+ key_line = line_number
1184
+ if not key:
1185
+ exemption.diagnose("EXEMPTION_UNKNOWN_KEY", source, line_number)
1186
+ push(value, line_number)
1105
1187
  continue
1106
1188
  if key:
1107
- push(line)
1189
+ push(line, line_number)
1190
+ else:
1191
+ exemption.diagnose("EXEMPTION_IGNORED_LINE", source, line_number)
1108
1192
  flush()
1109
1193
  return exemption
1110
1194
 
1111
1195
 
1112
1196
  def load_exemption(workspace: Optional[str]) -> Exemption:
1113
1197
  """Read the repo-local exemption file; absent means "no exemptions"."""
1198
+ result = Exemption()
1114
1199
  if not workspace:
1115
- return Exemption()
1200
+ return result
1116
1201
  for relative in (DEFAULT_ALLOWFILE, DEFAULT_IGNOREFILE):
1117
1202
  path = os.path.join(workspace, relative)
1118
1203
  try:
1119
1204
  with open(path, "r", encoding="utf-8") as fh:
1120
- return _parse_allowfile(fh.read(), relative)
1121
- except (OSError, UnicodeDecodeError):
1205
+ parsed = _parse_allowfile(fh.read(), relative)
1206
+ except FileNotFoundError:
1122
1207
  continue
1123
- return Exemption()
1208
+ except UnicodeDecodeError:
1209
+ result.diagnose("EXEMPTION_ENCODING_INVALID", relative)
1210
+ continue
1211
+ except OSError:
1212
+ result.diagnose("EXEMPTION_READ_FAILED", relative)
1213
+ continue
1214
+ result.rules, result.paths, result.hashes = parsed.rules, parsed.paths, parsed.hashes
1215
+ result.source = parsed.source
1216
+ for row in parsed.diagnostics:
1217
+ result.diagnose(row["code"], relative, row.get("line", 0))
1218
+ result.diagnostics_omitted += parsed.diagnostics_omitted
1219
+ if relative == DEFAULT_ALLOWFILE and os.path.lexists(
1220
+ os.path.join(workspace, DEFAULT_IGNOREFILE)):
1221
+ result.diagnose("EXEMPTION_SHADOWED", DEFAULT_IGNOREFILE)
1222
+ return result
1223
+ return result
1124
1224
 
1125
1225
 
1126
1226
  def apply_exemption(spans: List[SpanSpec], exemption: Exemption,
@@ -1189,6 +1289,7 @@ def scan_text(text: str, channel: str = "",
1189
1289
  notes=["value-free reference detection", reason]))
1190
1290
  if exemption is None:
1191
1291
  exemption = load_exemption(workspace)
1292
+ result.exemption_info = exemption.safe()
1192
1293
  # A source-reference fact must survive even inside a redaction span:
1193
1294
  # masking a literal URI password is not permission to resolve an env
1194
1295
  # secret embedded there. The aggregate BLOCK prevents plan application.
package/docs/README.md CHANGED
@@ -1,10 +1,17 @@
1
1
  # Documentation / 文档导航
2
2
 
3
- Start with the [harness capability matrix](guides/harness-capabilities.md) for
4
- current coverage, the [architecture](design/architecture.md) for the shared
5
- Core, and the [Lab guide](lab/guard-lab.md) for experiment semantics.
6
-
7
- 先看当前能力矩阵、架构和 Lab 指南。测试报告按所测版本与配置保留;发布记录、
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
7
+ [harness capability matrix](guides/harness-capabilities.md) for observed coverage
8
+ and the [architecture](design/architecture.md) for the shared Core.
9
+
10
+ Current source: [0.2.5-rc1 candidate](releases/release-notes-0.2.5-rc1.md).
11
+ Published stable baseline: [0.2.4](releases/release-notes-0.2.4.md).
12
+ Candidate preparation and package validation do not establish publication.
13
+
14
+ 先看入门指南,再按恢复保护、外发检测、Lab 验测选择入口。测试报告按所测版本与配置保留;发布记录、
8
15
  历史设计和外部案例各自归档,不能据此扩展当前产品的承诺。
9
16
 
10
17
  | Category / 分类 | Contents / 内容 |
@@ -20,6 +27,7 @@ Core, and the [Lab guide](lab/guard-lab.md) for experiment semantics.
20
27
 
21
28
  | Document / 文档 | Scope / 范围 |
22
29
  |---|---|
30
+ | [Getting started](guides/getting-started.md) | 安装路径、Agent 接入提示词与最短验证流程 |
23
31
  | [Harness capabilities](guides/harness-capabilities.md) | 当前接入范围、证据等级与未验证路径 |
24
32
  | [Host drift](guides/host-drift.md) | 宿主版本、配置与本地基线检查 |
25
33
  | [Trash locations](guides/trash-index.md) | 0.2.4 的只读位置查询、Agent/前端共享 JSON 契约 |
@@ -81,6 +89,7 @@ coverage rather than treating every historical result as current acceptance.
81
89
 
82
90
  | Document / 文档 | Scope / 范围 |
83
91
  |---|---|
92
+ | [0.2.5-rc1](releases/release-notes-0.2.5-rc1.md) | 当前维护候选、文档整理、版本例外与验收状态 |
84
93
  | [0.2.4](releases/release-notes-0.2.4.md) | 恢复维护、trash 查询及兼容性例外 |
85
94
  | [0.2.3](releases/release-notes-0.2.3.md) | 正式版范围与证据边界 |
86
95
  | [0.2.3-rc2](releases/release-notes-0.2.3-rc2.md) | 离线 Lab 与已复核 DSH 契约 |
@@ -263,8 +263,11 @@ FORBIDDEN (BLOCK, never askable).
263
263
  5. **Lexical boundaries.** Workspace containment is decided on normalized
264
264
  paths; deleting a symlink removes the link, never the target, so symlink
265
265
  targets outside the workspace neither leak nor block.
266
- 6. **Self-exclusion.** Targets inside `.agent-trash/` are exempted from
267
- quarantine - housekeeping cannot recurse into itself forever.
266
+ 6. **Self-exclusion with protected controls.** Ordinary unprotected payloads
267
+ inside the selected quarantine use housekeeping rather than relocation.
268
+ The 0.2.5-rc1 candidate checks root/control paths and storage parents first;
269
+ housekeeping cannot override protection. Opaque globs must be enumerated
270
+ explicitly, and validated transaction purge uses the GC CLI.
268
271
  7. **Diagnostics do not silently become enforcement.** `guard-lab` records
269
272
  declared synthetic channels and evaluates one case criterion. It does not
270
273
  feed a Lab observation into Core policy or claim to ban model calls. A real
@@ -295,7 +298,17 @@ order of value:
295
298
  skill and the "prefer safe_delete" rule. Interception without prompting
296
299
  causes friction; prompting without interception is advisory only.
297
300
 
298
- ## Roadmap
301
+ ## Delivery status and design directions
302
+
303
+ The current source candidate is 0.2.5-rc1; 0.2.4 remains the published stable
304
+ baseline. The candidate contains the documented lifecycle/audit maintenance
305
+ and exemption diagnostics, alongside a README/documentation reorganization.
306
+ See [candidate notes](../releases/release-notes-0.2.5-rc1.md) and
307
+ [compatibility](compatibility.md) for behaviour and validation boundaries.
308
+
309
+ The milestones below describe historical delivery and future design scope,
310
+ not a committed schedule or a guarantee that new compensation types need no
311
+ architecture changes.
299
312
 
300
313
  - V1 (this repo): delete-guard skill, fs + git compensations, Linux/macOS.
301
314
  - v0.1.1: durable relocation intents, explicit retention/GC policy, quoted
@@ -315,7 +328,7 @@ order of value:
315
328
  `tests/test_dialect_phase2.py`) cover further cmd/PowerShell spellings,
316
329
  option aliases and fail-closed edge cases. Hook payload dialect forwarding
317
330
  has adapter tests; this is not a Windows host execution claim.
318
- - **Phase 3a (`0.2.3-rc1` candidate).** A blocking `windows-latest` Core
331
+ - **Phase 3a (shipped since `0.2.3-rc1`).** A blocking `windows-latest` Core
319
332
  job covers the Issue #7 dialect-mismatch and separator regressions,
320
333
  deterministic cmd/PowerShell facts, and recovery inside disposable
321
334
  fixtures. The job uses Python argv/bytes so a surrounding shell cannot
@@ -325,7 +338,7 @@ order of value:
325
338
  broader UNC/device paths and full-suite portability still require
326
339
  separate evidence. A focused Core runner is not a universal Windows E2E
327
340
  claim.
328
- - `0.2.3-rc2` source candidate: offline `guard-lab` MVP with disposable
341
+ - Offline `guard-lab` MVP, introduced in `0.2.3-rc2` and shipped in `0.2.3`: disposable
329
342
  synthetic fixtures, zero-token controls, a bounded loopback observer,
330
343
  explicit-output marker scanning, chained evidence, and fail-inconclusive
331
344
  reports. General file-read visibility, remote callbacks, real-model rating,
@@ -335,4 +348,5 @@ order of value:
335
348
  - V3+: `database-guard` (compensations = transaction / backup /
336
349
  point-in-time recovery), `cloud-guard` (snapshot / state capture). The
337
350
  Guard answers "may this happen"; the Compensation Engine answers "how do
338
- we come back" - both extend without restructuring the repository.
351
+ we come back". These remain design directions requiring separate scope and
352
+ implementation decisions.
@@ -74,6 +74,44 @@ must accept the additional refusal reason and ignore unknown optional fields.
74
74
  | `doctor.py --live-sentinel` and hashed hook receipt | minor | Explicit, opt-in real-host/model probe only. Default doctor behavior is unchanged; raw command/model output is not retained, and incomplete evidence is `INCONCLUSIVE` rather than PASS |
75
75
  | Cross-vocabulary mismatch floor (`0.2.3-rc1`) | minor safety fix | At a selected-dialect command boundary, a supported destructive shape that produced no operation becomes target-free `UNKNOWN` → `BLOCK_UNDETERMINABLE_EFFECT`; it never borrows a compensation plan from another grammar |
76
76
 
77
+ ### 0.2.5-rc1 assessment contract clarification (source candidate)
78
+
79
+ Advisory and dry-run retain their existing best-effort audit behavior and
80
+ metadata side effects. Tests and documentation distinguish unchanged command
81
+ targets from zero filesystem writes, and advisory exit 0 from execution
82
+ authorization. No flag, result field, policy decision, audit storage location
83
+ or exit code changes. See the [assessment contract](../../skills/delete-guard/references/policy.md#assessment-and-dry-run-side-effects).
84
+
85
+ ### 0.2.5-rc1 safe_delete audit minimization (source candidate)
86
+
87
+ New safe_delete audit events replace raw target/reason payloads with
88
+ `target_count`; established relocation reports retain `txid` and add
89
+ `moved_count`/`skipped_count`, including storage-failure decisions. Decision
90
+ codes, phases and static outcome labels remain available. Free-form
91
+ `--reason` stays accepted but is omitted from new audit events and
92
+ `tx-start.meta`. Essential recovery paths/intents, CLI result fields,
93
+ verdicts, exit codes and durability gates retain their behavior.
94
+ Audit event shapes are not frozen. Historical records are not rewritten,
95
+ and generic audit writers, automatic session identity and other output
96
+ surfaces are unchanged. See the [writer contract](../../skills/delete-guard/references/policy.md#safe_delete-audit-metadata).
97
+
98
+ ### 0.2.5-rc1 exemption configuration diagnostics (source candidate)
99
+
100
+ The existing limited parser, first-readable-file precedence and exemption
101
+ matching are retained. No full TOML/gitignore parser, configuration migration,
102
+ production dependency or new policy reason is added. Unknown top-level keys
103
+ and bare lines remain ineffective; recognized legacy entries may still apply
104
+ alongside warnings. Diagnostics do not change verdicts or exit codes.
105
+
106
+ Successful text scans may add `exemption` provenance/count/diagnostic metadata
107
+ to checker JSON and the sanitizer library result. Human checker and sanitizer
108
+ CLI warnings use stderr; JSON checker stdout and sanitizer payload/plan stdout
109
+ keep their respective formats. Normal missing/valid configurations remain
110
+ quiet. Diagnostic codes are configuration metadata, not Decision Protocol
111
+ reason codes. Consumers should tolerate the additive fields and warnings;
112
+ the manifest is 0.2.5-rc1, selected as a prerelease candidate. The diagnostic
113
+ grammar and privacy contract are in [rules.md](../../skills/exfil-guard/references/rules.md#configuration-diagnostics).
114
+
77
115
  ### 0.2.0 check output minimization
78
116
 
79
117
  `check.py` still returns the same decision class, reason code, static
@@ -161,9 +199,40 @@ Every expansion is recorded in the op notes for audit.
161
199
 
162
200
  ## Verdict changes since v0.1.1
163
201
 
202
+ ### 0.2.5-rc1 lifecycle and restore-audit maintenance (source candidate)
203
+
204
+ Existing `BLOCK_PROTECTED_PATH` now wins before `ALLOW_TRASH_GC` for
205
+ workspace/Git and quarantine control paths. Quarantine root metadata,
206
+ session state and in-workspace storage parents are protected. Ordinary
207
+ unprotected explicit payload housekeeping and the explicit GC CLI remain
208
+ available. Opaque quarantine globs now return `BLOCK_WILDCARD`; safe_delete
209
+ can enumerate a concrete batch before policy checks.
210
+ See [F26](../history/friction.md#f26--housekeeping-overrode-quarantine-control-protection).
211
+ This changes default verdicts and would ordinarily follow the minor-release
212
+ contract. The maintainer explicitly selected 0.2.5-rc1 for this maintenance
213
+ candidate instead of 0.3.0. This is a new, bounded exception for the existing
214
+ control-path/glob, PURGED inventory, audit-writer and exemption-diagnostic
215
+ maintenance, not an extension of the prior 0.2.4 exception to arbitrary changes.
216
+ Existing decision/reason strings, CLI arguments and exit codes retain their
217
+ roles. There is no manifest migration or production dependency. Publication,
218
+ and any later stable 0.2.5 decision, remain separate from candidate preparation.
219
+ The exact -rcN tag maps to GitHub prerelease and npm rc, preserving stable latest.
220
+ See the [candidate notes](../releases/release-notes-0.2.5-rc1.md).
221
+
222
+ Active `tx_inventory` and GC plans now omit `PURGED` history, while
223
+ `transactions` and manifests retain it. Failed/unpurged transactions retain
224
+ their prior eligibility rules; no stash deletion or storage migration is added.
225
+
226
+ Restore audit records replace `restored`/`conflicts`/`errors` payload copies
227
+ with `restored_count`/`conflict_count`/`error_count`. Established IDs and backup
228
+ attempt IDs stay correlated; invalid/unknown caller IDs use `txid_sha256`.
229
+ Audit shapes beyond manifests are not frozen. CLI parameters, exit codes,
230
+ recovery manifests and returned recovery paths/errors retain their roles.
231
+ This is one writer's minimization, not general recursive audit sanitization.
232
+
164
233
  A changed default verdict for an existing shape is a **minor** release and
165
234
  requires an entry in [friction.md](../history/friction.md) - never a silent behaviour
166
- shift. The explicit 0.2.4 exception is recorded above. Additive reason codes
235
+ shift. The bounded 0.2.4 and 0.2.5-rc1 exceptions are recorded above. Additive reason codes
167
236
  are listed above; this table is for shapes
168
237
  whose *existing* verdict moved.
169
238
 
@@ -175,6 +244,7 @@ whose *existing* verdict moved.
175
244
  | Attached or newline-separated destructive commands (`echo ok;rm ...`, `echo ok` followed by newline and `rm ...`) | Could miss the destructive segment | Classifies and applies its normal policy | POSIX command boundaries must be preserved by the lexer |
176
245
  | `git reset --hard [ref]` with untracked/ignored or quarantine collisions | Tracked-only `SNAPSHOT` could proceed | `BLOCK` / `BLOCK_GIT_RESET_COLLISION` | Stash does not preserve the colliding content (0.2.4 maintenance exception, F24) |
177
246
  | Hard reset with uncertain preflight or unsupported compound/wrapper context | Could proceed or ask despite incomplete coverage | `BLOCK_UNDETERMINABLE_EFFECT` before compensation | Snapshot and preflight must describe the actual Git context (F24) |
247
+ | Quarantine root/control paths, protected metadata inside trash, or an in-workspace storage parent | Could be allowed as housekeeping or regenerable content | `BLOCK_PROTECTED_PATH` | Recovery/state evidence protection precedes housekeeping (0.2.5-rc1 candidate, F26) |
178
248
 
179
249
  Unchanged on purpose: a genuine compensation fault (`git stash create`
180
250
  failing, a relocation that does not cover every target, an audit intent