truthmark/docs/features/contracts.md

status, doc_type, last_reviewed, source_of_truth

status	doc_type	last_reviewed	source_of_truth
active	feature	2026-05-10	../../src/config/schema.ts ../../src/checks/check.ts ../../src/templates/init-files.ts ../../src/init/init.ts ../../src/output/diagnostic.ts ../../src/output/render.ts

Contracts

Scope

This document defines the current machine-facing contracts exposed by Truthmark: the config file shape and the CLI result envelope.

Config Contract

Truthmark loads .truthmark/config.yml and validates it against the current schema.

Current fields:

• version: must be 1
• platforms: optional list of agent harnesses to initialize; defaults to all supported platforms
• docs.layout: currently hierarchical
• docs.roots: named canonical doc roots
• docs.routing.root_index: root area index path
• docs.routing.area_files_root: child area route directory
• docs.routing.default_area: default child route file basename used by scaffold
• docs.routing.max_delegation_depth: currently must be 1
• authority: ordered list of canonical doc paths or globs
• instruction_targets: files that receive installed instructions; defaults to AGENTS.md
• frontmatter.required: frontmatter fields that produce error diagnostics when missing
• frontmatter.recommended: frontmatter fields that produce review diagnostics when missing
• ignore: glob patterns excluded from relevant checks and routing logic
• realization.enabled: whether doc-first realization is enabled

The default scaffolded authority list includes:

• docs/truthmark/areas.md
• docs/truthmark/areas/**/*.md
• docs/ai/**/*.md
• docs/standards/**/*.md
• docs/architecture/**/*.md
• docs/features/**/*.md

Supported platforms values are:

• codex
• opencode
• claude-code
• github-copilot
• gemini-cli

There is no .truthmark/local.yml contract in the current implementation. User preferences that affect generated repository behavior must be expressed through committed config or the generated surfaces cannot be reproduced by another checkout.

Command Result Envelope

truthmark config, truthmark init, and truthmark check return the same JSON envelope when run with --json.

Current shape:

• command: string command name
• summary: human-readable summary string
• diagnostics: array of diagnostic objects
• data: optional command-specific object

Diagnostic fields:

• category: one of config, authority, frontmatter, links, area-index, coverage, truth-sync, realization, doc-structure, or generated-surface
• severity: one of info, action, review, or error
• message: human-readable detail
• file: optional repository-relative file path
• area: optional area name from docs/truthmark/areas.md
• data: optional machine-readable extras

Human-rendered output is intended for people. JSON output is the machine-facing contract.

Config Result Data

truthmark config --json writes only .truthmark/config.yml unless --stdout is used.

Current config result data fields include:

• repositoryRoot
• worktreePath
• branchName
• isDetached
• isUnborn

When --stdout is used, data also includes:

• path
• content

Init Result Data

truthmark init --json currently returns these data fields:

• repositoryRoot
• worktreePath
• branchName
• isDetached
• isUnborn

The command emits action diagnostics describing whether each scaffolded file was created, updated, or unchanged. Generated realization skill files use the realization diagnostic category.

truthmark init requires an existing valid .truthmark/config.yml. It does not create config; truthmark config is the required first step in a new repository. Configured instruction_targets are generated or refreshed independently of platform-specific surfaces, so AGENTS.md remains managed even when claude-code is not in platforms.

Generated Truth Structure, Truth Document, Truth Sync, and Truth Check surfaces and the managed AGENTS.md block use the truth-sync diagnostic category.

Current agent-native scaffold targets include:

• .codex/skills/truthmark-structure/SKILL.md
• .codex/skills/truthmark-structure/agents/openai.yaml
• .codex/skills/truthmark-document/SKILL.md
• .codex/skills/truthmark-document/agents/openai.yaml
• .codex/skills/truthmark-sync/SKILL.md
• .codex/skills/truthmark-sync/agents/openai.yaml
• .codex/skills/truthmark-realize/SKILL.md
• .codex/skills/truthmark-realize/agents/openai.yaml
• .codex/skills/truthmark-check/SKILL.md
• .codex/skills/truthmark-check/agents/openai.yaml
• .claude/skills/truthmark-structure/SKILL.md
• .claude/skills/truthmark-document/SKILL.md
• .claude/skills/truthmark-sync/SKILL.md
• .claude/skills/truthmark-realize/SKILL.md
• .claude/skills/truthmark-check/SKILL.md
• .opencode/skills/truthmark-structure/SKILL.md
• .opencode/skills/truthmark-document/SKILL.md
• .opencode/skills/truthmark-sync/SKILL.md
• .opencode/skills/truthmark-realize/SKILL.md
• .opencode/skills/truthmark-check/SKILL.md
• AGENTS.md
• CLAUDE.md
• .github/copilot-instructions.md
• .github/prompts/truthmark-structure.prompt.md
• .github/prompts/truthmark-document.prompt.md
• .github/prompts/truthmark-sync.prompt.md
• .github/prompts/truthmark-realize.prompt.md
• .github/prompts/truthmark-check.prompt.md
• GEMINI.md
• .gemini/commands/truthmark/structure.toml
• .gemini/commands/truthmark/document.toml
• .gemini/commands/truthmark/sync.toml
• .gemini/commands/truthmark/realize.toml
• .gemini/commands/truthmark/check.toml

Generated SKILL.md files use closed YAML frontmatter with name, description, argument-hint, user-invocable, and truthmark-version fields so Codex-style, Claude Code, and OpenCode-style skill indexers can parse every generated workflow surface. Generated Copilot prompt files use .github/prompts/*.prompt.md files with agent and description frontmatter so supported Copilot IDEs can expose /truthmark-* prompts. Generated Codex metadata includes a truthmark.version marker plus truthmark.refresh_command: "truthmark init". Managed instruction blocks also render the Truthmark package version, and package.json is the single maintained version source for those markers. Generated Gemini command files use project-scoped TOML custom commands so truthmark init can install /truthmark:structure, /truthmark:document, /truthmark:sync, /truthmark:realize, and /truthmark:check alongside GEMINI.md. Re-running truthmark init after a package upgrade refreshes configured committed surfaces and exposes staleness through ordinary Git diffs. Removing a platform from config stops future refreshes for that platform; it does not delete previously generated files.

Check Result Data

truthmark check --json returns:

• branchScope
• truthVisibility

branchScope contains:

• repositoryRoot
• worktreePath
• branchName
• headSha
• identity
• relevantFileHashes

For normal branches, identity is branch name plus HEAD SHA. For detached checkouts, identity is the commit SHA. worktreePath remains separate so callers can distinguish parallel worktrees for the same repository.

relevantFileHashes currently tracks hashes for:

• .truthmark/config.yml
• the configured root route index
• configured child route files under the configured area-files root

truthVisibility contains:

• routePrecision.leafAreaCount
• routePrecision.broadAreaCount
• unmappedSurfaceCount
• staleGeneratedSurfaceCount
• syncCompletenessIssueCount
• topologyPressureCount

Current Diagnostic Emission Notes

• ordinary truthmark check emits config, authority, frontmatter, links, area-index, coverage, doc-structure, and generated-surface diagnostics.
• truth-sync and realization categories exist for init and generated workflow reporting, but ordinary check does not emit workflow payloads.
• truthmark check does not support --workflow truth-sync in the current contract.
• Missing authority files are error diagnostics.
• Authority globs and code-surface globs that match nothing are review diagnostics.
• Coverage diagnostics discover unmapped functional code across common code roots with the same path classifier used by Truth Sync. V1 coverage must include Go, Python, C#, Java, JavaScript, TypeScript, frontend roots, monorepo app or package roots, Terraform, Kubernetes manifests, CI workflows, OpenAPI or Swagger, GraphQL, and protobuf surfaces within those roots.
• doc-structure emits review diagnostics when configured architecture or current feature docs are missing active Product Decisions or Rationale sections.

Product Decisions

• The committed config file owns the documentation hierarchy contract, while route files own domain-to-doc mappings.
• truthmark config and truthmark init are separate contracts so repositories can review hierarchy before workflow installation.
• Active decisions stay in the canonical doc they govern instead of in separate timestamped decision logs. Date active decisions inline when added or changed.
• The V1 user-facing CLI surface is limited to config, init, and check; workflow verbs such as sync, realize, structure, audit, packet, review, scan, doctor, build, and context are not top-level commands.
• gemini-cli installs both hierarchical GEMINI.md context and project-scoped .gemini/commands/truthmark/*.toml custom commands so Gemini users get the same explicit workflow entrypoints without adding top-level CLI verbs.

Rationale

Separating config from init keeps repository layout reviewable and predictable. Keeping decisions with the owning feature, contract, or architecture doc prevents agents from having to infer which historical note is still active.

Keeping workflow verbs out of the CLI preserves the agent-native model: installed skills and instruction blocks run the workflows, while the CLI installs and validates repository artifacts.