docs: the twelve questions the specification does not answer, and code does

MANIFEST.sha256

@@ -45,14 +45,14 @@
 1fb7dd2afe2b230d7c335db5c5da4e72e0ad271ce2dcd1683f446945e0abb917  conformance/materialization/011_discriminator_envelope/input.yaml
 2020cd3da7008987b81055f0ef1bc7481567202da7f8bf49d616b1018f52bc21  mk/infra.mk
 2063bf8ac333858a9b5c96de552fc4879ca3c35e5d0e34b0dd4067cec94bb5da  Dockerfile
+214885986c75f2a6928c9e2a8326804353310ade3834815c5d64f3e74634ddbf  project.yaml
 21a2f539315cb8500c9d812776d0e777b2eca73d668b3079b694b651fe8539d8  conformance/materialization/012_discriminator_payload_keywords/input.yaml
 21a9994fa283ffca9aa0d063526ba4bc8b7d53d781bfbbee0d0041dcc04d143a  conformance/invalid/005_origin_in_authoring_input/schema.yaml
 21a9994fa283ffca9aa0d063526ba4bc8b7d53d781bfbbee0d0041dcc04d143a  conformance/invalid/006_unknown_primitive/schema.yaml
 21a9994fa283ffca9aa0d063526ba4bc8b7d53d781bfbbee0d0041dcc04d143a  conformance/invalid/008_duplicate_mapping_key/schema.yaml
 225e266950c6f85bfd2be20cacb3de0ac011414f92010b831136640ffe9a46be  conformance/invalid/007_sealed_missing_path/expected-error.yaml
 229376bac93d6b5d81c8c3015b4981999cf3a3c82bf8a8e1d63eecaf61d1e35d  conformance/validation/007_origin_duplicate_term/expected-error.yaml
 24219339b219898ecb69d09495bc078745cef2c1b5065eedfff886dd95032881  conformance/invalid/010_required_value_missing/expected-error.yaml
-25330918bb1de80bf3db79532e39dd87e2752df46e402434c0044de476046f86  README.md
 2758d20cf5aa0688060bce28a52786eee272986714a8376d7f190eb2dc90a43e  reviews/README.md
 275acc4de6f4d5fcd87330039777ceb8f8d8a7933c4e4924eccabe21a9f28da2  conformance/materialization/002_origin_schema/meta.yaml
 27fc384a0d7987e4cb311648408b9b5a3995c0b58871ed55389ae154061209c9  conformance/validation/011_more_than_one_document/object.yaml
@@ -155,6 +155,7 @@
 72c48fa014dea46236640cf52037631aa5db63a6f58807b3bf24577a247aa238  tools/check_doc_links.yaml
 72e9b7c69632c1e1877e9f9d69812f3259003989b69f6b0fa7f23612d4514c94  tools/releaselib/git_service.yaml
 7426752feb1140b2023192728df35248e4f802617c150bb0523ab97dc1638c0b  tools/init-hooks.sh
+753f2eb2a6b70c2e35e76b61baa67b9f9533f8f86713da7b9ff62ab44def6ccb  docs/pending-decisions.md
 75b59a6cf6a2ce8af4fd04c8a0dcf7d33e5e5f132a48a981252ce61c05cf97c9  docs/hu/makefile-cheatsheet.md
 75d086d878abe5943b2dd0c080c0ffb4fd88b517289c216ffa6bc5c1f12056f7  conformance/invalid/003_closure_undeclared/input.yaml
 764d101d6bb896af8c4f082768f30f9f7cf77a6f0a0fed940b7b39805330d842  requirements.txt
@@ -211,6 +212,7 @@
 94dabea4d0bdb7a81c750c4b2830f096c9ee2e59952fd1b9f7d4e235cddeb2f9  mk/golang.mk
 96a0612d7f3d7d3faf96bbc408da0b32979eaee2599962e8d6d9e97c15b38d40  conformance/materialization/015_nested_sealed_template/schema.yaml
 992423396d17250586acefe1ca589c21d650fb75c7f578bdff9cbb42fa1351fa  conformance/invalid/012_scalar_position_sequence_payload/expected-error.yaml
+998c8f3ef914d9447a6f565be986c0c8d3459b55b6a131290609d912b709e542  SPEC.md
 9c11fd643268e578437b015dc5a4ea6e5a3f290f0303ac04ea4d429768208617  tools/schemalib/__init__.py
 9c2c853fb20be48e4ebbfdf70a98e6890df116fd77fd85a6be2b010674afcaab  go/conformance/conformance_test.go
 9d0d594b86072a88bbda400992cb62d0b4faf71176a76c8f30c2e632c8eb5fb1  conformance/validation/011_more_than_one_document/meta.yaml
@@ -238,6 +240,7 @@ aad20e1630b166e5ca74baad558d0f47cc9be1d6b6aea22c23deebeaa75447fc  conformance/ma
 ac2343c803409938f2414e5833bab1ae33061506fe2678307121837036e3ada2  conformance/invalid/003_closure_undeclared/schema.yaml
 af1074d4241e3ac01c7b4197ffcef9e270dbde4c4ddccd7b1d6c0aab4a75cbb0  docs/hu/architecture.md
 af6cd3c7db5089246c1c7533fb2763351d03dab7c26424a8827e347fdaee618e  tools/schemalib/artifact.yaml
+b1f4c81b89b74764e424b6f963615944c64b5c11d3e61ef8027334836a51b18d  README.md
 b24ec80c06a16f685f69c69a2b2d266b823e45d0153868b10967df484d9eafee  conformance/invalid/010_required_value_missing/meta.yaml
 b35767f17012df3e8334e7414d1d535c60a3a6e83c7a3038e6c8ea4915c48bdb  conformance/validation/002_origin_empty/object.yaml
 b3d0d0dd71c294b5fa8bad4fcdd9784feae35141aeb71e1755abd8bbd0cfca58  pyproject.toml
@@ -273,7 +276,6 @@ c874c3372e425b2255c6eb1771e13f77fe6025923d06ced7b5a91259e28e1d22  go/objectmodel
 c8daecc8e4b81241d10c642c6c051712022bb8950a7855fd31d7805534de9586  conformance/materialization/006_closure_opaque/expected.yaml
 cadf923c73fdea6b9e1478f822f30d3f4d6c7463b15a12df709f0ae5d56743a2  conformance/validation/007_origin_duplicate_term/meta.yaml
 cc2109e262ef7d2c0ae924af62ae6b794934a37c9be09e35f1a175b22faa2483  go/objectmodel/construct.go
-cc22d2735173aaf85a9944852f4522df726185bd7f8b023085fd7d0c5d7fe6d4  project.yaml
 cc94b0652d20afaf3b85ee72e50913f0277b6441642309670818355847f1e721  spec/node.schema.yaml
 ccc12224c9262ebed8b7bedb3046e9a359fa817e9c08659765d62d63355d0e3a  conformance/materialization/014_hostile_keys/input.yaml
 cdc268dd275143f3cbad6b84078f397367c40951812143d227b5490cd007ce82  tools/infra.py
@@ -334,7 +336,6 @@ fa3d02b5fc0677eb715d676e88b98b94016a76eb13e47abfa1040d0e6f12719f  docs/rust-gate
 fa8afcf490e0b9b1e3ce94789f3233ed73289553ec94f16d2c347afd5e08b367  conformance/invalid/002_sealed_yaml_schema_conflict/input.yaml
 fab14c32130c2345945fa55f41e6614bc443815733249fce81ed7d97e1d1f4cf  rust/src/value.rs
 fd4ba258680da20f4084db2696fa942c09e47de8ec4650104f2b2e18c53980bc  go/module/adversarial_test.go
-fdd8b8d94d94d9c08aafdc2b0e6f85db5deba627541786a8d72ef99c3eb37049  SPEC.md
 ff005c27b6c185b065c2121b01fa6f71c9668af920483714c9b137e411cec32c  go/objectmodel/emit_test.go
 ff5d544dc1e253e76844a7c325f7f73d952ac29b284092f0ed2e80b8de3ae0a2  go/objectmodel/materialize.go
 ffa488df0e6ea07872d7c2b8a7ed0b692e4a998711991e4471cfc134fcbaf0b6  go/objectmodel/api_test.go

README.md

@@ -20,7 +20,7 @@ written into SPEC.md and propagated nowhere else.
 | `SPEC.md` — 46 numbered invariants | written, normative |
 | `conformance/` — 38 vectors | executed against Go on every CI run |
 | `docs/spec-vector-map.md` | 37 invariants vector-covered, 5 declared unvectorizable with a reason each |
-| `tools/check_spec_vectors.py` | runs and passes; negative-tested |
+| `tools/check_spec_vectors.py` | runs and passes; checks the invariant index, not RFC-2119 clauses |
 | `go/` | implemented — corpus, fuzz, mutation, adversarial and CLI golden tests |
 | `rust/` | implemented — corpus, reader, rejection and CLI golden tests |
 | `mk/rust.mk` | present; digest-pinned toolchain, `make rust.quality` |
@@ -74,6 +74,7 @@ conformance/                the falsifiable part — YAML in, YAML out
   validation/                 canonical object -> accept / reject
 docs/
   spec-vector-map.md          every invariant -> its vectors, or why it has none
+  pending-decisions.md        questions the spec does not answer and code does
   decision-delta.md           what this model changes in D-003 / D-011
   migration-surface.md        the measured file list this model would change
   branch-decision.md          why base-repo wasm/main

SPEC.md

@@ -1205,6 +1205,10 @@ The procedure, and the three commissioning prompts a request carries, are in
 
 ## 13. Related documents
 
+- [`docs/pending-decisions.md`](docs/pending-decisions.md) — questions this
+  document does not answer, which an implementation has answered anyway. Twelve
+  of them, three answered differently in the two implementations. Read this
+  before adding a rule: several of these are load-bearing and unwritten.
 - [`docs/spec-defects.md`](docs/spec-defects.md) — where this document is not
   executable, measured by implementing it. **Read SD-017 before relying on
   INV-033.**