Skip to main content

Valenar Contract Backing And Propagation Gate

Docs waves that add or change contracts, adjudicator terms, state machines, generated/read-model expectations, or runtime-facing design promises are incomplete unless every backing and propagation obligation is met before the wave closes. Silent fallbacks and unregistered deferrals are a tenet violation: "No hacks, no shortcuts, no workarounds" and "Future-proofed solutions only" apply to documentation contracts as strictly as they apply to code. Repeated partial-propagation audits that find the same missing glossary entries, missing runtime-backing records, or unregistered deferrals across multiple waves signal an architectural process failure, not a missing parameter — the process must be fixed, not patched. This rule formalizes the gate so that Validate/Verify agents have a machine-readable checklist and implementers have a complete propagation surface at acceptance time.

Contract Backing And Propagation Gate​

When a Valenar or SECS wave adds or changes a contract doc, adjudicator term, state machine, generated/read-model expectation, or runtime-facing design promise, the wave must complete the backing/propagation gate before acceptance:

  1. Add a runtime-backing status block: implemented, partial, stubbed, contract-only, or deferred, with host/runtime owner, source/generated owner, read-model/UI owner, tests, known gaps, illegal fallback behavior, and next closure wave.
  2. Propagate every new adjudicator/runtime term to the canonical glossary and README/index/navigation surfaces, or explicitly record why the term is not canonical.
  3. Add roadmap/open-question/code-sync entries for every deferred runtime, generated, source, or UI dependency.
  4. Replace silent fallbacks with explicit errors, explicit unimplemented states, startup validation, or explicit contract-only/deferred status.
  5. If the contract depends on a state transition or primitive that does not exist, do not implement from guesses; route to a transition/primitives wave or resolver decision.
  6. Conditional artifact-coverage rows are not permission to skip canonical propagation. If a wave's explorer misses a canonical companion update, verifier must fail the wave.

A wave that introduces a contract but leaves its glossary/index/runtime-backing/deferral surface ambiguous is incomplete even if the new doc itself is internally coherent.

Status Vocabulary Role Split​

Two vocabulary sets coexist in Valenar docs. They serve different audiences and must not be conflated.

Per-doc prose status block (defined in docs-site/content/valenar/implementation/pr-status-and-sync-policy.md): the short prose block immediately under a doc's H1. It uses the four terms Current, Prototype, Target, and Drift to answer "what is running, what is the target, is there gap?" for human readers navigating the doc tree. This block is for readers; it summarizes implementation reality in one glance.

Wave-acceptance structured runtime-backing record (defined in this rule, gate item 1 above): a structured record produced at wave acceptance time. It uses the five terms implemented, partial, stubbed, contract-only, and deferred to specify, for each surface owner (host/runtime, source/generated, read-model/UI, tests), the current backing state, known gaps, illegal fallback behavior, and the wave responsible for closure. This record is for agents and orchestrators; it is the machine-readable gate that prevents silent deferrals from becoming permanent drift.

The two systems answer different questions and carry different schemas. Do not merge them or replace one with the other. A doc may carry both: the prose status block at the top for readers, and the structured backing record in a wave-acceptance section for process tracking. Cross-reference: the prose status vocabulary is the normative reference at docs-site/content/valenar/implementation/pr-status-and-sync-policy.md; the wave-acceptance record schema is governed here.

Canonical Glossary Targets​

When a new adjudicator or runtime term is introduced by a wave, it must be propagated to the correct canonical surfaces. The split is by domain:

Valenar-side new term:

  • Live terms: docs-site/content/valenar/gd-glossary.md
  • Canonical naming record: docs-site/content/valenar/gd-canon.md
  • Index/navigation surface: docs-site/content/valenar/README.md

Valenar docs now live directly under docs-site/content/valenar/**; update those canonical surfaces in the same wave as the new term.

SECS-engine-side new term:

  • Canonical concept vocabulary: docs/design/00-overview.md
  • Behavior-layer vocabulary subset: .claude/rules/behavior-vocabulary.md (for activity, policy, on_action and related terms)
  • Core concept vocabulary subset: .claude/rules/secs-concepts.md (for the seven core concepts and the resolution pipeline)

If the new term touches both sides (a SECS runtime concept that Valenar surfaces as a player-facing or designer-facing noun), propagate to both. Record the propagation decision explicitly — do not silently omit a side because it seems less important.

Cross-References​

  • No-fallback redesign propagation clause: .claude/rules/orchestrator-mode.md § Source freshness and no-fallback redesign propagation
  • Per-doc prose status vocabulary: docs-site/content/valenar/implementation/pr-status-and-sync-policy.md
  • Wave template and working rules: docs-site/content/valenar/implementation/pr-wave-template.md
  • Authoritative drift tracker: docs-site/content/valenar/implementation/pr-code-sync-audit.md

Examples Of What This Catches​

  • Verifier FAIL trigger (gate item 6): A wave introduces a new LocationKnowledgeState adjudicator term and adds it to the design doc, but the explorer does not include gd-glossary.md in the affected-files list. The verifier reads gate item 6, finds the term absent from gd-glossary.md, and fails the wave. Inline "it was obvious" reasoning is not acceptance; verifier FAIL routes back to implementer.

  • Missing glossary entry (gate item 2): A wave adds a new state-machine stage Reclaimed as a runtime backing state. The doc is internally coherent. But gd-glossary.md has no entry for Reclaimed and gd-canon.md has no canonical naming record. Gate item 2 is unsatisfied; the wave is incomplete.

  • Absent runtime-backing status (gate item 1): A wave ships a new adjudicator contract specifying how SettlementTier resolves. The doc describes the algorithm clearly. But no structured backing record identifies the host/runtime owner, the generated owner, or what happens at runtime before the backing exists. Gate item 1 is unsatisfied; contract-only must be recorded explicitly with the next closure wave named.