From 9ffadc1b1fc5d1f8739e3d2ec6715ccd08b32769 Mon Sep 17 00:00:00 2001 From: atbagan Date: Mon, 18 May 2026 19:43:55 -0500 Subject: [PATCH] docs(adr): pin mode is exactly one value MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The original §5 mode-semantics text allowed pin to carry one or many Values, with the modal switching between a read-only single entry and a list. That made pin and allowList only differ by the optional Default field, which is a weak distinction the form implementation surfaced as a real UX problem (operators added multiple values to a "pin" rule when they expected a singleton). Update §5 pin definition: Values must have length 1; the modal renders the entry as a single read-only selection. Use allowList when the value count is unbounded; use pin only when the single- value semantics are deliberate. Mode-behavior table row for pin updated to "Yes (single value)" and "Renders read-only" so the orthogonal grid reads cleanly: pin: single value, enforcing default: single value, advisory allowList: multi value, enforcing recommended: multi value, advisory butler-controller webhook (PR #105) enforces len(Values) == 1 for pin. butler-console form (PR #76) renders pin as a single-select. No design change beyond clarifying intent that was already present in the name "pin". --- docs/architecture/ADR-018-cluster-creation-policy.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/architecture/ADR-018-cluster-creation-policy.md b/docs/architecture/ADR-018-cluster-creation-policy.md index 503ae40..fa9ffbe 100644 --- a/docs/architecture/ADR-018-cluster-creation-policy.md +++ b/docs/architecture/ADR-018-cluster-creation-policy.md @@ -136,7 +136,7 @@ Adding a new option type beyond this four requires butler-server handler changes ### 5. Mode semantics -- **pin**: the only acceptable values for this option. The modal renders the pinned list (when length is greater than one) or renders the single pinned entry as read-only (when length is one). Admission rejects any TenantCluster create or update whose corresponding spec field references a value outside `Values`. +- **pin**: exactly one acceptable value for this option. `Values` must have length 1. The modal renders the pinned entry as a single read-only selection. Admission rejects any TenantCluster create or update whose corresponding spec field references a different value. Use `allowList` with one entry when you want a single-value enforcing rule that the admin may later widen; use `pin` when the single-value semantics are deliberate. - **allowList**: the acceptable values for this option. The modal renders the allow-listed subset. `Default` (when set) is pre-selected. Admission rejects values outside `Values`. - **default**: presentation only. The modal renders the full provider response. `Default` is pre-selected. Admission does not enforce. - **recommended**: presentation only. The modal renders the full provider response. Entries in `Values` are badged and sorted first. `RecommendedReason` (when set) appears in the badge tooltip. Admission does not enforce. @@ -145,7 +145,7 @@ Summary of mode behaviors: | Mode | Filters dropdown | Pre-selects default | Badges entries | Admission enforces | |---|---|---|---|---| -| pin | Yes | When single entry, renders read-only | No | Yes | +| pin | Yes (single value) | Renders read-only | No | Yes | | allowList | Yes | When default set | No | Yes | | default | No | Yes | No | No | | recommended | No | No | Yes | No |