Source model
Canonical source
The source of truth is the fragment tree under .ledger/archledger/data:
sections/for the major arc42 chapter skeletonrecords/for individual architecture factsarchive/for archived records and tombstones that preserve allocated ledger IDs
Records include structural, behavioral, and decision artifacts plus first-class
diagram records. Diagram records default to plain text diagrams (diagram_type = "text").
Text diagrams stay embedded in Markdown/AsciiDoc record bodies as readable fenced blocks.
Mermaid is available for compact sequence, state, or flow diagrams but is not the default.
Fragments contain YAML front matter and a body in the configured dialect.
Archived fragments keep normal front matter and use status: archived.
Archledger does not store creation, update, or archive timestamps in ledger
source. Every current source fragment has a positive monotonic version.
CLI mutation commands increment it exactly once; manual source edits must
increment it manually.
Ledger ID format
Default IDs use <prefix>_<number> (for example al_0013).
When [ids].segment_mode = "type", IDs use
<prefix>_<segment>_<number> (for example al_content_0013 and
al_risk_0014). Segment values come from metadata/config mapping, while
the numeric sequence remains one global ledger-wide counter.
Traceability
Use source_refs when fragments describe real files or directories.
Directory refs must end with / and must exist in the workspace.
Generated output
Generated build outputs are derived artifacts and should not be edited as
source. New projects default to build/ under the workspace root, and
[build].default_output_dir may place outputs elsewhere.
External references
Use generic links and source_refs for artifacts outside the architecture
ledger. Archledger preserves these references as data and does not interpret
external domain semantics.
Example:
links:
- rel: documents
target_kind: path
target: specs/behavior/features/task-management/plan-gates.feature
reason: External artifact documents the runtime flow.