damage-control-dev 0.1.0__tar.gz → 0.1.2__tar.gz

damage_control_dev-0.1.2/PKG-INFO

@@ -0,0 +1,95 @@
+Metadata-Version: 2.5
+Name: damage-control-dev
+Version: 0.1.2
+Summary: Damage control for AI coding agents: a PreToolUse guard that blocks or asks before destructive commands and protected-path writes (Claude Code).
+Project-URL: Homepage, https://github.com/dotdevdotdev/damage-control-dev
+Project-URL: Source, https://github.com/dotdevdotdev/damage-control-dev
+Project-URL: Issues, https://github.com/dotdevdotdev/damage-control-dev/issues
+Project-URL: Security, https://github.com/dotdevdotdev/damage-control-dev/security/policy
+Author-email: dotdev <dev@dotdev.dev>
+License: Apache-2.0
+License-File: LICENSE
+License-File: NOTICE
+Keywords: agent,ai,claude-code,guardrails,hooks,safety
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Requires-Python: >=3.9
+Requires-Dist: pyyaml>=6.0
+Description-Content-Type: text/markdown
+
+# damage-control-dev
+
+A guardrail layer for AI coding agents. It runs as a Claude Code `PreToolUse` hook and **blocks or asks before destructive commands, secret access, protected-path writes and risky MCP calls**, before the tool runs.
+
+It is a seatbelt, not a sandbox. See [What it is not](#what-it-is-not).
+
+```
+uv tool install damage-control-dev      # or: pipx install damage-control-dev
+damage-control-dev init                 # register the hooks, self-test them, record the install
+damage-control-dev status               # read-only drift report
+```
+
+Supports **Claude Code on macOS and Linux**, Python 3.9 or newer. Nothing else is supported or planned.
+
+## What it does
+
+- Guards Bash, Edit, Write, Read and MCP tool calls through one policy ladder (allow, ask, block).
+- Re-scans wrapped commands as commands in their own right: `ssh host "..."`, `sh -c`, database clients (`psql -c`, `mysql -e`), `git -c` keys that run programs.
+- Protects its own control plane: the hook scripts, the settings that register them, and its policy file cannot be edited by the agent it guards.
+- Fails closed: any crash or import failure in the hook exits 2 (block), and `init` registers the hook with `onFailure: block` (Claude Code 2.1.295 or newer) so a missing interpreter blocks the call instead of silently allowing it.
+- Unattended mode: when no human can answer a prompt, an `ask` becomes a block unless a rule carries an explicit grant.
+- Rules ship as groups that are on by default (control-plane, core, git, uv, registry, payloads, remote, mcp-tools, outbound) and opt-in vendor packs: `aws`, `gcp`, `firebase`, `cloud-hosting`, `databases`, `containers`, `infrastructure`, `publish`, `tmux`. Every rule has a frozen, stable id.
+- Offline: after `init` nothing touches the network.
+
+```
+damage-control-dev check "git push --force origin main"   # what would the hooks decide?
+damage-control-dev rules                                   # list enforced rule ids
+damage-control-dev packs                                   # list packs; enabling is human-terminal only
+damage-control-dev doctor --fix                            # self-test and repair
+damage-control-dev uninstall                               # remove exactly our entries
+```
+
+## What it is not
+
+- Not a sandbox, and not a boundary against a determined adversary. A process running as the same OS user can edit anything this tool can.
+- Only as strong as the harness's hook surface: commands you type yourself with `!`, tools that have no hook event, and a hook that times out are outside its reach.
+- No network egress filtering, containment or resource limits.
+- Expect false positives and false negatives. The policy is: ask, then learn.
+
+See [docs/threat-model.md](docs/threat-model.md).
+
+## Where things live
+
+Everything the installer keeps is under `~/.damage-control/` (or `$DAMAGE_CONTROL_HOME`), except the policy file, which is always `~/.damage-control/damagecontrol.yml`:
+
+- `damagecontrol.yml`: the protected policy (kill switch, `packs:`, `disabled_groups:`)
+- `damage-control/`, `tooldefs/`: your own rule overlays
+- `state/install.json`: what `init` recorded (interpreter, ruleset digest, per-scope write hash); `state/backups/` holds first-write backups of your settings file
+- `bin/damage-control-breakglass`: a stdlib-only script that unregisters the hooks if the Python environment is ever broken
+- `logs/damage-control/<date>.jsonl`: the audit log, one JSON line per decision
+
+A policy with no `packs:` key loads the default groups and no vendor packs; an unreadable policy loads everything.
+
+If the environment breaks (for example a `uv tool install --force` interrupted mid-upgrade) and the hook cannot start, every tool call is blocked by design. Run `python3 ~/.damage-control/bin/damage-control-breakglass unregister` from a normal terminal, then reinstall and run `init` again.
+
+## Docs
+
+Start at [docs/index.md](docs/index.md).
+
+- [docs/threat-model.md](docs/threat-model.md): what it protects against and the residuals
+- [docs/coverage.md](docs/coverage.md): which tools are covered and how
+- [docs/rule-authoring.md](docs/rule-authoring.md): writing rules, packs and overlays
+- [docs/extending.md](docs/extending.md): profiles, the hook runtime, registration and repair
+
+## Security
+
+A bypass of a shipped rule that the threat model says should be caught is a vulnerability. Report it privately, see [SECURITY.md](SECURITY.md).
+
+## License
+
+Apache-2.0. Contributions are signed off under the DCO, see [CONTRIBUTING.md](CONTRIBUTING.md).

damage_control_dev-0.1.2/README.md

@@ -0,0 +1,71 @@
+# damage-control-dev
+
+A guardrail layer for AI coding agents. It runs as a Claude Code `PreToolUse` hook and **blocks or asks before destructive commands, secret access, protected-path writes and risky MCP calls**, before the tool runs.
+
+It is a seatbelt, not a sandbox. See [What it is not](#what-it-is-not).
+
+```
+uv tool install damage-control-dev      # or: pipx install damage-control-dev
+damage-control-dev init                 # register the hooks, self-test them, record the install
+damage-control-dev status               # read-only drift report
+```
+
+Supports **Claude Code on macOS and Linux**, Python 3.9 or newer. Nothing else is supported or planned.
+
+## What it does
+
+- Guards Bash, Edit, Write, Read and MCP tool calls through one policy ladder (allow, ask, block).
+- Re-scans wrapped commands as commands in their own right: `ssh host "..."`, `sh -c`, database clients (`psql -c`, `mysql -e`), `git -c` keys that run programs.
+- Protects its own control plane: the hook scripts, the settings that register them, and its policy file cannot be edited by the agent it guards.
+- Fails closed: any crash or import failure in the hook exits 2 (block), and `init` registers the hook with `onFailure: block` (Claude Code 2.1.295 or newer) so a missing interpreter blocks the call instead of silently allowing it.
+- Unattended mode: when no human can answer a prompt, an `ask` becomes a block unless a rule carries an explicit grant.
+- Rules ship as groups that are on by default (control-plane, core, git, uv, registry, payloads, remote, mcp-tools, outbound) and opt-in vendor packs: `aws`, `gcp`, `firebase`, `cloud-hosting`, `databases`, `containers`, `infrastructure`, `publish`, `tmux`. Every rule has a frozen, stable id.
+- Offline: after `init` nothing touches the network.
+
+```
+damage-control-dev check "git push --force origin main"   # what would the hooks decide?
+damage-control-dev rules                                   # list enforced rule ids
+damage-control-dev packs                                   # list packs; enabling is human-terminal only
+damage-control-dev doctor --fix                            # self-test and repair
+damage-control-dev uninstall                               # remove exactly our entries
+```
+
+## What it is not
+
+- Not a sandbox, and not a boundary against a determined adversary. A process running as the same OS user can edit anything this tool can.
+- Only as strong as the harness's hook surface: commands you type yourself with `!`, tools that have no hook event, and a hook that times out are outside its reach.
+- No network egress filtering, containment or resource limits.
+- Expect false positives and false negatives. The policy is: ask, then learn.
+
+See [docs/threat-model.md](docs/threat-model.md).
+
+## Where things live
+
+Everything the installer keeps is under `~/.damage-control/` (or `$DAMAGE_CONTROL_HOME`), except the policy file, which is always `~/.damage-control/damagecontrol.yml`:
+
+- `damagecontrol.yml`: the protected policy (kill switch, `packs:`, `disabled_groups:`)
+- `damage-control/`, `tooldefs/`: your own rule overlays
+- `state/install.json`: what `init` recorded (interpreter, ruleset digest, per-scope write hash); `state/backups/` holds first-write backups of your settings file
+- `bin/damage-control-breakglass`: a stdlib-only script that unregisters the hooks if the Python environment is ever broken
+- `logs/damage-control/<date>.jsonl`: the audit log, one JSON line per decision
+
+A policy with no `packs:` key loads the default groups and no vendor packs; an unreadable policy loads everything.
+
+If the environment breaks (for example a `uv tool install --force` interrupted mid-upgrade) and the hook cannot start, every tool call is blocked by design. Run `python3 ~/.damage-control/bin/damage-control-breakglass unregister` from a normal terminal, then reinstall and run `init` again.
+
+## Docs
+
+Start at [docs/index.md](docs/index.md).
+
+- [docs/threat-model.md](docs/threat-model.md): what it protects against and the residuals
+- [docs/coverage.md](docs/coverage.md): which tools are covered and how
+- [docs/rule-authoring.md](docs/rule-authoring.md): writing rules, packs and overlays
+- [docs/extending.md](docs/extending.md): profiles, the hook runtime, registration and repair
+
+## Security
+
+A bypass of a shipped rule that the threat model says should be caught is a vulnerability. Report it privately, see [SECURITY.md](SECURITY.md).
+
+## License
+
+Apache-2.0. Contributions are signed off under the DCO, see [CONTRIBUTING.md](CONTRIBUTING.md).

{damage_control_dev-0.1.0 → damage_control_dev-0.1.2}/pyproject.toml

@@ -2,11 +2,15 @@
 name = "damage-control-dev"
 dynamic = ["version"]
 description = "Damage control for AI coding agents: a PreToolUse guard that blocks or asks before destructive commands and protected-path writes (Claude Code)."
+readme = "README.md"
 requires-python = ">=3.9"
 license = { text = "Apache-2.0" }
 authors = [{ name = "dotdev", email = "dev@dotdev.dev" }]
-keywords = ["ai", "agent", "claude-code", "safety", "hooks"]
+keywords = ["ai", "agent", "claude-code", "safety", "hooks", "guardrails"]
 classifiers = [
+    "Development Status :: 4 - Beta",
+    "License :: OSI Approved :: Apache Software License",
+    "Intended Audience :: Developers",
     "Operating System :: MacOS",
     "Operating System :: POSIX :: Linux",
     "Programming Language :: Python :: 3",
@@ -16,6 +20,12 @@ classifiers = [
 # bundled rules ship as JSON, so a hook with no PyYAML still enforces every bundled rule.
 dependencies = ["pyyaml>=6.0"]
 
+[project.urls]
+Homepage = "https://github.com/dotdevdotdev/damage-control-dev"
+Source = "https://github.com/dotdevdotdev/damage-control-dev"
+Issues = "https://github.com/dotdevdotdev/damage-control-dev/issues"
+Security = "https://github.com/dotdevdotdev/damage-control-dev/security/policy"
+
 [project.scripts]
 damage-control-dev = "damage_control.cli:main"
 

{damage_control_dev-0.1.0 → damage_control_dev-0.1.2}/src/damage_control/__init__.py

@@ -6,4 +6,4 @@ escape the hook's fail-closed wrapper (a Python crash exits 1, which Claude Code
 as non-blocking).
 """
 
-__version__ = "0.1.0"
+__version__ = "0.1.2"

{damage_control_dev-0.1.0 → damage_control_dev-0.1.2}/src/damage_control/cli.py

@@ -1,4 +1,4 @@
-"""``damage-control-dev``: install, inspect and operate the Claude Code hooks (#1209 M5).
+"""``damage-control-dev``: install, inspect and operate the Claude Code hooks.
 
     damage-control-dev init [--scope user|project|managed] [--dry-run] [--refresh] [--fail-open]
     damage-control-dev status [--json]      # read-only drift report

{damage_control_dev-0.1.0 → damage_control_dev-0.1.2}/src/damage_control/engine.py

@@ -24,7 +24,7 @@ import signal
 import sys
 import threading
 from pathlib import Path
-from typing import Any, Dict, Iterator, List, NamedTuple, Optional, Set, Tuple
+from typing import Any, Callable, Dict, Iterator, List, NamedTuple, Optional, Set, Tuple
 
 from damage_control import audit
 from damage_control.profile import GENERIC
@@ -1500,7 +1500,7 @@ def _record_load_failure(
     detail = getattr(exc, "problem", None) or str(exc) or type(exc).__name__
     where = f"{path}:{line}" if line else str(path)
     try:
-        print(f"agentwire damage-control: SKIPPED {where}: {detail}", file=sys.stderr)
+        print(f"damage-control: SKIPPED {where}: {detail}", file=sys.stderr)
     except Exception:
         # A dead stderr must not turn a reporting line into a changed verdict.
         pass
@@ -2782,7 +2782,7 @@ def unattended_grant_allows(
         # to a looser layer — see parse_unattended_allow.
         return False, (
             f"rule '{rule_id}' is named in unattended_allow but its entry is malformed, "
-            f"so it grants nothing (check `agentwire tasks review` for the reason)"
+            f"so it grants nothing"
         )
     if any(not s for s in scopes):
         return True, f"rule '{rule_id}' is granted unattended (unscoped)"
@@ -5594,11 +5594,11 @@ def _ansi_c_fold(text: str) -> str:
     return _ANSI_C.sub(_dec, text)
 
 
-def _resolve_word(word: str, cwd: str) -> str:
-    """``word`` (already unquoted) made absolute when it names a protected file under ``cwd``."""
+def _resolve_word(word: str, cwd: str, guarded: Callable[[str], bool]) -> str:
+    """``word`` (already unquoted) made absolute when it names a ``guarded`` path under ``cwd``."""
     opt = _OPT_VALUE.fullmatch(word)
     if opt:  # of=<file>, --output=<file>, --output-document=<file>, -o=<file>
-        return opt.group(1) + _resolve_word(opt.group(2), cwd)
+        return opt.group(1) + _resolve_word(opt.group(2), cwd, guarded)
     if word.startswith("-"):
         return word
     if _PLAIN_WORD.fullmatch(word):
@@ -5606,22 +5606,16 @@ def _resolve_word(word: str, cwd: str) -> str:
         if re.search(r"[*?\[]", word):
             hits = _glob_hits(joined)
             return hits[0] if hits else word
-        return joined if is_protected_control_plane(joined) else word
+        return joined if guarded(joined) else word
 
     def _sub(m: "re.Match[str]") -> str:  # a word with quotes inside (python -c "open('x')")
         cand = posixpath.normpath(posixpath.join(cwd, m.group(1)))
-        return cand if is_protected_control_plane(cand) else m.group(0)
+        return cand if guarded(cand) else m.group(0)
 
     return _REL_WORD.sub(_sub, word)
 
 
-def _absolutize(text: str, cwd: str) -> str:
-    """Rewrite words in ``text`` that name a protected file under ``cwd``.
-
-    The text is first folded through what the shell does to a word before the
-    program sees it — ANSI-C ``$'…'``, ``$PWD``, adjacent quotes, backslashes —
-    so the relative spelling reaches the same check the absolute one does.
-    """
+def _absolutize_line(text: str, cwd: str, guarded: Callable[[str], bool]) -> str:
     folded = _ansi_c_fold(text).replace("${PWD}", cwd).replace("$PWD", cwd)
     try:
         lex = shlex.shlex(folded, posix=True, punctuation_chars=True)
@@ -5629,14 +5623,26 @@ def _absolutize(text: str, cwd: str) -> str:
         words = list(lex)
     except ValueError:
         return _REL_WORD.sub(
-            lambda m: _resolve_word(m.group(1), cwd), folded
+            lambda m: _resolve_word(m.group(1), cwd, guarded), folded
         )
-    resolved = [w if _PUNCT_WORD.fullmatch(w) else _resolve_word(w, cwd) for w in words]
+    resolved = [w if _PUNCT_WORD.fullmatch(w) else _resolve_word(w, cwd, guarded) for w in words]
     if resolved == words and folded == text:
         return text
     return " ".join(w if _PUNCT_WORD.fullmatch(w) else _quote_word(w) for w in resolved)
 
 
+def _absolutize(text: str, cwd: str, guarded: Callable[[str], bool] = is_protected_control_plane) -> str:
+    """Rewrite words in ``text`` that name a ``guarded`` path under ``cwd`` (default: the control plane).
+
+    The text is first folded through what the shell does to a word before the
+    program sees it — ANSI-C ``$'…'``, ``$PWD``, adjacent quotes, backslashes —
+    so the relative spelling reaches the same check the absolute one does.
+    Each line is rewritten on its own: a newline separates commands, and
+    flattening it would pull a later command's verb out of command position.
+    """
+    return "\n".join(_absolutize_line(line, cwd, guarded) for line in text.split("\n"))
+
+
 _ASSIGN_STMT = _rx(
     r"(?:^|[;&|\n({]|\b(?:then|do|else))[ \t]*(?:(?:export|local|declare|readonly)[ \t]+)?(?P<n>[A-Za-z_]\w*)=(?P<v>(?:'[^']*'|\"[^\"]*\"|[^\s;&|()<>'\"])*)(?=[ \t]*(?:[;&|\n]|$))"
 )
@@ -5938,6 +5944,19 @@ def _alias_target(path: str) -> Optional[str]:
     return None
 
 
+def _alias_variants(rest: str, cwd: str) -> List[str]:
+    """``rest`` with each relative word that is an existing alias of a protected file spelled as that file."""
+    out: List[str] = []
+    for m in itertools.islice(_PATH_WORD.finditer(rest), _REALPATH_WORD_CAP):
+        word = m.group(0)
+        if word.startswith(("/", "~", "-")) or len(word) < 2:
+            continue
+        target = _alias_target(posixpath.normpath(posixpath.join(cwd, word)))
+        if target:
+            out.append(rest.replace(word, _quote_word(target)))
+    return out
+
+
 def _cwd_realpath_variants(command: str) -> List[str]:
     """``_realpath_variants`` for a relative word after a literal ``cd <dir> &&`` (#1065).
 
@@ -5945,16 +5964,49 @@ def _cwd_realpath_variants(command: str) -> List[str]:
     ``_cwd_variants`` only rewrites words that are lexically protected. The
     aliased word is resolved against the same cwd and judged as what it is.
     """
+    return [new for cwd, rest in _cwd_scopes(command)[0] for new in _alias_variants(rest, cwd)]
+
+
+def _guarded_path_test(config: Dict[str, Any]) -> Callable[[str], bool]:
+    """Whether an absolute path is guarded by ANY class: control plane, zero-access, read-only, no-delete."""
+    patterns = [
+        p
+        for key in ("zeroAccessPaths", "readOnlyPaths", "noDeletePaths")
+        for p in (config.get(key) or [])
+        if isinstance(p, str)
+    ]
+    return lambda path: is_protected_control_plane(path) or any(match_path(path, p) for p in patterns)
+
+
+def _before_first_cd(command: str) -> str:
+    """The text that runs in the payload cwd: everything before the first ``cd`` / ``pushd`` / ``popd``."""
+    starts = [m.start() for rx in (_CD_RE, _POPD_RE) for m in itertools.islice(rx.finditer(command), 1)]
+    return command[: min(starts)] if starts else command
+
+
+def _cwd_resolved_variants(command: str, cwd: Optional[str], config: Dict[str, Any]) -> List[str]:
+    """``command`` with each relative operand that names a guarded path spelled absolutely.
+
+    Relative operands are resolved against the payload ``cwd`` — and its
+    ``realpath``, when the cwd is itself a symlink — for the text that runs
+    there, and against each literal ``cd <dir> &&`` / ``git -C`` / ``env -C``
+    scope for the text that runs in it. The absolute spelling is then judged by
+    the same rules as any other, so ``> .claude/settings.json`` from ``$HOME`` is
+    ``> ~/.claude/settings.json``. A missing cwd adds nothing: what a relative
+    word means is then unknown, which the unverifiable-target verdict owns.
+    """
+    scopes = list(_cwd_scopes(command)[0])
+    if cwd and os.path.isabs(cwd):
+        lead = _before_first_cd(command)
+        scopes += [(base, lead) for base in dict.fromkeys((posixpath.normpath(cwd), os.path.realpath(cwd)))]
+    guarded = _guarded_path_test(config)
     out: List[str] = []
-    for cwd, rest in _cwd_scopes(command)[0]:
-        for m in itertools.islice(_PATH_WORD.finditer(rest), _REALPATH_WORD_CAP):
-            word = m.group(0)
-            if word.startswith(("/", "~", "-")) or len(word) < 2:
-                continue
-            target = _alias_target(posixpath.normpath(posixpath.join(cwd, word)))
-            if target:
-                out.append(rest.replace(word, _quote_word(target)))
-    return out
+    for base, text in scopes:
+        new = _absolutize(text, base, guarded)
+        if new != text:
+            out.append(new)
+        out.extend(_alias_variants(text, base))
+    return list(dict.fromkeys(out))
 
 
 def _cwd_variants(command: str) -> List[str]:
@@ -9920,7 +9972,7 @@ def audit_best_effort(log: Any) -> Any:
             log(*args, **kwargs)
         except Exception as e:
             try:
-                print(f"agentwire: audit log failed ({type(e).__name__}) — decision unchanged",
+                print(f"damage-control: audit log failed ({type(e).__name__}) — decision unchanged",
                       file=sys.stderr)
             except Exception:
                 pass
@@ -10020,6 +10072,15 @@ def _decide_command(
     outer one.
     """
     verdict = _decide_rules(command, config, cwd)
+    resolved = []
+    if not verdict.get("protected"):
+        # The control plane outranks the escape hatch and the kill switch, so a
+        # relative spelling of it is judged before either can end the walk.
+        for variant in _cwd_resolved_variants(command, cwd, config):
+            inner = _decide_rules(variant, config)
+            if inner.get("protected"):
+                return dict(inner, command=command)
+            resolved.append(inner)
     if (
         _depth >= _RESCAN_DEPTH
         or verdict.get("protected")
@@ -10028,8 +10089,10 @@ def _decide_command(
         or verdict["decision"] == "block"
     ):
         return verdict
-    for hidden in _hidden_commands(command, rules=True):
-        inner = _decide_command(hidden, config, cwd, _depth + 1)
+    for inner in itertools.chain(
+        resolved,
+        (_decide_command(hidden, config, cwd, _depth + 1) for hidden in _hidden_commands(command, rules=True)),
+    ):
         if _DECISION_RANK[inner["decision"]] > _DECISION_RANK[verdict["decision"]] and not (
             inner.get("escape") or inner.get("disabled")
         ):

damage_control_dev-0.1.2/tools/check_links.py

@@ -0,0 +1,85 @@
+#!/usr/bin/env python3
+"""Fail if a relative link in the repository's Markdown files does not resolve.
+
+Checks ``[text](target)`` links in README.md, SECURITY.md, CONTRIBUTING.md and docs/*.md:
+the target file must exist, and a ``#fragment`` must match a heading in that file (GitHub's
+slug rules) or an explicit ``<a id=...>``. External ``http(s)``/``mailto`` links are not fetched.
+
+    check_links.py        # exit 1 and list every broken link
+"""
+
+from __future__ import annotations
+
+import re
+import sys
+from pathlib import Path
+from typing import List, Set
+
+ROOT = Path(__file__).resolve().parent.parent
+LINK_RE = re.compile(r"(?<!\!)\[[^\]]*\]\(([^)\s]+)\)")
+HEADING_RE = re.compile(r"^(#{1,6})\s+(.*?)\s*#*\s*$")
+ANCHOR_RE = re.compile(r'<a\s+(?:id|name)="([^"]+)"')
+
+
+def slug(heading: str) -> str:
+    """GitHub's heading anchor: lowercase, drop punctuation except ``-`` and ``_``, spaces to ``-``."""
+    text = re.sub(r"`", "", heading.strip().lower())
+    text = re.sub(r"[^\w\- ]", "", text)
+    return text.replace(" ", "-")
+
+
+def anchors(path: Path) -> Set[str]:
+    found: Set[str] = set()
+    counts: dict = {}
+    in_fence = False
+    for line in path.read_text().splitlines():
+        if line.startswith("```"):
+            in_fence = not in_fence
+            continue
+        if in_fence:
+            continue
+        m = HEADING_RE.match(line)
+        if m:
+            base = slug(m.group(2))
+            n = counts.get(base, 0)
+            counts[base] = n + 1
+            found.add(base if n == 0 else f"{base}-{n}")
+        found.update(ANCHOR_RE.findall(line))
+    return found
+
+
+def markdown_files() -> List[Path]:
+    return sorted([*ROOT.glob("*.md"), *ROOT.glob("docs/*.md")])
+
+
+def check(path: Path) -> List[str]:
+    problems: List[str] = []
+    in_fence = False
+    for number, line in enumerate(path.read_text().splitlines(), 1):
+        if line.startswith("```"):
+            in_fence = not in_fence
+            continue
+        if in_fence:
+            continue
+        for target in LINK_RE.findall(line):
+            if re.match(r"[a-z][a-z0-9+.-]*:", target):
+                continue
+            name, _, fragment = target.partition("#")
+            dest = (path.parent / name).resolve() if name else path
+            where = f"{path.relative_to(ROOT)}:{number}"
+            if not dest.exists():
+                problems.append(f"{where}: {target}: no such file")
+            elif fragment and dest.suffix == ".md" and fragment not in anchors(dest):
+                problems.append(f"{where}: {target}: no heading '#{fragment}' in {dest.relative_to(ROOT)}")
+    return problems
+
+
+def main() -> int:
+    problems = [p for f in markdown_files() for p in check(f)]
+    for problem in problems:
+        print(problem, file=sys.stderr)
+    return 1 if problems else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

{damage_control_dev-0.1.0 → damage_control_dev-0.1.2}/tools/coverage_matrix.py

@@ -30,7 +30,7 @@ def render() -> str:
     for matcher, hook in claude_code.MATCHERS.items():
         tools, shell = adapter.HOOK_KINDS[hook]
         if tools is None:
-            kind, judges = "mcp", "the tool name and its path-valued arguments, plus a synthesized shell command for outbound tools"
+            kind, judges = "mcp", "the tool name and its path-valued arguments, plus, where a host profile maps the tool, the shell command it runs"
         else:
             names = [t for t, (_, _) in tools.items() if matcher == "mcp__.*" or t == matcher]
             kind = tools[names[0]][0] if names else "?"
@@ -42,7 +42,11 @@ def render() -> str:
     return "\n".join([
         "# Coverage",
         "",
-        "Generated by `tools/coverage_matrix.py` from the hooks' own tables; `--check` fails if it is stale.",
+        "Which Claude Code tools damage control judges, and how. Anything not listed is not judged; see the",
+        "[threat model](threat-model.md#what-it-does-not-protect-against).",
+        "",
+        "This page is generated by `tools/coverage_matrix.py` from the hooks' own tables; do not edit it by hand.",
+        "CI fails if the committed file is stale. Regenerate with `python tools/coverage_matrix.py`.",
         "",
         "| Tool matcher | Hook | Judged on | Block | Ask | Audited |",
         "|---|---|---|---|---|---|",

damage_control_dev-0.1.0/PKG-INFO

@@ -1,15 +0,0 @@
-Metadata-Version: 2.5
-Name: damage-control-dev
-Version: 0.1.0
-Summary: Damage control for AI coding agents: a PreToolUse guard that blocks or asks before destructive commands and protected-path writes (Claude Code).
-Author-email: dotdev <dev@dotdev.dev>
-License: Apache-2.0
-License-File: LICENSE
-License-File: NOTICE
-Keywords: agent,ai,claude-code,hooks,safety
-Classifier: Operating System :: MacOS
-Classifier: Operating System :: POSIX :: Linux
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.9
-Requires-Python: >=3.9
-Requires-Dist: pyyaml>=6.0