truthmark/docs/standards/documentation-governance.md

status, doc_type, last_reviewed, source_of_truth

status	doc_type	last_reviewed	source_of_truth
active	standard	2026-07-30	../README.md ../ai/repo-rules.md

Documentation Governance

Scope

This standard defines the documentation-governance rules Truthmark itself follows when routing truth docs, syncing code changes into docs, and realizing docs back into code.

Projects may adapt the exact directory layout, but the rules below are the reusable core that makes branch-local truth routing work.

For the broader reusable baseline beyond documentation governance, see docs/standards/default-principles.md.

Small repositories are in scope. A project does not need a large documentation program to benefit from Truthmark. It needs only a small canonical truth surface, clear ownership, and a willingness to improve routing quality over time.

Core Rules

• Each document should have one primary responsibility.
• Each class of fact should have one canonical source.
• Current implementation, reusable standards, and accepted decision rationale have distinct canonical owners.
• Git history carries superseded plans and implementation choices; active docs keep only current behavior and necessary rationale in the owning decision section.
• Do not maintain parallel documentation trees for the same subject.
• The root README may introduce the project or product, but it should not silently compete with canonical engineering or behavior docs.
• Agent instruction files may install workflow behavior, but they are not product truth unless a project explicitly includes them in authority.
• Generated helper output is never canonical truth.

Truthmark Implications

• Truth Sync works best when changed code maps to a small and explicit set of truth docs.
• Truth Realize works best when authority order and area ownership are unambiguous.
• Weak routing produces weak truth maintenance.
• Large repositories should treat topology repair as an AI workflow responsibility, not as a human folder-discipline requirement.
• Automatically created truth should be placed conservatively: extend mapped docs first, create an area-local doc second, create a new area only as a last resort.
• When a fact is already canonical elsewhere, Truth Sync should update or reference that source rather than duplicating the fact in a second document.

Canonical Surface

Truthmark's minimal canonical surface is:

• docs/ai/repo-rules.md as the repository-wide agent policy source
• .truthmark/config.yml as the committed hierarchy contract
• docs/truthmark/routes/areas.md as the primary routing surface
• the project's canonical docs under directories such as docs/standards/, docs/architecture/, docs/truthmark/product/, and docs/truthmark/engineering/

By default, instruction files such as AGENTS.md install workflow behavior. They do not outrank the canonical truth surface unless a project opts into that explicitly.

In Truthmark itself, AGENTS.md should contain a small manual preamble plus the managed Truthmark block. The block is workflow installation, not the place for broader repository rules.

Recommended Document Classes

Use a small number of stable document classes:

• standards for reusable rules and governance
• architecture for current structural decisions
• truth docs for current behavior and invariants

Projects do not need every class on day one. They do need clear ownership for current truth, reusable standards, and accepted decision rationale.

Architecture docs describe system structure, module boundaries, runtime topology, persistence boundaries, cross-cutting contracts, and generated-surface ownership.

Architecture docs should not carry ordinary product behavior, endpoint details, UI copy, validation rules, or bug fixes unless those changes alter architecture boundaries. Keep product behavior in behavior or contract docs.

Decision-Bearing Truth Docs

Active decisions are part of current truth. They live in the canonical doc for the feature, contract, architecture surface, or standard they govern.

Use Product Decisions and Engineering Decisions sections for accepted decisions and the rationale needed to explain non-obvious behavior, boundaries, rejected directions, or migration constraints.

When a decision changes, replace the old active decision in the same canonical doc. Git history is the historical decision log.

Date active decisions inline when added or changed, for example Decision (2026-05-09): keep routing agent-native. The date is context on the active decision, not a separate historical log.

Do not create separate timestamped ADR folders, planning tickets, or historical design notes as repository guidance. Promote necessary accepted rationale into the owning decision section and rely on Git history for superseded context.

Update Rules

• Behavior changes and truth-doc updates should land in the same working change when possible.
• Major product, onboarding, install, command, positioning, or workflow changes should include a root README review in the same working change. Update the README when its human-facing claims, examples, or command sequences are stale.
• When the root README has localized variants, keep them aligned with the English README for materially changed install, command, positioning, and workflow guidance in the same working change, or explicitly document why a variant intentionally differs.
• When routing changes, update docs/truthmark/routes/areas.md and any affected canonical docs together.
• When routing is missing, stale, broad, overloaded, catch-all, or cannot map changed code to a bounded truth owner, run Truth Structure before adding more generic truth docs.
• When a code change alters system structure, module boundaries, runtime topology, persistence boundaries, cross-cutting contracts, or generated-surface ownership, update the owning architecture doc in the same change.
• Do not update architecture docs for ordinary product behavior unless that behavior changes an architecture boundary.
• When a document stops being canonical, supersede or demote it explicitly.
• If Truth Sync is skipped, the skip reason should be stated clearly.
• If Truth Sync creates missing truth, it should avoid duplicating facts that are already canonical elsewhere.
• When truthmark init seeds a broad truth-doc list from existing Markdown, narrow that list to the canonical surface before relying on it.

Anti-Patterns

• multiple documents claiming authority over the same behavior
• product behavior defined only in agent instruction files
• the root README redefining behavior already owned by canonical docs
• the root README lagging behind major install, command, or workflow changes
• current-state docs mixed with draft proposals in the same file
• historical planning docs treated as if they were current product truth
• generated helper output committed to Git or treated as authority
• area mappings that are so broad that agents cannot identify which docs actually matter
• generic truth docs created because topology was too broad to resolve a specific behavior owner
• current decisions stored only in separate timestamped plans, ADR logs, or draft specs
• old and new decisions coexisting as parallel active truth

Checklist

• Does this document have one primary responsibility?
• Does each class of fact have one canonical source?
• Is this fact stored in the correct document class?
• Does docs/truthmark/routes/areas.md route the changed area to the right truth docs?
• If routing is broad or overloaded, has Truth Structure repaired topology before new truth docs were created?
• Are duplicated or shadow documentation paths being avoided?
• Is generated helper output still treated as non-authoritative rather than truth?
• Are superseded plans absent from active docs, with necessary accepted rationale kept in the owning decision section?

Product Decisions

• Decision (2026-05-14): Documentation governance remains a canonical standard doc rather than moving into agent instructions or the root README.

Rationale

Keeping governance in a standard doc preserves one reusable authority for routing, truth-sync, README parity, and decision-bearing doc maintenance without scattering those rules across workflow surfaces.