docs: document invariantModes and disabledInvariants policy overrides

[jpleva91]

Summary

• Adds an "Invariant Configuration (Policy Overrides)" section to CLAUDE.md under Architecture & Key Patterns
• Documents the two policy YAML mechanisms for overriding built-in invariants: invariantModes (monitor mode — warn but allow) and disabledInvariants (completely disable)
• Includes a YAML example and references the source files where these are defined and composed

Test plan

• Verify the new section renders correctly in the CLAUDE.md
• Confirm the referenced source files (packages/invariants/src/definitions.ts, packages/policy/src/yaml-loader.ts, packages/policy/src/composer.ts) are accurate

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Adds documentation to CLAUDE.md describing how operators can override built-in invariant behavior via policy configuration.

Changes:

• Adds an “Invariant Configuration (Policy Overrides)” section under Architecture & Key Patterns.
• Documents two override mechanisms (invariantModes / disabledInvariants) and provides a YAML example.
• References the source files responsible for parsing and composing these settings.

[Copilot]

The doc refers to a policy YAML field invariantModes and the example uses invariantModes:, but the YAML loader actually expects an invariants: mapping at the top level (parsed into policy.invariantModes). As written, the example/config key won’t be recognized by parseYamlPolicy() in packages/policy/src/yaml-loader.ts.

Suggested change

	The 26 built-in invariants (defined in `packages/invariants/src/definitions.ts`) enforce by default, but operators can override them in policy YAML via two mechanisms. **`invariantModes`** sets an invariant to `monitor` mode — it still evaluates and emits warnings but does not block the action, useful for rolling out new invariants or during planned maintenance. **`disabledInvariants`** completely removes an invariant from evaluation — use sparingly, as it eliminates the safety check entirely. Both fields are parsed in `packages/policy/src/yaml-loader.ts` and merged across composed policies in `packages/policy/src/composer.ts` (disabled invariants union across all sources).
	```yaml
	# Set a specific invariant to monitor mode (warn but don't block)
	invariantModes:
	The 26 built-in invariants (defined in `packages/invariants/src/definitions.ts`) enforce by default, but operators can override them in policy YAML via two mechanisms. **`invariants`** is the top-level mapping used in YAML to set an invariant to `monitor` mode — it still evaluates and emits warnings but does not block the action, useful for rolling out new invariants or during planned maintenance. This mapping is parsed into `policy.invariantModes` by `packages/policy/src/yaml-loader.ts`. **`disabledInvariants`** completely removes an invariant from evaluation — use sparingly, as it eliminates the safety check entirely. Both fields are merged across composed policies in `packages/policy/src/composer.ts` (disabled invariants union across all sources).
	```yaml
	# Set a specific invariant to monitor mode (warn but don't block)
	invariants:

[Copilot]

This paragraph says both invariantModes and disabledInvariants are “merged across composed policies in composer.ts”, but composePolicies() only unions disabledInvariants—it does not merge/resolve invariant mode overrides. Invariant mode precedence is resolved elsewhere (e.g., CLI’s buildModeConfig() reads the first policy with invariantModes, and resolveInvariantMode() applies defaults), so the doc should reflect that (or reference those files instead).

Suggested change

The 26 built-in invariants (defined in `packages/invariants/src/definitions.ts`) enforce by default, but operators can override them in policy YAML via two mechanisms. **`invariantModes`** sets an invariant to `monitor` mode — it still evaluates and emits warnings but does not block the action, useful for rolling out new invariants or during planned maintenance. **`disabledInvariants`** completely removes an invariant from evaluation — use sparingly, as it eliminates the safety check entirely. Both fields are parsed in `packages/policy/src/yaml-loader.ts` and merged across composed policies in `packages/policy/src/composer.ts` (disabled invariants union across all sources).

The 26 built-in invariants (defined in `packages/invariants/src/definitions.ts`) enforce by default, but operators can override them in policy YAML via two mechanisms. **`invariantModes`** sets an invariant to `monitor` mode — it still evaluates and emits warnings but does not block the action, useful for rolling out new invariants or during planned maintenance. **`disabledInvariants`** completely removes an invariant from evaluation — use sparingly, as it eliminates the safety check entirely. Both fields are parsed in `packages/policy/src/yaml-loader.ts`, but only **`disabledInvariants`** is merged across composed policies in `packages/policy/src/composer.ts` (unioned across all sources). **`invariantModes`** overrides are resolved later by the CLI/runtime configuration rather than merged in the policy composer.