Future / Deferral Language Audit (Canonical Docs)

Keywords: future wording audit, deferral discipline, planned deferral, north star claim, ambiguous future language, tracker mapping, proposal-only, pending decision

This page is the repo-wide audit record for future/deferred wording in canonical docs. It exists to prevent vague prose from becoming unscheduled work.

Purpose

• Classify future/deferred wording in canonical docs (src/**/*.md, README.md, AGENTS.md)
• Separate acceptable uses (NorthStarVision, narrative examples, legal phrases, etc.) from ambiguous planning language
• Track remediation work (rewrite, overlay mapping, or pending decision)
• Provide a repeatable audit workflow so the problem does not reappear

This page supports the cross-cutting process feature cluster:

• M0.OPS.FUTURE_DEFERRAL_DISCIPLINE_AND_AUDIT (P-Core)

Scope

Strict (canonical) scope

• src/**/*.md
• README.md
• AGENTS.md

Lighter (research) scope

• research/**/*.md
• Research notes may use speculative language, but accepted takeaways must be mapped into the execution overlay if adopted.

Out of scope

• Non-doc code files
• Legal/SPDX fixed phrases unless misused as project commitments
• Historical quotations unless presented as project commitments

Policy Summary (What Is Allowed vs Not)

• The word future is not banned.
• Ambiguous future intent is banned in canonical planning/spec docs.
• Every accepted future-facing commitment in canonical docs must be classified and (if it implies work) placed in the execution overlay.

Accepted classes:

• PlannedDeferral
• NorthStarVision
• VersioningEvolution
• NarrativeExample
• HistoricalQuote
• LegalTechnicalFixedPhrase
• ResearchSpeculation (research docs only)

Forbidden class in canonical docs (after audit rewrite):

• Ambiguous

Classification Model

Status Values (Audit Workflow)

• resolved — rewritten/classified and, if needed, mapped into overlay
• exempt — valid non-planning usage (historical/narrative/legal/etc.)
• needs rewrite — ambiguous wording in canonical docs
• needs tracker placement — wording is specific enough to be accepted work, but overlay mapping is missing
• needs pending decision — commitment depends on unresolved policy/architecture choice and should become Pxxx

Audit Method (Repeatable)

Baseline grep scan (canonical docs)

rg -n "\bfuture\b|\blater\b|\bdefer(?:red)?\b|\beventually\b|\bTBD\b|\bnice-to-have\b" \
  src README.md AGENTS.md --glob '!research/**'

Ambiguity-focused triage scan (canonical docs)

rg -n "future convenience|later maybe|could add later|might add later|\beventually\b|\bnice-to-have\b|\bTBD\b" \
  src README.md AGENTS.md --glob '!research/**'

Notes

• Grep is an inventory tool, not the final classifier.
• eventually, later, and future frequently appear in valid historical or narrative contexts.
• Use line-level classification only where the wording implies project planning intent.

Baseline Inventory (Canonical Docs)

Baseline snapshot

• Inventory count: 292 hits (future/later/deferred/eventually/TBD/nice-to-have)
• Source set: canonical docs (src/**/*.md) + README.md + AGENTS.md
• Purpose: establish remediation scope for M0.OPS.FUTURE_DEFERRAL_DISCIPLINE_AND_AUDIT

This inventory is a moving count. It will change as docs grow and as ambiguous wording is rewritten.

Highest-volume files (baseline triage priority)

Audit Status (Current)

Phase A — Policy lock

• AGENTS.md: resolved (Future / Deferral Language Discipline added)
• src/14-METHODOLOGY.md: resolved (classification + rewrite rules added)
• src/18-PROJECT-TRACKER.md: resolved (audit status + maintenance rules + intake checklist)
• src/tracking/milestone-dependency-map.md: resolved (cluster row + mapping rules + deferred-feature placement examples)
• src/decisions/DECISION-CAPSULE-TEMPLATE.md: resolved (deferral fields + wording rule)

Phase B — Inventory & classification audit

• Baseline inventory: complete (canonical docs)
• Per-hit full classification: in progress (this page seeds the queue and examples)
• Canonical first-pass focus: M0 docs, then M1-M4 docs

Phase C2 — M1-M4 targeted rewrite/classification pass (baseline)

• Status: baseline complete for planning-intent wording; residual hits are classified as exempt/versioning/technical-semantics references and can be audited incrementally
• Resolved in this pass:
  • src/05-FORMATS.md ambiguous nice-to-have and versioning “future” wording rewritten as explicit PlannedDeferral / VersioningEvolution
  • src/06-SECURITY.md cross-engine bounds-hardening line rewritten as explicit PlannedDeferral tied to M7
• src/03-NETCODE.md bridge/alternative-netcode wording tightened to explicit deferred/optional scope with M4 boundary and trust/certification caveats
• src/02-ARCHITECTURE.md example “future” wording tightened in fog/pathfinder/browser mitigation references (architectural headroom remains, ambiguity reduced)
• src/17-PLAYER-FLOW.md D070/D053 later-phase wording tied to explicit M10/M11 phases
• Residual C2 hits (classified, no rewrite needed by default):
  • src/17-PLAYER-FLOW.md setup copy (change later in Settings) -> NarrativeExample / UI copy, not planning commitments
  • src/17-PLAYER-FLOW.md “later Westwood Online/CnCNet” -> HistoricalQuote / historical product chronology
  • src/04-MODDING.md OpenRA tier analysis eventually needs code wording -> NarrativeExample (observational product-analysis statement, not IC roadmap commitment)
  • src/04-MODDING.md “later in load order” -> technical semantics, not planning
  • src/04-MODDING.md “future alternative” Lua VM wording -> VersioningEvolution / architectural headroom (stable API boundary is the point)
  • src/04-MODDING.md pathfinding deferred requests wording -> technical runtime semantics, not planning
  • src/03-NETCODE.md “ticks into the future”, “eventual heartbeat timeout”, “later packets” -> temporal/network mechanics wording, not planning
  • src/02-ARCHITECTURE.md many “future/later” mentions in trait-capability tables/examples and 3D-title chronology -> architectural headroom examples / scope statements, not scheduled commitments
• Still pending in C2 scope: only newly discovered ambiguous planning statements if future edits add them; otherwise C2 can be treated as closed for the current baseline

Planned deferral for the remaining rewrite pass (explicit)

• Deferred to: M0 maintenance work under M0.OPS.FUTURE_DEFERRAL_DISCIPLINE_AND_AUDIT
• Priority: P-Core
• Depends on: tracker overlay (src/18-PROJECT-TRACKER.md), dependency map (src/tracking/milestone-dependency-map.md), this audit page, wording patterns page
• Reason: repo-wide rewrite is cross-cutting and should proceed in prioritized batches instead of ad hoc edits
• Not in current scope: rewriting every one of the 292 baseline hits in a single patch
• Validation trigger: canonical-doc batches (M0, then M1-M4, then M5-M11) audited with ambiguous hits rewritten or reclassified

Phase C3 — M5-M11 targeted rewrite/classification pass (baseline)

• Status: baseline complete for planning-intent wording; residual hits are classified as North Star, versioning evolution, narrative/historical examples, or technical/runtime semantics
• Resolved in this pass (explicit rewrites):
  • src/decisions/09d/D042-behavioral-profiles.md manual AI personality editor “future nice-to-have” -> explicit M10-M11 planned optional deferral with dependencies and out-of-scope boundary
  • src/decisions/09e/D031-observability.md / src/decisions/09e/D034-sqlite.md optional OTEL and PostgreSQL scaling wording -> explicit M7/M11 planned deferrals (P-Scale)
  • src/decisions/09e/D035-creator-attribution.md monetization schema/comments + creator program paid-tier wording -> explicit deferred optional M11+ policy path
  • src/decisions/09f/D016-llm-missions.md generative media video/cutscene wording -> explicit deferred optional M11 path
  • src/decisions/09g/D058-command-console.md RCON and voice-feature deferrals -> explicit M7 / M11 planned deferrals with scope boundaries
  • src/07-CROSS-ENGINE.md cross-engine correction/certification/host-mode wording -> explicit deferred M7+/M11 certification decisions and North Star guardrails
  • src/decisions/09b/D006-pluggable-net.md / src/decisions/09b/D011-cross-engine.md / src/decisions/09b/D055-ranked-matchmaking.md “future/later” netcode/ranking wording -> explicit deferred milestone phrasing
  • src/decisions/09c-modding.md plugin capability wording -> explicit separately approved deferred capability path
  • README.md cross-engine interop and contributor reward wording -> explicit deferred milestone framing (M7+/M11) while preserving marketing readability
• Residual C3 hits (classified, no rewrite needed by default):
  • README.md author biography/history and README navigation prose (later, eventually) -> HistoricalQuote / NarrativeExample
  • src/07-CROSS-ENGINE.md replay drift wording (desync eventually) -> technical behavior (NarrativeExample)
  • src/decisions/09c-modding.md future genres/workshop consumer examples, load-order semantics, migration story examples, reversible UI copy -> NarrativeExample / NorthStarVision / VersioningEvolution
  • src/decisions/09d-gameplay.md architectural-headroom rationale, historical sequencing text, versioning examples, D070 narrative examples -> NarrativeExample / VersioningEvolution / HistoricalQuote
  • src/decisions/09e-community.md UI copy (“Remind me later”), lifecycle semantics, historical platform examples, and maintenance reminders -> NarrativeExample / HistoricalQuote
  • src/decisions/09f-tools.md narrative examples/story chronology, migration/version comments, historical references, and deterministic replay timing descriptions -> NarrativeExample / VersioningEvolution
  • src/decisions/09g-interaction.md competitive-integrity guidance for contributors, historical examples, platform table labels, UI reversibility copy -> NarrativeExample / HistoricalQuote / VersioningEvolution
• Still pending in C3 scope: only newly introduced ambiguous planning statements in future edits, plus individually reclassified edge cases discovered during later doc revisions

Initial Classification Queue (Seed Batch)

This table records concrete examples to anchor the classification rules and prevent repeat ambiguity.

Exempt Patterns (Allowed, Do Not “Fix” Into Planning)

Prioritized Rewrite Batches (Canonical Docs)

Batch C1 — M0 planning docs (first)

• AGENTS.md — policy text complete; maintain as the strict gate
• src/18-PROJECT-TRACKER.md — policy + audit status complete; keep inventory current
• src/tracking/milestone-dependency-map.md — rules + examples complete; keep new clusters mapped
• src/14-METHODOLOGY.md — process rule complete; keep grep snippet current
• src/09-DECISIONS.md — scan for ambiguous deferral wording in summaries/index notes

Batch C2 — M1-M4 milestone-critical docs

• src/02-ARCHITECTURE.md
• src/03-NETCODE.md
• src/04-MODDING.md
• src/05-FORMATS.md
• src/06-SECURITY.md
• src/17-PLAYER-FLOW.md (milestone-critical commitments only)

Batch C3 — M5-M11 canonical docs

• src/decisions/09b-networking.md
• src/decisions/09c-modding.md
• src/decisions/09d-gameplay.md
• src/decisions/09e-community.md
• src/decisions/09f-tools.md
• src/decisions/09g-interaction.md
• src/07-CROSS-ENGINE.md
• README.md (North Star wording review, not feature deletion)

Remediation Workflow (Per Hit)

1. Classify the reference (PlannedDeferral, NorthStarVision, etc.).
2. If PlannedDeferral, ensure wording includes:
   • milestone
   • priority
   • dependency placement (or direct cluster/Dxxx refs)
   • reason
   • out-of-scope boundary
   • validation trigger
3. If accepted work is implied, map it in the execution overlay (18-PROJECT-TRACKER.md and/or tracking/milestone-dependency-map.md) in the same change.
4. If it cannot be placed yet, rewrite as:
   • proposal-only (not scheduled), or
   • Pending Decision (Pxxx)
5. Update this audit page status (resolved, exempt, etc.) for the touched item/batch.

Doc-Process Interface Sketches (Planning APIs)

These are planning-system interfaces for consistent audit records and wording review, not runtime code APIs.

FutureReferenceRecord

#![allow(unused)]
fn main() {
pub enum FutureReferenceClass {
    PlannedDeferral,
    NorthStarVision,
    VersioningEvolution,
    NarrativeExample,
    HistoricalQuote,
    LegalTechnicalFixedPhrase,
    ResearchSpeculation,
    Ambiguous, // forbidden in canonical docs after audit
}

pub struct FutureReferenceRecord {
    pub file: String,
    pub line: u32,
    pub snippet: String,
    pub class: FutureReferenceClass,
    pub canonical_doc: bool,
    pub requires_rewrite: bool,
    pub milestone: Option<String>,   // M0..M11 for PlannedDeferral/NorthStar as applicable
    pub priority: Option<String>,    // P-Core ... P-Optional
    pub dependencies: Vec<String>,   // cluster IDs / Dxxx / Pxxx
    pub reason: Option<String>,
    pub non_goal_boundary: Option<String>,
    pub validation_trigger: Option<String>,
    pub tracker_refs: Vec<String>,
    pub status: String,              // resolved / exempt / needs_rewrite / needs_mapping / needs_P_decision
}
}

DeferralWordingRule

#![allow(unused)]
fn main() {
pub struct DeferralWordingRule {
    pub banned_pattern: String,
    pub replacement_requirements: Vec<String>, // milestone, priority, deps, reason, trigger
    pub examples: Vec<String>,
}
}

NorthStarClaimRecord

#![allow(unused)]
fn main() {
pub struct NorthStarClaimRecord {
    pub claim_id: String,
    pub statement: String,
    pub fairness_or_trust_scope: Option<String>,
    pub milestone_prereqs: Vec<String>,
    pub non_promise_label_required: bool,
    pub canonical_sources: Vec<String>,
}
}

Maintenance Rules (Keep This Page Useful)

1. Update the baseline count only when re-running the same canonical-doc scan (document the command).
2. Do not treat grep hits as automatically wrong; classify before rewriting.
3. Keep M0/M1-M4 batches current before spending time polishing low-risk narrative wording.
4. If a rewrite creates/changes planned work, update the execution overlay in the same change.
5. Use src/tracking/deferral-wording-patterns.md for consistent replacement wording instead of inventing one-off phrasing.

Related Pages

• ../18-PROJECT-TRACKER.md
• milestone-dependency-map.md
• deferral-wording-patterns.md
• ../14-METHODOLOGY.md