Skip to main content

Status and Sync Policy

Status: governance reference — defines the vocabulary used in per-doc status blocks across the Valenar docs tree. This doc itself has no drift because it is definitional.

Purpose​

This document defines the four status terms used in status blocks at the top of authoritative Valenar docs, and defines what "drift" means between doc status and runtime state. Every new Valenar doc that describes a system with a current implementation must carry a status block using this vocabulary. Readers learn from a single page how to read a Status: block; doc authors gain a fixed set of words that make implementation reality legible without silently reconciling design with code.

Status Vocabulary​

Current​

Current describes what the running Valenar prototype does today, as seen in Host/, Generated/, Server/, and Content/. A current claim is verifiable by reading the code: a reader who follows the status block to the named file, line, or system can confirm the behavior is implemented and exercised by the runtime. current is the only status that asserts working behavior in the live build.

Prototype​

Prototype describes a stepping-in implementation that satisfies the shape (types, APIs, wire format, on-disk layout) but not the final design intent. A system marked current prototype is running, but its implementation is known to be replaced by a future wave. The committed int Explored field on TerritoryData is a current prototype form of the Territory knowledge axis — it is live and exercised, but the design target is the multi-rung knowledge ladder documented in gd-territory-generation-contract.md. prototype MUST be paired with the current qualifier when the prototype is in the live build.

Target​

Target describes what the design doc specifies as the correct end-state behavior. Target behavior may not yet be implemented. The gd-territory-generation-contract.md ladder (Unknown -> Sighted -> Scouted -> Surveyed -> Secured -> Claimed -> Cleansed -> Developed) is a target; int Explored is the current prototype. A status block that names a target without naming the current prototype hides drift; both must be present when they differ.

Drift​

Drift is a documented divergence between current and target, where the current implementation does not satisfy the target design. Drift must be named explicitly in the status block rather than silently reconciled. The pr-code-sync-audit.md is the authoritative drift tracker; per-doc status blocks summarize, the audit doc enumerates.

Per-Doc Status Block Format​

Every authoritative Valenar doc describing a system with a current implementation carries a status block immediately under the H1. The block answers, in prose:

  1. What is the current state? (running runtime, prototype runtime, or doc-only specification with no runtime yet)
  2. What is the target state, if it differs from current?
  3. Is there drift? Where is the drift recorded?

Existing status blocks in gd-feature-generation-contract.md and gd-territory-generation-contract.md are the reference shape. The format is:

Status: <current-state-description>. <target-state-description if different from current>. <drift-statement if applicable>.

The status block is short prose, not a structured table. It is the only prose summary of implementation reality in a doc; deeper drift detail belongs in pr-code-sync-audit.md, and unanswered questions belong in pr-open-questions.md.

What Does Not Belong In A Status Block​

Implementation notes, wave attribution, changelog entries, and version history do not belong in the status block. The status block answers "what is true now and what is the target?" The pr-code-sync-audit.md answers "what changed in which wave?" Cross-link conventions, deprecation notices, and rewriter intent live in their own sections of the host doc, not in the status block. The status block must remain compact prose so that a reader can parse current vs target vs drift in one pass.

Wave-Acceptance Runtime-Backing Vocabulary​

The four prose terms above (Current, Prototype, Target, Drift) are the per-doc status block vocabulary aimed at human readers. The Foundation Hardening and every Valenar / SECS contract-adding wave additionally use a structured, wave-acceptance runtime-backing record governed by .claude/rules/valenar-contract-backing.md. That structured record uses five terms, NOT the four prose terms above:

  • implemented — the contract is fully backed: host data, host systems, source / Generated, read-model, and tests all exist and agree.
  • partial — some surface owners exist (e.g., host data file exists) but the full backing is incomplete (e.g., the new channel does not yet exist). Known gaps are enumerated; no surface is left ambiguous.
  • stubbed — a placeholder value lives in code (e.g., => 1.0, a null return, a hardcoded default) that the contract explicitly rejects as a silent fallback. Stubbed surfaces must fail loudly (throw NotImplementedException, log a hard error, reject the operation) until the real backing lands.
  • contract-only — the design / ADR commits the contract but no runtime owner exists yet. The next-closure wave must be named.
  • deferred — the contract surface is intentionally postponed to a later wave or to a deliberate migration prompt, with the reason recorded.

Wave-acceptance term used by Foundation Hardening: <deferred-to-Wave-5a-runtime-backing> is the canonical phrasing for "this contract surface is committed at the doc / ADR level but will not gain runtime backing until the Foundation Hardening Wave 5a source / Generated / lowering wave runs." It is a deferred status in the vocabulary above, with the next-closure wave named explicitly as Wave 5a. The phrasing appears in Foundation Hardening contract docs and in pr-open-questions.md deferred entries.

These two systems answer different questions and carry different schemas. Do not merge them: a doc may carry both the prose status block (for readers) AND the structured runtime-backing record (for process tracking). The prose block stays compact; the structured record carries the host/runtime owner, source/generated owner, read-model/UI owner, tests, known gaps, illegal fallback behavior, and next closure wave.