docs: cumulative strict-mode constraint list + spec-version-drift test

Captures two follow-ups surfaced by the four CoPilot review rounds:

- docs/concepts/llms.md "Strict mode" section expanded into the
  full constraint list. After four rounds of tightening the
  strict_mode_supported heuristic, the rule set is stable and the
  user-facing surface should list it directly rather than make
  callers read provider.py. The page frames the list as the
  authoritative set: anything not on it trips to non-strict.

- docs/model-providers/index.md "Strict mode" subsection trimmed
  and now links into the concepts page for the full list,
  following the established split (concepts/ owns the deep-dive,
  model-providers/ stays terse).

- tests/test_smoke.py adds test_spec_version_matches_pyproject:
  reads pyproject.toml's [tool.openarmature].spec_version and
  asserts it equals openarmature.__spec_version__. AGENTS.md
  flags these as required to stay in sync; the previous smoke
  test only checked internal consistency between __spec_version__
  and its asserted value, so the pyproject side could drift
  silently (and did, in the original submodule-bump commit).

Author: chris-colinsky

docs/concepts/llms.md

@@ -163,22 +163,38 @@ inspect which path is active.
 ### Strict mode
 
 OpenAI's native path supports a `strict: true` flag that engages the
-model's schema-constrained decoding (the model literally cannot emit
-non-conforming tokens). It applies only when the schema satisfies
-specific constraints: `additionalProperties` explicitly `false` on every
-object, every key in `properties` listed in `required`, no
-unresolvable `$ref` targets.
-
-`strict_mode_supported(schema)` performs the deep recursive check. The
-provider passes `strict: true` to the wire when the schema satisfies
-it, and `strict: false` otherwise. Either way, the provider validates
-the response post-receive against the supplied schema. Strict is a
+model's schema-constrained decoding: the model literally cannot emit
+non-conforming tokens. The framework decides `strict: true` vs
+`strict: false` automatically based on whether your schema satisfies
+strict-mode constraints. Either way, the framework validates the
+response post-receive against the supplied schema; strict is a
 wire-level optimization, not a correctness requirement.
 
-If you control the schema, prefer making it strict-compatible:
-explicit `additionalProperties: false` plus `required` covering every
-property. Pydantic-derived schemas may need a tweak to satisfy this
-(`model_config = ConfigDict(extra="forbid")` on the class).
+`strict_mode_supported(schema)` (exported from `openarmature.llm`)
+performs the deep recursive check. The heuristic is conservative —
+anything not on the list below trips to `strict: false`:
+
+- Top-level schema is `type: "object"`.
+- For every nested object: `additionalProperties` is **explicitly**
+  `false`, and every key in `properties` is listed in `required`.
+- For every nested array: `items` is present and points to a
+  verifiable schema (dict, or tuple-form list of dicts).
+- Every branch of `anyOf` / `oneOf` / `allOf` independently satisfies
+  the above.
+- Internal `$ref` targets (`#/...` or bare `#`) resolve and their
+  resolved schema passes. External refs (any other URI) and `$ref`
+  cycles are handled conservatively.
+- Primitive types (`string`, `integer`, `number`, `boolean`, `null`)
+  are accepted as terminal: no nested structure to verify.
+- Empty `{}` schemas and unrecognized-keyword schemas (`const`-only,
+  `enum`-only, etc.) trip to non-strict; the walker can't statically
+  verify them.
+
+If you control the schema and want strict mode, the easiest path is to
+set `additionalProperties: false` and put every property in `required`
+on every object. Pydantic-derived schemas may need `model_config =
+ConfigDict(extra="forbid")` on the class to get the
+`additionalProperties: false` in the generated JSON Schema.
 
 ## Routing on parsed fields
 

docs/model-providers/index.md

@@ -153,14 +153,14 @@ inspect which path is active.
 ### Strict mode
 
 OpenAI's native path supports a `strict: true` flag that engages
-schema-constrained decoding. It applies only when the schema satisfies
-specific constraints: `additionalProperties` explicitly `false` on
-every object, every key in `properties` listed in `required`, no
-unresolvable `$ref` targets. `strict_mode_supported(schema)` (exported
-from `openarmature.llm`) performs the deep recursive check; the
-provider passes `strict: true` to the wire when the schema satisfies
-it, and `strict: false` otherwise. Either way, the provider validates
-the response post-receive.
+schema-constrained decoding. The provider passes `strict: true` when
+the schema satisfies the strict-mode constraints and `strict: false`
+otherwise; the full constraint list lives on the
+[LLMs concepts page](../concepts/llms.md#strict-mode).
+`strict_mode_supported(schema)` is exported from `openarmature.llm`
+for callers wanting to check the heuristic directly. Either way, the
+provider validates the response post-receive against the supplied
+schema.
 
 ## A minimal example
 

tests/test_smoke.py

@@ -1,6 +1,22 @@
+import tomllib
+from pathlib import Path
+
 import openarmature
 
 
 def test_package_versions() -> None:
     assert openarmature.__version__ == "0.5.0"
     assert openarmature.__spec_version__ == "0.15.0"
+
+
+def test_spec_version_matches_pyproject() -> None:
+    # AGENTS.md flags __spec_version__, pyproject.toml's
+    # [tool.openarmature].spec_version, and the submodule pin as
+    # required to stay in sync. The test_package_versions check above
+    # only verifies internal consistency between __spec_version__ and
+    # its asserted value, so the pyproject side can drift undetected.
+    # This test catches that class of three-place drift.
+    pyproject_path = Path(__file__).resolve().parent.parent / "pyproject.toml"
+    config = tomllib.loads(pyproject_path.read_text())
+    pyproject_spec_version = config["tool"]["openarmature"]["spec_version"]
+    assert openarmature.__spec_version__ == pyproject_spec_version