From 92a7de4f842ed608e8cfc9db79cb2a65d4da26ad Mon Sep 17 00:00:00 2001 From: CleverThis Date: Fri, 10 Apr 2026 20:44:54 +0000 Subject: [PATCH] docs(spec): clarify invariant CLI completeness requirements UAT findings #7461 and #7462 identified two spec-implementation gaps in the invariant system: 1. Missing --non-overridable CLI flag (#7461): The spec defines 'agents invariant add --global --non-overridable' but the CLI raises 'No such option: --non-overridable'. System administrators cannot create non-overridable global safety constraints. 2. Action-scope omitted from --effective output (#7462): The spec defines four-tier precedence (plan > action > project > global) but InvariantService.get_effective_invariants() only merges plan/project/ global, omitting action scope entirely. The --effective output also ignores non_overridable semantics. Added 'CLI completeness requirements for invariants' section clarifying: - --non-overridable flag MUST be implemented (global scope only) - Action-scope MUST be included in --effective output - non_overridable semantics MUST be correctly applied in --effective Refs: UAT #7461, UAT #7462 --- CHANGELOG.md | 5 +++++ docs/specification.md | 8 ++++++++ 2 files changed, 13 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 89d67e2c3..a72969b15 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -96,6 +96,11 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). ### Changed +- **Invariant CLI Completeness Spec Clarification** (#7461, #7462): Added a + "CLI completeness requirements for invariants" section to the specification + mandating the `--non-overridable` global flag, inclusion of action scope in + `agents invariant list --effective`, and correct non_overridable semantics in + the effective invariant output. - **Decision Tree Full ULID Display** (#5825): The `agents plan tree` command now displays full 26-character ULIDs for all decisions instead of truncating them to 8 characters. This enables users to copy decision IDs directly from tree output diff --git a/docs/specification.md b/docs/specification.md index dbe7bd381..33067865b 100644 --- a/docs/specification.md +++ b/docs/specification.md @@ -19748,6 +19748,14 @@ Each effective invariant is then recorded as an `invariant_enforced` decision in **Non-overridable global invariants**: A global invariant may be marked `non_overridable: true`. When set, this invariant takes precedence over all lower-scope invariants regardless of the normal precedence chain -- even plan-level invariants cannot override it. This is intended for system-wide safety constraints that must never be relaxed (e.g., "Never commit secrets to version control"). Non-overridable invariants are set via `agents invariant add --global --non-overridable ""`. The `non_overridable` flag is only meaningful on `GLOBAL`-scoped invariants; it is ignored on project, action, and plan invariants. +**CLI completeness requirements for invariants**: + +1. **`--non-overridable` flag**: The `agents invariant add --global --non-overridable ""` command MUST be implemented. Without this flag, system administrators cannot create non-overridable global safety constraints, making the safety override feature effectively unusable. The flag is only accepted when combined with `--global`; using it with `--project`, `--action`, or `--plan` MUST raise a validation error. + +2. **Action-scope in `--effective` output**: The `agents invariant list --effective` command MUST include action-scope invariants in the effective set. The four-tier precedence is `plan > action > project > global` — action-scope invariants sit between plan and project scope. Omitting action-scope invariants from the effective view causes the CLI output to disagree with the Invariant Reconciliation Actor used during Strategize, making `--effective` unreliable for UAT validation. + +3. **`non_overridable` in `--effective` output**: The `--effective` output MUST correctly apply `non_overridable` semantics. When a global invariant has `non_overridable: true`, it MUST appear at the top of the effective set and MUST NOT be overridden by plan-scope invariants, even when a plan-scope invariant would normally take precedence. The output MUST indicate which invariants are non-overridable (e.g., via a `[NON-OVERRIDABLE]` marker or a dedicated column). + **Child plan inheritance**: When a top-level plan spawns child plans, the parent's effective invariant view (already reconciled) is passed down to each child plan. Child plans do not re-run reconciliation — they inherit the parent's resolved view. **Correcting invariants**: The correction mechanism for `invariant_enforced` decisions supports two operations: -- 2.52.0