Conventions & Write-Contract¶

Audience: Every human and every AI agent that writes to this site
Rule of the road: Direction persists, tasks scatter. If an edit doesn't move a roadmap row, question it.

This page is the contract for editing the living roadmap. It is deliberately short. Follow it and the roadmap stays a single, trustworthy source; ignore it and it rots back into a smorgasbord.

1. The marker system (mandatory, used everywhere)¶

Tag every material claim inline with one marker. The markers are the living signal — a monthly job can find every stale 🟡/🔴 and every 🎯 that a return has hit.

Marker	Means	Carries
🟢 Confirmed	Verified fact or booked actual	a source
🟡 Assumption	Believed, not yet validated	a validate-by intent
🔴 Gap	Known unknown / missing data	an owner
🎯 Target	A committed number to hit	horizon + owner

Discipline: never state an assumption as fact. A hypothesis that gets disproven is struck through and marked, not deleted (git keeps the history). A 🔴 that research fills becomes 🟢; a 🎯 a return hits gets checked. Watching markers move is the roadmap working.

2. Single source of truth (SSOT)¶

Every fact lives on exactly one page; everything else links to it. No fact is copy-pasted.
Every KPI is defined once in the Metrics Glossary — roadmaps cite it, never redefine it.
Shared market facts (AZ macro, seasonality, regulatory) live cross-entity once; entity pages link, not re-key.
Found a duplicate or a competing strategy doc? Fold it in and deprecate (banner + archive) — never leave two.

3. Front-matter schema (every page)¶

---
icon: material/...        # nav icon
owner: <seat or person>   # who keeps this page true
entity: <KEY>             # for entity pages (SWTR, SEQ, STE, SWTP, DET, ...)
layer: <0-market|1-charter|2-operating|3-targets|4-actuals|5-mbr|6-ai-ops|loop|enterprise|conventions>
review_cadence: <monthly|quarterly|annual>
last_reviewed: <YYYY-MM-DD>
status: <🟢 canonical | 🟡 draft | 🔴 stub>
---

This lets an agent query the tree and flag anything past its review date.

4. The 7-layer entity template¶

Every entity roadmap has the same shape, so humans and agents always know where a fact belongs:

0 Market & Demand → 1 Charter/Intent (V2MOM) → 2 Operating Model & GTM → 3 Targets (LEAD/LAG, RAG) → 4 Return/Actuals → 5 Report (monthly MBR) → 6 AI Operations

Above them sits the Enterprise north star; every entity target should ladder to a group measure. What goes where:

Work you did	Lands in
Market/marketing research, competitors, pricing, demand triggers, TAM/SAM/SOM, seasonality, SWOT	§0 Market (+ a shared cross-entity Market section, pending consolidation)
Entity intent / obstacles / values	§1 Charter
How it earns + go-to-market + operations	§2 Operating Model
Targets / projections / KPIs you set	§3 Targets
Actuals / results from the books/CRM	§4 Return
Monthly review / what moved / misses	§5 MBR → decision log
AI use-cases / agent context for the entity	§6 AI Ops

5. How decisions change direction¶

Targets and beliefs change only on a logged decision. Write an ADR-style entry in the decision log; it names what changed, why, and which target/belief it edits. Git records who/when. A reversed decision is superseded, not deleted.

6. Deploy¶

Edit markdown → cd D:\claude_www\projects\enterprise && python -m mkdocs build (strict — a broken link fails the build) → IIS serves site_dir behind the CF tunnel at strategy.arizonatruckgroup.com.

This contract is itself under the marker system: 🟢 rules are settled; a 🟡 here is a convention still being trialed.