nacre: Skill for Claude Code

Changing the permission model

This is the module where a mistake is a leaked document that gets discovered in an auditor's report. docs/authz.md is normative — implement it as written and raise deviations rather than absorbing them.

Before touching code

Read docs/authz.md in full, not the section you think you need. The rules interact: rule 5 (any deny beats any allow, at any depth) and rule 4 (inheritance downward) together mean a deny on a workspace kills an explicit allow on a document beneath it. That row is in the truth table and it is the one people get wrong.

The check for every diff

Answer all three explicitly in the PR description — the template asks:

1. Is filtering still applied during index traversal? Not after ranking, not by fetching more and trimming. If your change adds a code path that receives results and removes some, it is wrong regardless of what it removes.
2. What happens when permission evaluation fails? Every failure — timeout, cache miss that cannot be filled, malformed grant — denies. There is no fallback that widens access. Look specifically for catch blocks that continue.
3. Are "no permission" and "no such object" still indistinguishable? Same status, same body, same timing characteristics where practical. A different error string is a leak.

Rules easiest to break by accident

• write does not imply read (rule 6), while admin implies both (rule 7). Every other permission system trains the opposite instinct. If you find yourself writing if (perm >= read), stop — permissions are not ordered.
• Deny is absolute, not nearest-wins. Do not implement "most specific scope wins"; that is a different model and it grants access the spec denies.
• platform_admin reads no documents (rule 2). Administering a tenant is not access to its data.
• acl_tags is a cache. The grants table is the source of truth. Until a recomputation finishes, the layer filter and the tag filter both apply — do not "simplify" that to one.
• Tag hashes are truncated to 8 bytes and collide by design. That is only safe because the query is also bounded by allowed layer_id. Removing the layer bound makes the truncation a leak.