Skip to content

Documentation Governance Contract

Purpose: Prevent hallucinated drift, enforce "truth > prose" Authority: This document overrides all other documentation guidance Owner: Repository maintainers Last Verified: 2026-02-01

Core Principle

Documentation must describe reality, not aspirations.

Every factual claim must be provable. If you cannot prove it, do not write it.

Rule 1: No Invented Dates or Commitments

What This Means

  • NO launch dates unless in approved ADR, issue, or PR
  • NO quarterly roadmaps (Q1 2026, Q2 2026, etc.) without ADR approval
  • NO "coming soon" or "planned for" statements without evidence
  • NO announcements or future commitments

Allowed

**Launch Status**: Pending (requires ADR approval)
**Planned Capabilities** (pending ADR approval): [list]
*Timeline requires ADR-0003 approval.*

Not Allowed

**Q2 2026**: We will launch feature X
**Coming soon**: Multi-region support
**Launch Target**: April 2, 2026

Verification

  • Grep for: Q[1-4] 20[2-9][0-9], launch.*202[0-9], coming soon
  • If found without ADR reference, remove or add ADR citation

Rule 2: Evidence Required

What This Means

Every factual claim about infrastructure, services, endpoints, or behavior must cite evidence.

Evidence Types (in order of authority)

Type Format Example
Code file:line cmd/fulcrum-server/main.go:437
Script Output script @ timestamp validate-infra.sh @ 2026-02-01
ADR ADR-XXXX ADR-0002
Truth Map TRUTH_MAP.md#section TRUTH_MAP.md#railway-services
Manual Verify MANUAL VERIFY: [procedure] MANUAL VERIFY: Railway dashboard → Settings

Evidence Tagging Format

<!-- Evidence: docs/infra/PROD_TRUTH_MAP.md, verified 2026-01-31 -->
The MCP endpoint is served via fulcrum-server at `/mcp`.

<!-- Evidence: sdk/python/__init__.py:31 -->
Python SDK version is 0.1.3.

<!-- UNVERIFIED: Manual check required via Railway dashboard -->
Autodeploy is disabled for all services.

<!-- MANUAL VERIFY: `curl https://api.fulcrumlayer.io/health` -->
Health endpoint returns 200.

When Evidence Is Missing

If you cannot find evidence for a claim: 1. Do NOT write the claim as fact 2. Either: Remove the claim, OR 3. Tag as <!-- UNVERIFIED --> with verification procedure

Rule 3: Canonical Files Define Reality

Source of Truth Hierarchy

When documents conflict, this hierarchy determines truth:

1. ADRs (docs/decisions/ADR-*.md)
   └── Approved architectural decisions

2. TRUTH_MAP.md (docs/infra/TRUTH_MAP.md)
   └── Verified infrastructure state

3. Code behavior
   └── What the code actually does

4. Other documentation
   └── May be stale; verify against above

Canonical Files

Domain Canonical File Purpose
Infrastructure docs/infra/TRUTH_MAP.md Services, domains, env vars
Decisions docs/decisions/ADR-*.md Architectural choices
Configuration railway.toml, Dockerfile Build/deploy config
API api.swagger.json REST API spec
Secrets docs/runbooks/CREDENTIALS.md Secret locations (not values)

Resolution Protocol

When you find a contradiction: 1. Identify which source is higher in hierarchy 2. Update lower-authority doc to match higher 3. If unsure, verify via code or script output 4. Document the resolution in commit message

Rule 4: Change Protocol

When ADR Is Required

Change Type ADR Required? Example
New service YES Adding fulcrum-analytics
Delete service YES Removing fulcrum-mcp
Change database YES Switching from Postgres to MySQL
New domain YES Adding api2.fulcrumlayer.io
Architecture change YES Changing MCP from standalone to embedded
Config change NO Updating env var value
Doc correction NO Fixing stale service name
New tutorial NO Adding getting-started guide

ADR Template Location

docs/decisions/0000-adr-template.md

Doc-Only Changes

For changes that don't require ADR: 1. Update doc with evidence citation 2. Commit with clear message: docs(scope): what changed and why 3. Reference evidence source in commit body

Rule 5: Verification Cadence

Automatic Verification

  • scripts/validate-infra.sh - Run on every deploy
  • scripts/verify-lockdown.sh - Run before releases

Manual Verification Schedule

Item Frequency Owner Procedure
Railway services Weekly Ops railway status --json
Vercel config Weekly Ops Vercel dashboard
Domain routing Weekly Ops validate-infra.sh
Doppler sync Weekly Ops Doppler dashboard
SDK versions Per release Dev Check PyPI/npm

Verification Output Location

docs/infra/validate-infra.latest.txt - Latest script output snapshot

Enforcement

Pre-Commit Check

Future: Add pre-commit hook to detect: - Dates without ADR references - Claims without evidence tags - References to deleted services

Review Checklist

Before merging doc changes: - [ ] No invented dates/timelines - [ ] Factual claims have evidence tags - [ ] References canonical files where applicable - [ ] No contradictions with TRUTH_MAP.md - [ ] UNVERIFIED tags include verification procedure

Document Purpose
docs/infra/DOC_STYLE.md Canonical terminology
docs/infra/TRUTH_MAP.md Infrastructure truth source
docs/decisions/ Architecture Decision Records
.claude/doc-master.local.md Doc-master configuration

Contract established: 2026-02-01 Source: conductor/Fulcrum_rewrite.md, conductor/product-guidelines.md