Skip to content

Commit ef0e7f9

Browse files
dmealingclaude
andcommitted
fix(docs): the retirement guide's own notes examples do not load
Both "where the record goes" snippets in verified-by-retirement.md write `"notes"` BARE. Canonical JSON reserves exactly eight structural keys (name/package/extends/abstract/ overlay/isArray/children/value); everything else is an inline attribute and must carry the sigil. So the loader rejects it: Unknown key 'notes' on requirement.functional 'BeatProgression' — must be reserved or @-prefixed Verified against a real strict load: bare `notes` errors, `@notes` loads and reads back. This is the worst possible place for it. Those two snippets ARE the answer FR-038 gives to the one objection adopters actually raise — "deleting the node destroys the history" — and the answer is "put it in notes, here is how". An adopter who follows the example literally gets a load failure while doing the migration the guide told them to do, which reads as the retirement being half-baked rather than as a typo in a sample. Found by testing the example rather than reading it, after being asked where notes had gone. The two other bare-`notes` hits in the tree are tool config (conformance-expected-failures.json), not metadata, and are correct as written. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
1 parent eae94b3 commit ef0e7f9

1 file changed

Lines changed: 2 additions & 2 deletions

File tree

‎docs/features/migrations/verified-by-retirement.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -68,7 +68,7 @@ history, and history is not what a requirement is for.
6868
"name": "BeatProgression", "@level": 4, "@status": "live",
6969
"@statement": "A scene advances when its beat completes",
7070
"@violation": "A scene that advances with its beat unresolved",
71-
"notes": "Replaced the per-turn wall-clock timer retired in 2026-06; do not reintroduce clock-driven pacing — it advanced scenes with beats unresolved.",
71+
"@notes": "Replaced the per-turn wall-clock timer retired in 2026-06; do not reintroduce clock-driven pacing — it advanced scenes with beats unresolved.",
7272
"@implementedBy": ["game::turn::BeatProgression"]
7373
}}
7474
```
@@ -92,7 +92,7 @@ parent is the carrier:
9292
"name": "Narration", "@level": 3, "@status": "live",
9393
"@statement": "The narrator describes outcomes the player can act on",
9494
"@violation": "Narration a player cannot act on",
95-
"notes": "The `sceneRecap` prompt under this requirement was retired 2026-06 and left no artifact behind — its template was deleted with it. Do not reintroduce a recap turn: it restated state the player already had and consumed a third of the budget.",
95+
"@notes": "The `sceneRecap` prompt under this requirement was retired 2026-06 and left no artifact behind — its template was deleted with it. Do not reintroduce a recap turn: it restated state the player already had and consumed a third of the budget.",
9696
"children": [ /* the surviving child requirements */ ]
9797
}}
9898
```

0 commit comments

Comments
 (0)