design: updated design/router-decision-matrix.md

[raskolnikoff]

This pull request adds a formal, machine-readable specification for the router decision matrix, along with a JSON schema for structural validation and CI enforcement guidelines. These changes ensure that routing behavior is explicitly defined, versioned, and validated to prevent contract drift or unintended changes.

Router Decision Matrix Formalization:

• Added a normative, machine-readable YAML table in Section 8 that codifies all router rules, defaults, failure handling, and invariants for deterministic routing behavior.
• Introduced a JSON schema in Section 9 to structurally validate the router decision table, ensuring all required keys and rule formats are present.

Continuous Integration (CI) Enforcement:

• Defined a CI policy to extract, convert, and validate the YAML decision table against the schema, failing the build on validation errors to prevent silent contract drift.

Documentation and Process:

• Clarified that the machine-readable table is the authoritative contract and that any changes require an ADR update and must pass schema validation before merging.

[Copilot]

Pull request overview

This PR adds formal machine-readable specifications for the router decision matrix design document, introducing a normative YAML-based decision table and a JSON schema for structural validation. The changes aim to codify routing behavior explicitly and enable CI-based contract enforcement to prevent silent drift in routing logic.

Changes:

• Added Section 8 with a machine-readable YAML decision table specifying routing rules, failure handling, and invariants
• Added Section 9 with a JSON schema for validating the decision table structure and CI enforcement guidelines
• Removed the generic statement about versioned modifications (line 200) in favor of more specific ADR requirements in the new sections

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

The JSON schema does not specify "additionalProperties": false for object definitions, which means unknown fields will be silently accepted during validation. This could allow "silent contract drift" (mentioned on line 353) if extra fields are inadvertently added to the YAML.

Consider adding "additionalProperties": false to the schema objects at lines 294, 298, 310, 322 to enforce strict validation and prevent unintended fields from passing validation.

[Copilot]

The LOCAL_EXECUTION_FAILURE rule checks "fallback_allowed: true" as a condition (line 256), but this creates a circular dependency with the routing decision. The fallback_allowed flag should be an input from the initial routing decision, not a condition to check during failure handling.

According to Section 3 (Rule 3), fallback should occur "If route == 'local' AND execution fails" when "fallback_allowed == true". The YAML should clarify whether fallback_allowed is checked as a stored routing decision property or as a runtime condition.

Suggested change

	- id: LOCAL_EXECUTION_FAILURE
	condition:
	route: "local"
	execution_failed: true
	fallback_allowed: true
	# Failure handling is based on the stored outcome of the initial routing decision.
	# `initial_routing.fallback_allowed` MUST be read from the original decision,
	# not recomputed at failure time.
	- id: LOCAL_EXECUTION_FAILURE
	condition:
	route: "local"
	execution_failed: true
	initial_routing:
	fallback_allowed: true

[Copilot]

The "otherwise: true" construct in the AUTO_CLOUD rule (line 245) lacks clear semantic definition. In a deterministic routing system, catch-all conditions should be explicitly defined rather than using an implicit "otherwise" keyword.

Consider either:

1. Explicitly defining the negation of AUTO_LOCAL conditions
2. Documenting that "otherwise: true" means "evaluate this rule if no previous rules matched"
3. Adding this construct to the JSON schema validation with specific semantics

This is important for the stated goal of deterministic, machine-validatable routing behavior.

[Copilot]

The JSON schema defines "condition" and "action" as generic objects with no structural constraints (lines 314-315, 326-327). This provides no validation of the actual routing logic and defeats the purpose of preventing "malformed rule definitions" (line 352).

To enable meaningful CI validation, the schema should define the expected properties for conditions (e.g., privacy_level, token_count_lte_threshold, local_model_available) and actions (e.g., route, fallback_allowed, return_error, log_escalation), potentially using oneOf or anyOf for different rule patterns.

[Copilot]

The AUTO_LOCAL rule (lines 232-240) does not include a network_state condition, but Section 2 (lines 72-79) states "Network state MUST be checked before cloud route selection." Additionally, Section 3 Rule 2 explicitly states for auto mode: "network_state is irrelevant" (line 117).

However, if the system routes to cloud in AUTO_CLOUD mode without checking network availability, cloud execution could fail unnecessarily. Consider adding network_state validation either as a condition in AUTO_CLOUD or as a separate validation step before cloud execution.

[Copilot]

The CI enforcement policy uses "SHOULD" (line 342) which is a weak recommendation according to RFC 2119, but then states that changes "MUST pass schema validation before merge" (line 355). This creates ambiguity about whether CI validation is optional or mandatory.

For a formal contract enforcement mechanism, consider changing "CI SHOULD:" to "CI MUST:" to match the mandatory nature of validation stated in line 355.

[Copilot]

The YAML invariants structure is inconsistent with the JSON schema definition. The YAML defines invariants as key-value pairs (objects with boolean/string values like "deterministic: true"), but the JSON schema on line 334 expects an array of strings. This inconsistency will cause schema validation to fail.

Either change the YAML invariants to be an array of strings (e.g., ["deterministic", "no_probabilistic_routing", ...]) or update the JSON schema to expect an array of objects with appropriate properties.

Suggested change

	- deterministic: true
	- no_probabilistic_routing: true
	- no_hidden_fallback: true
	- no_recursive_routing: true
	- deterministic
	- no_probabilistic_routing
	- no_hidden_fallback
	- no_recursive_routing

[Copilot]

The condition "token_count_lte_threshold: true" is ambiguous in a machine-readable context. The YAML uses a boolean value to represent a comparison operation, which may not be suitable for automated validation. Consider using a more explicit structure like "token_count: { lte: "threshold" }" or documenting that boolean conditions represent state checks rather than comparisons.

This affects rules AUTO_LOCAL (lines 232-240) where token_count_lte_threshold, local_model_available, and intent_supported_by_local are all boolean flags representing computed conditions.

Suggested change

	token_count_lte_threshold: true
	token_count:
	lte: "token_threshold"