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 LocationData is a current prototype form of the Location knowledge axis — it is live and exercised, but the design target is the multi-rung knowledge ladder documented in gd-location-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-location-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-location-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.

  • pr-code-sync-audit.md - the authoritative drift tracker between docs and committed Content/Generated/Host/Server/Client/ src/tests artifacts.
  • pr-open-questions.md - questions surfaced by waves that are awaiting user decision or ADR.
  • pr-docs-codegen-rules.md - how docs should describe Content, Generated, and future compiler lowering.