truthmark/docs/features/contracts.md

---
status: active
doc_type: feature
last_reviewed: 2026-05-09
source_of_truth:
  - ../../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 `codex`, `opencode`, and `claude-code`
- `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:

- `TRUTHMARK.md`
- `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`
- `cursor`
- `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.

Generated Truth Structure, 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`
- `skills/truthmark-structure/SKILL.md`
- `.codex/skills/truthmark-sync/SKILL.md`
- `.codex/skills/truthmark-sync/agents/openai.yaml`
- `skills/truthmark-sync/SKILL.md`
- `.codex/skills/truthmark-realize/SKILL.md`
- `.codex/skills/truthmark-realize/agents/openai.yaml`
- `skills/truthmark-realize/SKILL.md`
- `.codex/skills/truthmark-check/SKILL.md`
- `.codex/skills/truthmark-check/agents/openai.yaml`
- `.opencode/skills/truthmark-structure/SKILL.md`
- `.opencode/skills/truthmark-sync/SKILL.md`
- `.opencode/skills/truthmark-realize/SKILL.md`
- `.opencode/skills/truthmark-check/SKILL.md`
- `skills/truthmark-check/SKILL.md`
- `AGENTS.md`
- `CLAUDE.md`
- `.cursor/rules/truthmark.mdc`
- `.github/copilot-instructions.md`
- `GEMINI.md`
- `.gemini/commands/truthmark/structure.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 skill indexers can parse every generated workflow surface. Generated Codex metadata includes a `truthmark.version` marker plus `truthmark.refresh_command: "truthmark init"`. Generated Gemini command files use project-scoped TOML custom commands so `truthmark init` can install `/truthmark:structure`, `/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`
- `TRUTHMARK.md`
- 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. Short inline decision dates are allowed on the active decision itself.
- 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.