Chapter 4.2 follows chapter 4.1, The profile library of documentation doses, and precedes chapter 4.3, The purpose and rules of each dose, within part 4, the profile library.
The treatment adds a set of documentation artifacts to a codebase. The set identifies the cheapest source for a needed fact. The other artifacts provide orientation, code links, structured traceability, implementation decisions, cross-module relationships, and maintenance guidance. They are inert documentation and do not alter program behaviour.
4.2.1 Navigation index of the documentation profiles
The entry-point index, a list that directs an agent to the right documentation, is at the root of the documented variant. It points an agent towards the relevant readme, trace anchor, a code comment that links to explanatory documentation, or JavaScript Object Notation file instead of requiring a broad search of the repository.
4.2.2 Orientation files of the documentation profiles
Orientation files are READMEs at the repository root and inside folders, together with short headers at source-file boundaries. They provide location information. They do not carry the reasoning or implementation detail held by the other artifacts.
4.2.3 Trace anchors of the documentation profiles
A trace anchor, a comment at a code site that links a passage to the documentation describing its rule, gives the agent a stable connection between source and explanation. The anchor identifies the invariant enforced at that site. It changes no program behaviour.
4.2.4 Traceability file of the documentation profiles
The traceability file is the machine-readable traceability.json artifact. Its required contents are a schema version, a variant identifier, and maps connecting invariants to enforcing code, requirements to implementing code, and tests to the requirements they cover. It can mark an uncertain link instead of omitting the link or inventing a destination.
4.2.5 Decision notes of the documentation profiles
Decision notes are comments placed where the correct implementation choice is not evident from the code. Each note records the reason for a particular form of implementation. The notes preserve decisions close to the code that depends on them.
4.2.6 Relationship map of the documentation profiles
A relationship map, a graph in JavaScript Object Notation of cross-module trap seams, links a module where a symptom appears to the module that causes it. It exposes dependencies whose effects cross module boundaries. The map is stored as its own relationship_map.json artifact.
4.2.7 Agent manuals of the documentation profiles
An agent manual, documentation for an artificial intelligence agent maintaining the codebase, describes how to use the documentation layer during maintenance. It covers the available navigation artifacts, the trace anchors, the traceability file, and the relationship map. The manuals are supplied as separate User Manual and Developer Guide files.
4.2.8 Artifact anatomy of the documentation profiles
The locations and relationships of the documentation artifacts in a documented codebase.
4.2.9 Trace file structure of the documentation profiles
Figure D-L1-2. A structured JavaScript Object Notation object containing a schema version, a variant identifier, and maps from invariants, requirements, and tests to the code or requirements they describe, with uncertainty marking shown as an allowed link state.
%% figure D-L1-2 flowchart TB subgraph g1[" "] n1["A structured JavaScript Object Notation object containing a schema version<br/>a variant identifier<br/>maps from invariants<br/>requirements"] end subgraph g2[" "] n2["tests to the code or requirements they describe<br/>uncertainty marking shown as an allowed link state"] end n1 --> n2
source: operations/site-ia/A3-diagram-specification.md
source: 3. LAP Profile Library/traceability_schema.md line 24
The required structure of the traceability file and its links among code, requirements, invariants, and tests.
4.2.10 Artifact counts of the documentation profiles
The treatment contains six artifact kinds. source: 3. The LAP Profiles.md line 30
The largest documentation set contains fifteen files. The lap_artifact_manifest.json key lap_files supplies that file count.
source: lap_artifact_manifest.json key lap_files