# deadlock-breaker (Carehab Open Duo, v0.1.0, MIT)

Defensive duo. When a task is blocked by contradictory policies or missing rights, the agent may only:
(a) detect the deadlock, (b) produce a ContractDiff and one narrow authorization REQUEST addressed to a human role, (c) stop and wait.
Nothing here grants, escalates or self-authorizes permissions.

## Parts
- `skills/deadlock-breaker/SKILL.md` - advice to the agent (not an enforcement gate).
- `verifier/contract_diff.py` - `--contract --policy --grants` -> ContractDiff JSON (sorted keys, deterministic). Exit 0 OK, 3 blocked, 2 usage. Verdicts: OK, BLOCKED_MISSING_RIGHTS, BLOCKED_POLICY_CONTRADICTION, BLOCKED_BOTH.
- `verifier/check_mandate.py` - `--request --mandate [--used-nonces] [--now]` -> ACCEPT/REJECT with reasons. Exit 0 ACCEPT, 3 REJECT, 2 usage.
- `operator/` - mandate template (md + json) and 60-second request review card.
- `fixtures/` - synthetic data only.

## Input model
- contract: `{contract_id, human_role, requested_ttl_minutes?, required:[{id, description, evidenced, required_rights:[{action, resource}]}]}`; `evidenced: true` items form `outcome_verified`, the rest are `gaps`.
- policy: `{rules:[{id, effect: allow|deny, action, resource, priority, text, source}]}`; the highest-priority matching rules decide; an allow and a deny at that level are a contradiction. A rule may use a lone `*` to match; requests never may.
- grants: `{rights:[{action, resource}]}`; exact matches only, wildcard grants are not honoured.

## Install (proven scope: Claude Code only)
Copy `skills/deadlock-breaker/` to `~/.claude/skills/deadlock-breaker/` or `<project>/.claude/skills/deadlock-breaker/`. Keep `verifier/` where `python3` can run it. Python 3 stdlib only.

## Test
```
./run_tests.sh
```
(equivalent: `python3 -m unittest discover -s tests -v`; exit code is non-zero on failure.)

## Limitations (read these)
- `check_mandate.py` is a CONSISTENCY check only (exact action/resource, ttl, expiry, unused nonce, no wildcard, human role, `signed_by_human: true`, signature note). Without real signature infrastructure it does NOT authenticate a human: anyone who can write the JSON can write `signed_by_human: true`. Real authorization must come from your own access-control system.
- The tool grants nothing. ACCEPT means "internally consistent", not "authorized".
- The tool never writes the used-nonces file; the caller must record a used nonce.
- SKILL.md is advice, not an enforcement gate; an agent that ignores it is not stopped by this package.
- Not claimed: cross-agent compatibility beyond Claude Code; protection against a compromised host; policy-language coverage beyond exact/`*` matching.

## Trust model (who runs the verifier)

- The verifier lives in `verifier/`, outside `skills/<name>/`. The Claude Code skill-directory install copies only `SKILL.md`; run the verifier from the unpacked zip.
- A verifier result counts as evidence only when a human or CI ran it. If the agent runs its own verifier, the output is still an agent claim.
- The sha256 values in `manifest.json` and on the website are served from the same origin as the files: they detect corruption, not a compromised host. Nothing here is labelled "verified" by a third party.
- The verifier declarations in `manifest.json` (`tools_permissions`) are documentation, not an enforced sandbox.
- No wellbeing or effectiveness effect is claimed for any artifact in this package.