Canonical Sources, Links, and History
Avoiding Contradictions
A canonical source (source of truth) is the authoritative location that a project designates as definitive for a particular class of information.
When information exists in multiple places, the project MUST explicitly designate the canonical source or establish a clear precedence rule. For example:
| Information Class | Potential Canonical Source |
|---|---|
| Task status | Issue tracker |
| Architecture decisions | ADR repository |
| Project conventions | Relevant documents in FISS/knowledge/ |
| File change history | Version-control system |
This illustrates separation of responsibilities rather than a fixed FISS hierarchy. Project rules should be placed where they will be encountered when working in that context; broad rules belong in FISS/BOOTSTRAP.md.
In accordance with the “Keep canonical sources clear” principle, FISS must not duplicate code, documentation, or external systems without clear justification: copies, summaries, and projections must not silently become competing sources of truth. When a summary is helpful (such as a human diagram), explicitly identify the canonical source.
When sources conflict, do not silently pick a preferred version. Apply the designated source rule. If no rule exists, resolving the conflict requires an explicit team decision.
Linking Materials
Relationships between artifacts are expressed with standard Markdown links and concise explanations. A formal typed relationship syntax is not required.
For example, in FISS/state/adr/payment-decision.md:
This decision resolves [the open question on payment models](../../state/open-questions/payment-model.md).The read condition is required for navigation links in indexes. In substantive documents, a brief explanatory note describing the relationship is sufficient.
When In-Document History is Needed
Change logs inside individual documents are optional. For files under Git version control, technical revision history is already tracked by the repository.
Status or changelog notes are valuable when their omission could lead to misapplying the material. For instance, a decision record can indicate whether it is active, superseded, or withdrawn, with a link to its successor. The team determines whether individual documents require internal changelogs.