Skip to content

Docs: credential-gate override logging is best-effort, not guaranteed (fixes #119) - #222

Merged
F-e-u-e-r merged 1 commit into
mainfrom
issue119-docs-bestefort-logging
Aug 28, 2026
Merged

Docs: credential-gate override logging is best-effort, not guaranteed (fixes #119)#222
F-e-u-e-r merged 1 commit into
mainfrom
issue119-docs-bestefort-logging

Conversation

@F-e-u-e-r

Copy link
Copy Markdown
Owner

Summary

Fixes #119. Docs only — code/runtime unchanged; the code stays authoritative.

The credential-gate section of both README mirrors overstated the override's audit contract: "every use is logged" reads as a guarantee, while the hook's own _log() swallows every exception (except Exception: pass) and the README's shared auditability paragraph already describes hook log writes as best-effort. This PR softens the overstatement to the actual contract, in English/zh-Hant parity, preserving all four facts:

  1. the approved override still carries audit-log intent;
  2. every approved override attempts to append an audit event;
  3. a failed write may be silently dropped;
  4. a logging failure never blocks the hook.
Mirror Before After
README.md "…not proof of consent — every use is logged." "…not proof of consent — every approved override attempts to append an audit event, but the log write is best-effort: a failed write is silently dropped and never blocks the hook."
README.zh-Hant.md 「……不是同意的證明——每次使用都會留 log。」 「……不是同意的證明——每次 approved override 都會嘗試追加一筆稽核事件;log 寫入是盡力而為(best-effort),寫入失敗會被靜默丟棄,且絕不阻擋 hook 本身。」

Verification

  • Mechanical proofs: each preimage present exactly once before the edit; both postimages carry the four facts; no "usually/normally logged" hedge introduced; the existing shared best-effort auditability paragraph is untouched; diff is exactly the two README mirrors; hooks/gate-credential-destruction.py blob byte-identical to main; the _log() exception swallow re-confirmed first-hand at the current head.
  • checks.py green (including the README projection-parity gate and the invisible-Unicode sweep).
  • No behavioral change; no skill/doctrine/metadata/hook bytes.

🤖 Generated with Claude Code

https://claude.ai/code/session_0132RthrKSsMkywcEwtkXhkx

…#119)

Docs-only correctness fix in both README mirrors. The credential-gate
section claimed the approved override's every use is logged; the hook's
own _log() swallows every exception (except Exception: pass) and the
README's shared auditability paragraph already says hook log writes are
best-effort. Both mirrors now state the actual contract in parity: every
approved override ATTEMPTS to append an audit event, the write is
best-effort, a failed write is silently dropped, and a logging failure
never blocks the hook. Runtime/code unchanged; code stays authoritative.

Fixes #119

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0132RthrKSsMkywcEwtkXhkx
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Doc overstatement: credential-gate override "every use is logged" is best-effort (README.md:367 + zh:252)

1 participant