Skip to main content

ADR 0011 — True Harm Placeholder Material Naming Convention

Context​

The True Harm rule is committed at universe-design scope in ../universe/ud-world-law.md. That doc commits three category terms as hard canon — divine-touched, ritually-prepared, and runic-worked — and explicitly defers the specific materials within each category to "Wave M scope for Game 1" so the player excavates rune-craft, ritual knowledge, and divine-touched implements through discovery rather than receiving a published list. The rune-crafting-true-harm Quest Thread (one of the seven cross-act lanes committed in ./ad-0006-dynamic-quest-pressure-and-cross-act-lane-decisions.md) runs the full saga and depends on material-discovery beats across Acts 1 through 7. The lore-tree deferred-terms list in .claude/rules/lore-conventions.md names "specific True Harm materials" as a deferred-term class with explicit PROPOSED TERM: discipline.

The Foundation Hardening touches the rune-crafting-true-harm lane at four structural points: the Wave 3a Quest Thread / Mission state-machine row authoring; the urgency-signal binding wave that binds runtime urgency channels to lane progress; the Journal-readback hook wave that surfaces the lane's current Mission and accumulated clues to the player; and the Quest Thread index / cross-act binding plumbing wave. None of those Foundation Hardening waves are authorized to name specific True Harm materials — that authorization belongs to the deferred Wave M content track. But all four waves need to reference the material slot in the state machine, in the urgency binding, in the Journal hook, and in the index plumbing.

Without a committed placeholder convention, each agent dispatched for those four waves would invent its own placeholder form, producing parallel marker shapes the verifier cannot detect and a high risk of silent canon invention. The deferred-terms list in .claude/rules/lore-conventions.md is explicit that committed names must not be invented; the existing PROPOSED TERM: marker form is attested for [continent name], [fallen capital name], and similar deferred proper nouns. A typed-id placeholder form for runtime / contract-shape sketches is attested in workspace docs as <TBD:Foo>; curly braces are not attested as a marker form and must not be introduced.

Decision​

Foundation Hardening waves may touch the rune-crafting-true-harm Quest Thread lane for structural / state-machine / urgency-binding / Journal-readback / index-plumbing work only. Specific True Harm material names remain deferred and are represented by a typed placeholder convention with three forms, each scoped to the surface where the placeholder appears:

Prose / quest-thread / state-machine doc bodies. Use [specific True Harm material] exactly, matching the existing [fallen capital name] and [continent name] PROPOSED TERM bracket form attested in the lore tree. Example: "The mission resolves when the player presents [specific True Harm material] at the Wardheart's altar." The bracket form makes the deferred slot visible to the reader and to the verifier without inventing a name.

Header-line declarations or YAML-style placeholder ids. Use PROPOSED TERM: [specific True Harm material] exactly, matching the existing PROPOSED TERM: marker discipline. Example header line: material_slot: PROPOSED TERM: [specific True Harm material]. The explicit PROPOSED TERM: prefix flags the slot to the validator without requiring a committed name.

Typed-id-style placeholders for runtime / contract-shape sketches. Use <TBD:TrueHarmMaterialId> exactly, matching the attested angle-bracket TBD marker form used elsewhere in the workspace for deferred typed ids. Example: "The state-machine row carries a <TBD:TrueHarmMaterialId> field that resolves to the discovered material when Wave M content fills the slot." Curly-brace marker forms (e.g., {TrueHarmMaterialId}) are not attested and MUST NOT be introduced.

Every placeholder occurrence MUST be paired with an inline HTML comment (or equivalent marker for non-Markdown surfaces) of the form:

<!-- TODO(lore-owner): name deferred per .claude/rules/lore-conventions.md § Deferred terms -->

The TODO comment makes the deferral machine-detectable to the verifier and links to the authoritative rule. Foundation Hardening waves that omit the TODO comment when authoring a placeholder are a verifier FAIL.

In-scope work for the rune-crafting-true-harm lane during Foundation Hardening:

  • The Wave 3a state-machine row authoring (per ./ad-0007-quest-thread-and-mission-scope-primitives.md).
  • The urgency-signal binding wave that binds the lane's current urgency to runtime channels.
  • The Journal-readback hook wave that surfaces the lane's current Mission and accumulated clues.
  • The Quest Thread index / cross-act binding plumbing wave that wires the lane into the Quest Thread index and the cross-act lane index.

Out-of-scope work for the rune-crafting-true-harm lane during Foundation Hardening:

  • Per-act mission ladders authoring specific material-discovery beats. Those belong to Wave M.
  • Specific material instances (any named material under divine-touched, ritually-prepared, or runic-worked). Those belong to Wave M.
  • Promoting the cosmological framing of True Harm to revealed in ../hooks/lh-game1-world-hooks.md. The Game 1 reveal-tier ceiling rule in .claude/rules/lore-conventions.md caps cosmological facts at hinted in Game 1; True Harm cosmology is one of those facts.

Alternatives Considered​

Defer the rune-crafting-true-harm lane entirely from Foundation Hardening. Rejected because the lane is structurally referenced by all seven act docs as one of the seven committed cross-act lanes per ./ad-0006, and deferring the lane leaves the Wave 3a state-machine row surface incomplete (six lanes plus one missing lane is exactly the partial artifact-class drift the contract-backing rule forbids).

Halt Foundation Hardening for user input on whether to defer the lane. Rejected because the resolver protocol forbids halt-for-user when the resolver can decide (per .claude/rules/orchestrator-mode.md § Resolver dispatch). The resolver authority covers placeholder convention selection, and the three-form convention committed here is the resolver's decision.

Invent a committed material name to unblock the four Foundation Hardening waves. Rejected because .claude/rules/lore-conventions.md is explicit that "specific True Harm materials" is a deferred-term class and committed names must not be invented. Doing so would also violate the "No invented lore" forbidden-patterns clause for this wave.

Tenets Applied​

  • "No backwards compatibility." No legacy un-bracketed placeholder form is preserved; the three committed marker forms are the only legitimate placeholders.
  • "Future-proofed solutions only." A typed-id placeholder form (<TBD:TrueHarmMaterialId>) lets later Wave M content fill the slot by a single search-and-replace across runtime / contract sketches without requiring a re-author pass.
  • "No hacks, no shortcuts, no workarounds." Inventing a placeholder material name to unblock Foundation Hardening would be exactly the shortcut the tenets forbid; the placeholder convention preserves the deferral cleanly.
  • "AAA = COMPLETE correct algorithm." The analog AAA precedent (RimWorld biome-specific resource families named in code but filled in by writer catalogs; Path of Exile unique item slot ids filled by the writer team; AAA games gating art / lore reveals behind named typed slots filled by writer-led waves) commits to a typed-id slot layer separate from the writer's name catalog; this ADR commits Valenar to the same complete shape.

Runtime Backing Status​

Status at this ADR's acceptance time: contract-only (placeholder convention is an authoring policy; it does not itself have a runtime backing layer to close).

  • Host/runtime owner: not applicable — the placeholder convention is authoring policy, not a runtime entity. Material-slot runtime backing is owned by the deferred Wave M content track.
  • Generated/.secs owner: not applicable for the convention itself; Foundation Hardening waves that use the <TBD:TrueHarmMaterialId> form in runtime / contract sketches document that the typed id will resolve when Wave M lands.
  • Read-model/UI owner: not applicable — placeholder marker forms do not surface to the player; player-facing Journal entries that need to reference the deferred material must use the prose marker form with the inline TODO comment and must not surface the bracket text to the player UI.
  • Tests: any structural validator that walks the lore tree for PROPOSED TERM: markers continues to recognize the existing form; the typed-id <TBD:TrueHarmMaterialId> form is added to the recognized deferral surface during the Wave 5a runtime-backing wave's validator pass.
  • Known gaps: the specific True Harm materials themselves (Wave M scope); the binding rule between the typed-id placeholder and the Wave M material catalog when it lands.
  • Illegal fallback behavior: curly-brace placeholder forms, un-bracketed prose names, parenthetical "(name TBD)" forms, and TODO comments without the lore-owner attribution and rule citation are all explicitly forbidden and produce a verifier FAIL.
  • Next closure wave: the rune-crafting-true-harm lane's specific material catalog is closed by the deferred Wave M content track, not by Foundation Hardening.

Glossary Propagation​

The following terms MUST land in gd-glossary.md, gd-canon.md, and README.md:

  • TrueHarmMaterialId (typed-id placeholder used in runtime / contract sketches; resolves to a specific material when Wave M lands).
  • The three True Harm category terms (divine-touched, ritually-prepared, runic-worked) are already committed as hard canon at universe-design scope in ../universe/ud-world-law.md and must be present in gd-glossary.md as cross-references to that authority rather than as duplicate definitions.

No specific material names are added to the glossary by this ADR; specific names are deferred to Wave M.

Consequences​

For Foundation Hardening waves that touch the rune-crafting-true-harm lane (Wave 3a state-machine row, urgency-signal binding wave, Journal-readback hook wave, Quest Thread index / cross-act binding plumbing wave), the placeholder convention is binding. Every reference to a specific True Harm material must use one of the three committed marker forms with the matching TODO comment.

For Wave M (the deferred content track that will author specific True Harm materials for Game 1), the typed-id placeholder gives a clean search-and-replace target for promoting <TBD:TrueHarmMaterialId> to a committed typed id. The prose bracket forms are replaced by the committed material name when Wave M authors a specific instance.

For the verifier, the placeholder convention provides a machine-detectable deferral surface. Any new committed name for a specific True Harm material in a Foundation Hardening wave is a tenet FAIL (the no-invented-lore forbidden-patterns clause). Any un-bracketed deferral, curly-brace marker, or TODO comment without the lore-owner attribution and rule citation is also a FAIL.

For the existing universe-design authority at ../universe/ud-world-law.md, nothing changes. The three category terms remain hard canon; the specific materials remain deferred to Wave M scope. This ADR is the game-design layer's placeholder-handling convention; it does not amend the universe-design authority.

References​