truthmark/docs/standards/default-principles.md

---
status: active
doc_type: standard
last_reviewed: 2026-07-30
source_of_truth:
  - ../README.md
  - documentation-governance.md
---

# Default Principles

## Scope

This standard defines the reusable default principles Truthmark can safely scaffold into repositories that adopt branch-local truth workflows.

These are bootstrap defaults, not immutable law. Repositories should replace or extend them once they have stable project-specific standards.

## Default Versus Project Standards

- Truthmark defaults are a starting point for repositories that do not yet have explicit standards.
- Repository-specific standards are preferred once a project has stable architecture, product rules, or verification needs.
- Local standards should be explicit and committed in the repository rather than left in chat, memory, or team habit.
- When a project defines its own standards clearly, those standards should take precedence over generic Truthmark defaults.

## Reusable Default Principles

### Authority And Context

- Authority order should be explicit.
- Committed repository artifacts are the durable source of truth.
- External memory and off-repo discussion are non-authoritative unless the user provides them in the current session or commits them into the repo.
- Agent instruction files install workflow behavior by default; they do not become product truth unless a project opts into that explicitly.

### Documentation Governance

- 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 planning context; 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 remain an onboarding or product-facing entry point, but it should not silently compete with canonical engineering docs.

See [docs/standards/documentation-governance.md](documentation-governance.md) for the governance baseline.

### Verification Discipline

- Verification commands should have one canonical source.
- Build, lint, and typecheck are necessary but not sufficient for behavior changes.
- New behavior and bug fixes should add or update relevant automated coverage when reasonably testable.
- Skipped verification should be stated explicitly with a reason.
- Documentation-only changes do not require code-level verification unless commands or executable examples changed.

### Completion Discipline

- Repositories should define a completion gate or pre-completion checklist.
- If a normally expected test or check is skipped, the reason should be stated explicitly.
- Behavior changes and documentation changes should land together.
- Scope should stay focused; unrelated refactors should not be mixed into the requested work.
- Repositories should avoid speculative compatibility layers, duplicate contracts, shadow behaviors, or parallel route surfaces unless an explicit migration requirement exists.

### Harness Principles

- Important project facts should be visible in committed repository artifacts.
- If an agent repeatedly misses an important fact, the repository probably needs a clearer maintained document for that fact.
- Explicit constraints, routing, and feedback loops are more reliable than vague prompt instructions.
- Weak routing and weak feedback produce weak truth maintenance.
- AI-native structure repair should handle broad or overloaded documentation topology before agents create more generic truth docs.
- Installed repository workflows should remain usable from committed files even when the Truthmark CLI is unavailable.

## What Truthmark Can Reuse Safely

Truthmark can safely reuse or adapt defaults in these areas:

- documentation governance
- authority order and context-boundary rules
- verification and testing discipline
- pre-completion and explicit skip-reason discipline
- harness and repository-visible feedback principles

## What Truthmark Should Not Treat As Universal Defaults

Truthmark should not impose repository-specific rules such as:

- language- or framework-specific dependency layering models
- stack-specific localization rules
- repository-specific route, permission, or contract conventions
- product-specific feature invariants
- toolchain-specific command versions unless the project config sets them

Truthmark can provide places for those rules to live, but the content should belong to the project.

## Recommended Default Scaffold

When a repository has no explicit standards yet, a small default baseline is reasonable:

- a documentation governance standard
- authority and routing entrypoints such as `.truthmark/config.yml` and `docs/truthmark/routes/areas.md`
- a verification standard with canonical commands and skip rules
- a completion checklist or equivalent completion gate

Truthmark can bootstrap only part of that baseline automatically today. Repositories may need to add richer standards after initialization.

The default truth-document template rationale lives in [template-standards.md](template-standards.md); it maps Truthmark's template shapes to recognized software engineering references without claiming external certification.

Projects may keep that baseline, replace it, or extend it with their own standards.

## Override Model

- Users are allowed to write their own standards.
- In practice, writing project-specific standards is often better than relying forever on generic defaults.
- Truthmark should make those standards easy to add, route, and keep authoritative.
- Default principles are meant to reduce ambiguity at startup, not to lock a project into Truthmark-authored policy forever.