Profile reference

A profile is a YAML file. This page lists its fields. How to import and activate a profile is described in Profiles.

Top level

Field	Type	Default	Meaning
`name`	text	required	Display name.
`slug`	text	required	Identifier, only `a-z`, `0-9`, `_` and `-`. Also the file name in `specs/_profiles/`.
`artifact_types`	list	empty	The artifact types, see below.
`link_types`	list	empty	The allowed link types, see below.
`statuses`	list	`[draft, review, approved, obsolete]`	The statuses specs can have.
`workflows`	map	all off	Approval and signature rules.
`traceability`	map	see below	Trace chain and gap severities.
`classifications`	map	empty	Free dimensions for the `classifications` field.
`storage`	`managed` or `sidecar`	`managed`	Who owns the spec files. See Managed and sidecar profiles.
`frontmatter_format`	`ce`, or the name of an adapter	`ce`	Format of the frontmatter in the spec files. See Example: a proprietary format.
`source`	map	none	Location of foreign specs.

Artifact types

artifact_types:
  - id: URS
    label: "User Requirements Specification"
    folder: urs
    id_pattern: "URS-{rand}"
    required_fields: [id, title, status, acceptance_criteria]
    optional_fields: [rationale, classifications, anchors, links]

Field	Meaning
`id`	Short name of the type, unique.
`label`	Display name.
`folder`	Folder under `specs/` for new files, unique.
`id_pattern`	Pattern for new IDs with exactly one placeholder: `{rand}` (random, safe for several writers) or `{seq:04d}` (counter, padded to the given width). When reading existing IDs the width is ignored.
`required_fields`	Frontmatter fields every spec of this type must have.
`optional_fields`	Further fields shown in the Fields tab. Must not repeat a required field.
`template`	Sections for generated drafts, see below.

Templates for generated drafts

A template defines the sections the AI fills when it writes a draft. Tracemoor renders the body from them in the given order and checks them before the draft is stored.

    template:
      - name: functional_purpose
        label: "Functional Purpose"
        kind: text
        required: true
        constraints:
          must_contain_any: [must, shall]
      - name: inputs
        label: "Inputs"
        kind: struct_list
        fields:
          - { name: name, required: true }
          - { name: type }
      - name: acceptance_criteria
        label: "Acceptance Criteria"
        kind: list
        required: true
        constraints:
          deny_phrases: ["internal state"]

Field	Meaning
`name`	Key of the section. Unique within the type.
`label`	Heading in the body.
`kind`	`text` (one paragraph), `list` (list of lines) or `struct_list` (table with the columns in `fields`).
`required`	The draft is rejected when the section is empty.
`fields`	Columns of a `struct_list`. Only allowed there, and required there.
`constraints.must_contain_any`	At least one of these words must appear.
`constraints.deny_phrases`	None of these phrases may appear.

Link types

link_types:
  - id: satisfies
    inverse: satisfied_by
    source_types: [FS]
    target_types: [URS]
  - id: satisfied_by
    inverse: satisfies

Field	Meaning
`id`	Name of the link type, unique.
`inverse`	The link type of the opposite direction. Must exist.
`source_types`	Types that may have this link. Empty: all.
`target_types`	Types the link may point to. Empty: all.

source_types and target_types limit the choices in the Links tab. They are not checked when files are read.

Workflows

workflows:
  approval_required: true
  esignature: true
  esignature_method: password
  suspect_links: true
  brave_mode_required_for:
    - status_change_to_approved
    - esignature

Field	Meaning
`approval_required`	Approval is part of the workflow.
`esignature`	`approved` and `rejected` need an electronic signature.
`esignature_method`	Default signature method. The method in Project Settings › Signing takes precedence. See Signatures.
`suspect_links`	Track suspect anchors and links.
`brave_mode_required_for`	Actions the AI may perform only in Brave mode. `status_change_to_<status>` must name a status from `statuses`.

Traceability

traceability:
  required_chain: [URS, FS, TC]
  gap_severity:
    no_implementation: error
    no_test: warning
    suspect: warning

Field	Meaning
`required_chain`	The types a requirement passes through, in order. Each must be a declared type.
`gap_severity`	`error`, `warning` or `info` for a requirement without implementation, without test, or with suspect anchors. Defaults: `error`, `warning`, `warning`.

Classifications

classifications:
  layer:
    values: [presentation, business, persistence, integration]
  safety_classification:
    values: [A, B, C]

Each key is a dimension with its allowed values. The order is kept.

Source of foreign specs

source:
  include: [requirements, specifications]
  exclude: [attachments]

Field	Meaning
`root`	Folder of the specs. Usually left out and set per machine as Spec source folder in the project settings, so that no absolute path is shared. Relative paths are resolved from the exploration.
`include`	Subfolders to read. Empty: everything. If none of them exists, the whole folder is read.
`exclude`	Subfolders to skip.

include and exclude must be relative and must not contain ... Tracemoor 's own folders (_profiles, _overlays, _drafts) always stay under specs/ of the exploration.

Example: a proprietary format

Tracemoor reads spec files in another format through a frontmatter adapter in its code. frontmatter_format: pandora is such an adapter. It was written for one team's Obsidian vault with its own frontmatter and shows what an adapter maps:

Field in the foreign format	Becomes in Tracemoor
`key`	ID
`title`	title
`type: requirements` / `specifications` / `robot`	type `REQ` / `SPEC` / `RTC`
`requirements: [...]`	`satisfies` links
`[[…]]` links in the body	`references` links
further fields	classifications

The profile that uses it declares exactly these three types and storage: sidecar, so the foreign files stay unchanged. A different proprietary format needs its own adapter, which is a code change.

Validation

Tracemoor rejects a profile on import and on load, listing every problem, when:

name is empty or slug contains other characters than a-z, 0-9, _, -.
Two artifact types share an id or a folder, or one of them is empty.
An id_pattern does not contain exactly one {rand} or {seq:NNNd}.
A field is both required and optional.
A template repeats a section name, a struct_list has no fields, or another kind has fields.
Two link types share an id, or an inverse names an unknown link type.
statuses is empty, or brave_mode_required_for names an unknown status.
required_chain names an undeclared type.
A source.include or source.exclude entry is absolute or contains ...

An invalid override in specs/_profiles/ does not fall back to the shipped profile. The error is shown instead.