diff --git a/CONTEXT.md b/CONTEXT.md index df27ad3..0c10271 100644 --- a/CONTEXT.md +++ b/CONTEXT.md @@ -5,6 +5,22 @@ extensions that inspect and re-evaluate Bash commands before they are allowed. ## Language +### Authority + +**Enforce authority**: +Allow-only delegation — when the Judge's verdict is `allow` and every gate in +the Enforce truth table passes, the command runs without the human dialog. The +Judge can never answer `deny` with authority; every uncertain case (defer, +deny, preflight, infrastructure failure) falls back to the human dialog. +_Avoid_: AI takeover, auto-deny, full delegation + +**Audit log (Judge-owned)**: +The Enforce-era accountability record written by the Judge package itself — +separate file from the permission-system review log, append + fsync per +record, self-checked for health; an unhealthy audit log refuses authority. +_Avoid_: host contract (dropped — see ADR 0006), acknowledged write (upstream +sense) + ### Wrappers **Wrapper**: diff --git a/docs/adr/0006-enforce-audit-self-sufficiency.md b/docs/adr/0006-enforce-audit-self-sufficiency.md new file mode 100644 index 0000000..47c4014 --- /dev/null +++ b/docs/adr/0006-enforce-audit-self-sufficiency.md @@ -0,0 +1,74 @@ +--- +status: accepted +--- + +# Enforce audit self-sufficiency — no upstream host contract + +PIEXTENSIO-10 (promotion governance) and PIEXTENSIO-13/15 (host contract +and enforce gates) conditioned the allow-only Enforce authority on a +formal **host contract** in upstream `@gotgenes/pi-permission-system`: +acknowledged review writes, capability versioning, pre-link enrollment, +and a LocalUserAuthorizer-only human-decision marker. We decided to drop +that dependency: every guarantee Enforce needs will be **provided by the +Judge package itself**, and the upstream stays untouched at zero changes. + +## Why the original design was wrong + +Not "too early" — structurally wrong. Every contract item is complexity +the upstream maintainer must carry **forever**, serving a plugin he does +not use. His own users gain nothing from it. A PR of that shape sits in +the queue forever (observed: upstream has unprocessed PRs already). +Designing our audit needs as host obligations is asking someone else to +pay for our feature. + +The "self-recording is untrustworthy" argument also failed scrutiny under +the actual threat model: this Judge runs on the operator's own machine, +single-user. The Judge can be *buggy* but has no motive to *deceive*. +Bugs are covered by in-process self-checks; "independent third-party +audit" is an enterprise-multi-tenant requirement we do not have. +(The original patches were also lost with `~/Projects/.workspace/` +cleanup and were never pushed — the dependency was not just unwanted but +gone.) + +## What self-sufficiency means concretely + +1. **Judge-owned audit log**, separate file from the permission-system + review log (which also solves an operational pain: that log is ~850KB + of mixed events). Append + fsync per record; a failed write marks the + runtime **unhealthy**, and the Enforce truth table's telemetry gate + refuses authority while unhealthy. This is the self-implemented + version of "acknowledged writes". +2. **Human-decision attribution at the consumption side.** Real-human + decisions are distinguishable by event shape + (`approved`/`denied` from the dialog vs `session_approved`/ + `auto_approved`/`infrastructure_auto_allowed`), verified against live + data in the 2026-08-17 TUI cohort (round 5 showed forwarded + `auto_approved` double-writes). The analyzer filters cohort rows on + this shape instead of the upstream marking humans. +3. **Denominator redefined** as "asks the Judge itself received" + (waiting rows in the Judge log), not upstream pre-link enrollment. + Self-consistent bookkeeping; the PIEXTENSIO-10 floor math applies to + this denominator unchanged. +4. The truth-table gate `hostContractPresent` becomes a **local + self-check gate** (audit log healthy). Mechanically identical in + effect: today's production state already defers unconditionally. + +## What is explicitly not weakened + +- The PIEXTENSIO-10 floor (100 qualified rows, zero false allows, + per-segment) stands, computed on the self-owned log. +- Allow-only semantics stand: the Judge never denies; every uncertain + case defers to the human dialog. +- Fail-closed stands: audit unhealthy → defer; malformed evidence → + defer; unknown state → defer. + +## Consequences + +- PIEXTENSIO-15 is cancelled (single-consumer upstream feature = + unmaintainable dependency). Its lessons stay here. +- If the upstream ever ships an equivalent contract on its own + initiative, the Judge may adopt it later; nothing in this design + blocks that. Revisit trigger: multi-user / multi-tenant deployments + where the "buggy-but-honest" threat model no longer holds. +- Promotion cohort identity is unaffected (model/prompt/evidence + profile); the audit-log switch is a governance-consumer change.