Source of Truth: Which Record Answers Which Question

How AI coding agents work and context as a limited resource explained how an agent operates and why its context is finite. The next question is how it should find knowledge about the project. On any ordinary working day the same project lives in many places at once: tasks in Jira, code and documentation in Git, discussion in pull requests, data in a database, approved material in Drive, messages in chat, execution logs, and the agent's own short-lived memory. These places do not necessarily contradict one another. More often they answer different questions.

A source of truth is an agreed, verifiable source that is authoritative for a particular kind of claim within a defined scope. A project as a whole may have no single source of truth at all. The code in the repository answers the question "what exactly is stored at this revision?" The database answers "which record is currently held for this customer?" The event log answers "what did the system record earlier?" None of them, on its own, decides what the approved product policy is.

The goal is not to copy everything into one big encyclopedia. The goal is to know in advance where a requirement is recorded, who approves a decision, how to verify that something was done, and what to do when the records disagree.

Four different roles

Source of truth is the system or specific record the team has entrusted with answering a particular question. That status comes from process and agreed boundaries, not from a file extension or a product name. For example, the approved-terms section of a Drive folder can be the source for the current commercial policy. The Drive folder by itself does not make every file inside it approved.

System of record is the place where the authoritative set of records of a given category is kept: customer accounts in a database, say, or feature requirements in Jira. A system of record may keep change history and support audits. That does not make it the source of every kind of truth. A customer record does not define what was promised to customers; Jira does not prove that new code is already serving traffic.

Runtime state is what the system is actually doing or holding right now: the application version that is answering requests, the configuration in force, the state of a particular order, a live process. Any observation of runtime state is tied to a time, an environment and a method of checking. Yesterday's snapshot does not prove today's state.

Event log or change history is a record of what the system saw or registered, in order: a status transition, a request, an error, a commit, an edit to a field. It helps explain how the current state came about. But the event "the user clicked Publish" does not yet prove that the site deployed successfully; the log may be incomplete, or the action may have failed.

Convenience copy is an extract, a summary, an export, a local copy, a cache, a search index, a wiki page or an agent's memory. It speeds up finding and reading, but its authority depends on where it came from, how fresh it is and how it is kept up to date. Calling it "a copy of the source" is not enough: it needs links and a date or version, otherwise nobody can check whether it still matches.

These roles can be drawn as a simple flow:

authoritative record → derived representation → search or summary → answer

If all you can see is the final sentence, with no visible path back to the first record, the answer has no verifiable provenance.

Authority depends on the question

Question	Best place to check first	What that place does not prove on its own
What code or document text is recorded at a specific revision?	The Git repository, a specific branch and commit; the file history shows the changes.	That the commit is already on the main branch, deployed, or running in production.
What need and criteria were written down for the work?	Jira: the description, acceptance criteria, owner, status and field history.	That the implementation has been merged, verified or deployed.
What exactly was proposed and discussed for the code?	The pull request: its description, the list of differences (diff), commits, comments, reviews and checks.	That the proposed change has been merged, or that production is running it.
What record does the system hold for an entity?	The relevant database or domain-record service.	That the record matches the intended policy, or that the user actually saw that record.
Which process or material is officially approved?	The document designated by its owner in Drive or the corporate document store, together with its approval status and version.	That any neighbouring document, or a screenshot of it, has the same status.
What did people say or clarify during the work?	The chat or meeting record, with author and timestamp.	That the remark was a decision, an approval or current policy.
What does the agent remember about the project?	Agent memory is only a pointer to facts that must be re-checked.	That the note is complete, current, or has the authority to change a rule.
Which version is answering right now?	Live deployment status, artifact metadata, configuration and a control observation in the right environment.	That Git history or a Jira status automatically equals the current state.

The question "what is the source of truth?" has to be sharpened into "the truth about what, for which scope, as of when?" A README.md file can be the best short description of how to run the project, yet it is no evidence of which version the live service is running. An error log can reliably show a specific failure, but it has no standing to decide what the product should do. A customer's comment is evidence of what the customer said, not necessarily formal approval of a price change.

The record card: author, version, scope and provenance

Before you rely on a document or a message, check its authority context. For an important record it helps to know:

• Author or content owner. Who wrote the text? Who is responsible for keeping it correct?
• Date and effective period. When was the record created or last reviewed? From what date does it apply? The edit date is not necessarily the approval date.
• Version. A commit, revision number, decision identifier, contract number or another stable pointer.
• Scope. Which product, customers, environment, country, team or period does the rule cover? Exceptions must be explicit too.
• Status and approval. Is this a draft, a proposal, an approved version, a rejected record or an obsolete instruction? Who approved it, and in what role?
• Access. Can the person or agent actually read the record itself, its history, its attachments and the relevant environment? A document's title in search results does not mean its content has been read.
• Provenance. Where did this extract or fact come from? A derived document needs a link to the original and a note of which version it was produced from.
• What happens on change. When the decision changes, who updates the copies, whom do they notify, or which task do they open?

A timestamp alone does not settle a dispute. Yesterday's unapproved comment does not cancel a rule approved last week. A draft with a newer date does not become policy. Conversely, an old record may still be in force if nothing has replaced it. You need to establish the status, the owner of the decision and the exact boundary of where it applies.

In Git, a commit identifier lets you name a specific snapshot of the files. GitHub's page for a file can show its history, with the author, message and date of each commit. A pull request brings together the description, discussion, commits, checks and the diff, but it is the history of a proposal and its review; to answer "what is on the main branch?" you open that branch and commit. GitHub's documentation on viewing files and their history and its documentation on pull requests describe these capabilities separately.

In Jira it is equally important to distinguish the current field from its history. A "Done" status answers the question of what status was recorded for the task in the workflow. It can be wrong, or it can run ahead of the code. The work item's history shows field changes, transitions and comments, but it does not replace checking GitHub or the running environment. Atlassian describes work item activity precisely as records of edits and transitions.

Why not keep everything in one place

No single system answers every kind of question equally well. Jira is good for work ownership, queues and status. Git is good for versions of code and documentation. A database is good for operational records with a controlled structure. A document store is good for material that is approved and shared with a wide audience. Chat suits quick clarifications. Logs suit diagnosing what the system observed. Merging all of these functions into one page does not remove the differences between them; it can simply hide them behind one big canvas.

A practical idea from Michael E. Gerber's The E-Myth Revisited is not to let operational work depend on a single person: the system and the expected way of working should be transferable. In the book's publisher description and in material from the EMyth team, this is described as a systematised way of running processes that other people can understand and maintain. For documentation, it means a valuable decision cannot live only "in the founder's head" or in a private conversation; the owner of that knowledge must be ready to keep the current record up to date and hand it on to the next person. But the conclusion is not that every movement must be documented or that you need a thousand-page bureaucratic manual. Document what recurs, what affects decisions, risks or customers, and what matters when responsibility changes hands. This is an application of Gerber's idea to team knowledge, not a claim that he proposed a particular policy for files or distributed teams.

In the second edition of Designing Data-Intensive Applications (DDIA), Martin Kleppmann and Chris Riccomini discuss systems of record and derived data, and the reasons for combining different data stores when one cannot cover every need. This makes a useful analogy for documents: an approved rule can be the primary record, while a handbook, a search index or a digest is a derived representation; if the derived version gets corrupted, it can be rebuilt from the primary record, but only if there is a clear link and clear transformation rules. You also have to think about how fresh the copy is and about the history of changes. Documentation is not a transactional database: it does not guarantee that all copies are updated atomically, that they stay consistent automatically, or that a state can be reproduced. The comparison explains the direction in which information flows; it does not promise any technical guarantee.

Copies, extracts and derived material

A copy is useful as long as the path back to its source is preserved. A summary can be shorter than the full document and easier to start from, but it must not quietly turn into a second version that people edit independently.

Choose one of three simple modes:

1. Link instead of copying. In the README or the task, give the URL of the approved record and explain which part of it matters.
2. Automatically generated copy. If a handbook is generated from the source, state the script or process, the source, its version and the generation time; edit the original source, not the generated file.
3. Manual extract. If a copy is genuinely needed, label it "derived extract", link to the source, record the source version and the date it was last reconciled, name an owner, and define the event after which the extract must be re-checked.

For example:

Derived summary of the requirements for storing customer data. Source: the approved "Data Handling" policy, revision 4, dated 2026-08-12. Source owner: Head of Security. Checked 2026-09-15. Reconcile after every policy change or before any change to data exports. Full text of the rule: see the link.

Do not maintain two "master" files in which different people can independently change the same rule. If that is unavoidable, explicitly decide where changes are made, how they reach the second system, what maximum lag is acceptable, and who catches a failed synchronisation.

The open MADR repository (Markdown Architectural Decision Records) is a concrete example of this approach applied to decisions: it recommends keeping numbered records in a docs/decisions folder, uses a separate templates folder, and keeps a changelog. The full version 4.0.0 template contains the context, the chosen option, the consequences and metadata: status, date and the people making the decision. In the changelog the authors explain that the wording "Markdown Any Decision Record" appeared in a beta version, and that release 4.0.0 went back to the original name "Markdown Architectural Decision Records". This is not a universal standard, nor proof that every team needs an architectural decision record (ADR) for every small matter; it is a verifiable example of how decisions can be versioned together with the project. Architecture Decision Records covers the practice in depth.

When sources conflict

Neither an agent nor a developer should silently pick the newest, the most convenient or the most persuasive text. The disagreement has to be made visible and resolved with the owner of the decision.

1. State the concrete question. "Which rule applies to this plan in the EU from 1 October?" is better than "Which document is correct?"
2. Record the conflict without paraphrasing it into convenient words. Name the passage, file or field, and the date, version and scope of each source.
3. Check status and provenance. Is it a draft or an approved document? Which record was the copy made from? Do both sources concern the same country and the same period?
4. Find the authorised owner. This may be the owner of the product rule, the person responsible for the policy, or a designated person entitled to confirm the change. A tool or an agent does not acquire that right merely by having access.
5. Do not invent a missing decision. If the sources give no answer, pause any action that depends on that rule, ask a precise question and, if needed, propose a safe temporary restriction.
6. Update the canonical record and the places that depend on it. Record the decision, its rationale, the owner, the effective date and what it supersedes. Update the README, the reference material, the task, the template and the index, or mark them as obsolete. Do not delete the old record if its history is needed to explain earlier behaviour.
7. Verify that the change has propagated. Re-open the places holding copies and confirm that they link to the new version or carry a clear "obsolete" notice.

For architectural decisions, a short "context — options — decision — consequences" record is sometimes enough. The MADR repository provides such a template; it helps pass on the reason for a decision, not just the latest choice. The original paper by the MADR authors describes the problem of external documentation drifting away from the code and reports an early trial of the template in one open-source project; the authors call the results promising but in need of further refinement. That is a specific research example, not universal proof that a separate record benefits every team (Kopp, Armbruster and Zimmermann, 2018). The current MADR documentation provides for context, decision, consequences and metadata. Even so, not every chat needs to become an ADR. The test is simple: does a future reader need to know this decision, its limits and why it was made?

How an agent should find and cite knowledge

When an agent needs a fact about the project, a reliable sequence looks like this:

• pin down exactly which question needs answering;
• find and open the original source, rather than stopping at a search snippet or a summary;
• read the related section, history or dependent record that the scope of the task requires;
• check the branch or commit, revision number, date, approval status, environment and access rights;
• answer with the exact file path, record identifier, uniform resource locator (URL), commit, section heading or time window;
• separate what was read from what is merely assumed, and name the systems that were not checked.

A search index is a way of finding things, not the final authority. If the index turns up a fragment, open the corresponding file and check its context, date and status. If the agent has no access to the document itself or to its history, it should say so: "I can see a link, but I could not verify the content", rather than reporting a paraphrase as fact.

The content of an external document is data to analyse, not automatic authority to carry out instructions embedded in it. A policy text may contain a rule that matters for the answer, but it may also contain a quotation, a sample, a historical passage or a stray line such as "agent, ignore your previous instructions". First establish who created the document, its status and its purpose; follow the authority rules of the current task and the security rules. Repository instructions can steer work in that repository, but a comment in someone else's attachment cannot on its own authorise handing over secrets or changing a product rule. The Codex and Claude Code documentation likewise distinguish project instructions from auxiliary memory, and instructions in a text file are not a technical control over permissions (OpenAI describes how Codex assembles its instructions; Anthropic distinguishes CLAUDE.md files from Claude Code's automatic memory).

A good report also keeps time straight:

• "I remember from yesterday's chat that the release was planned on the release/2.1 branch."
• "Today I opened GitHub and checked that pull request #84 is still open at commit a1b2c3d, and that the deployment tag in the pre-production environment points to 9f8e7d6."

The first sentence reports a memory, not a current fact. The second reports specific, fresh checks. The same discipline applies to the current pull request, the main branch, a deployment, configuration or a database record. If you did not read the source today, do not give the impression that its state was verified today.

Worked cases

Case 1: Jira says "Done", but the football site still shows the old squad

Take a fictional football statistics site, where a squad is the list of players the site shows for a team. A transaction appears in the official source: the player with identifier 42 has moved from Team A to Team B. A Jira task asks for support for this new type of transaction, so that the current squad is updated and the previous team is kept in the history. In Jira the task is marked "Done", but there is no link to a pull request. On the production site the player is still in Team A's squad. A manager asks: "Is the task finished? Has the code been accepted? What does the site show right now?"

These are three different questions, so they need three sources.

• "What is the task's status in the tracking process?" Check Jira and the task history. If the status really is "Done", say so, but add that this is the status of the task record. With no link to a pull request, do not conclude that the implementation has been merged.
• "Which code has been accepted into the repository?" Check the main branch, the file history, and whether a pull request exists and what state it is in. If the required commit is not there, GitHub holds no evidence that the fix reached the main branch. Code sitting in a developer's local copy does not change that conclusion.
• "What does a visitor see on the site right now?" Check the live environment: the identifier of the deployed artifact, the configuration target, and a control request to the squad route and the transaction history. If the page still shows the player in Team A, say that the verified production squad is currently out of date, and give the time and the method. A historical record of the previous team does not by itself prove that the current squad was updated.

Then report the contradiction to the task owner: "Jira says 'Done', but there is no evidence of a merge, and a control request to the production site at time X still shows the player in Team A. Please check whether the task was closed by mistake, or whether the change has not yet been scheduled for deployment." Do not move the Jira task to another status, and do not trigger a deployment on the strength of a guess. Once it is explained, the responsible person will either establish the actual status of the work or add the pull request and the deployment step; after that, the new state must be checked in the appropriate systems.

Conclusion: Jira answered about the task's workflow, GitHub about the code, and the production site about the current squad. None of these systems overrides the facts held by the other two.

Case 2: An approved Drive policy contradicts the README, and chat holds an unconfirmed clarification

An imaginary approved policy in Drive, revision 4, dated 12 August, says: "The 10% discount is available only on the Annual plan." The README.md says: "10% for monthly billing." In chat today, a manager wrote: "I think the customer was promised 15% regardless of plan", but neither the policy owner nor the customer has confirmed this.

First the agent records the conflict: different discount terms; two written sources; a third, unconfirmed signal in chat. Next it checks the scope of the Drive document: does the policy apply to all customers, what is its effective date, who approved it, is there a newer revision? Git shows when the README line was changed, but that gives the line no right to outrank the approved policy. The manager's message is a hint that a one-off exception may exist; it is not yet evidence of an agreement.

The agent does not apply 15%, and it does not change the policy on the customer's behalf. It puts a specific question to the policy owner and the manager: "Is there an approved exception for this customer? Who approved it, for how long, and where is it recorded? Are we changing the general rule or adding an exception for this customer only?" Until there is an answer, the safe course for both the code and the reply to the customer is not to promise terms that are absent from the approved source.

Once an authorised person confirms, the team records either the individual exception in the contracts or customer-records system, or a new revision of the general policy in Drive. The README gets a link and a short, agreed summary. If a Jira item affects the implementation, its criteria are updated too. The old revision is not overwritten: it is marked to show exactly what replaced it and from which date. If confirmation never comes, the matter stays an open decision, not a fact the agent "logically" inferred from chat.

Case 3: The agent's summary left out a ban on personal data

Suppose a previous agent session left a handy summary: "Export a sample of customers to a spreadsheet to investigate subscription cancellations." The summary does not mention a constraint: the security policy forbids downloading names, email addresses and other personal data into personal spreadsheets. In the new session the agent sees a Jira task about analysing why customers cancel, together with the old summary.

Before exporting anything, the agent opens the current approved policy and, if they exist, the repository instructions or the instructions of the data-system owner. It checks which fields are actually needed, the environment, and the approved way of accessing the data. If the restriction really does cover this sample, the agent does not download personal data into a personal file. It looks for a permitted aggregated or pseudonymised dataset in the approved working environment; if no such route is confirmed, it asks the policy owner before processing any data.

In its report the agent says plainly: "The previous summary did not include the restriction on personal data. Before acting, I re-read policy revision X dated Y. No personal export was made. To continue, an approved dataset or environment is needed." The owner of that knowledge can then fix the handoff template and, if it makes sense, add a link to the policy in memory. Such a note reduces the chance of the restriction being missed again, but the next agent must still check the current rule.

Conclusion: a summary helps you carry on with the work; it does not override the policy in force, and it does not grant access to personal data.

Case 4: Cancellation analytics without a personal export

The team wants to find out why customers cancel their subscriptions. A Jira task asks for a sample of customers to be exported, but does not define which fields are allowed. The approved policy forbids keeping names and addresses in personal spreadsheets; the approved analytics environment has a dataset of aggregated or pseudonymised data. Check the scope of the policy, the fields in the dataset and the permissions of the environment. Use only confirmed data within that environment; if the conditions or the risk of re-identification are unclear, ask the data owner before exporting. In the report, name the policy revision that was checked and which data was actually used.

A minimal knowledge-ownership policy

A team needs only a few short agreements, answering four questions:

What to decide	Minimal rule
Where does it live?	Requirements and task status in Jira; versions of code and development documentation in Git; discussion and review of a change in the pull request; domain records in the designated database or service; approved working or customer-facing material in the designated Drive folder; any agreement that must be remembered for longer than a chat lasts, in a canonical record that the chat links to.
Who can approve or change it?	Name the owner of the rule and a deputy. Whoever does the work can propose text but does not stand in for approval. For a technical decision, name a reviewer or a team.
When is it updated?	After a change to policy, acceptance criteria, code, data schema, application programming interface (API), deployment or procedure, update the corresponding derived records. In every primary document, list the events that trigger a review.
How are copies corrected?	A derived record carries a link, the source version and an owner; after the canonical record changes, it is either synchronised automatically or checked against an explicit list. If a copy has not yet been updated, mark it obsolete rather than passing it off as current.

You do not need a separate full manual for every change. A small bug fix may need nothing more than a task and a pull request. An exception to a policy, a change to a contract or a long-lived decision deserves its own record, with context, authority and a date. The job of handing work over between people, agents and sessions is to pass on not every historical message but the goal, the actual state, the open decisions and links to the sources. The repository as a knowledge system covers how to find your way around a repository; this unit explains why finding a file does not yet confirm that it is current.

Summary

"Source of truth" only makes sense with qualifiers: the source for which claim, which scope and which moment. A system of record holds the authoritative records of its kind; runtime state shows what is working now; a log helps reconstruct history; a convenience copy helps you find your way but can go stale.

Requirements, code, implementation discussion, domain data, approved material, working conversation and agent memory all play different roles. Author, date, version, scope, approval, access and provenance explain why a record can be trusted for a particular question. Newer text does not automatically replace an older approved decision; a draft does not become policy just because of its date.

When sources disagree, show the exact conflict and go to the owner of the decision. Once it is confirmed, record the decision in the canonical place, refresh the links and derived material, and keep the history. An agent should open the original source, check its state and its own access, cite the exact version, and tell yesterday's memory apart from today's check.

Sources and further reading

Online documentation that may change was checked between 23 and 26 September 2026; where a source shows no publication date or version, this is noted. The conflict examples and all Jira, GitHub, Drive, database and production records in this unit are fictional and for teaching only.

1. GitHub, About Git, current documentation with no visible publication date; checked 26 September 2026. Used to explain that a repository holds files and their revision history, and that a Git source should be named together with its branch and commit.
2. GitHub, Viewing and understanding files, current documentation with no visible publication date; checked 26 September 2026. Used for the ability to view a raw file, line history (blame), and file history with the author, message and date of each commit.
3. GitHub, Pull requests, current documentation with no visible publication date; checked 26 September 2026. Describes a pull request as a proposal with discussion and review, with tabs for commits, checks and changed files.
4. Atlassian, What are the different types of activity on a work item?, current Jira Cloud documentation with no visible publication date; checked 26 September 2026. Used to distinguish comments, edit history, transitions and the work log. This describes Jira Cloud; it is no guarantee that an entered status is correct.
5. OpenAI, Michael Bolin, Unrolling the Codex agent loop, 23 January 2026; checked 23 September 2026. Describes how Codex assembles instructions, including AGENTS.md, and their size and order. This is a specific description of Codex as of the publication date, not the universal behaviour of every agent.
6. OpenAI Developers, Eric Provencher, Rethinking skills and prompts for GPT-6 Astra, 11 September 2026; checked 23 September 2026. Used for the principle of targeted reading of repository instructions and regular review of outdated rules; this is OpenAI's recommendation for the named model family, not an independent experiment.
7. Anthropic, How Claude remembers your project, current documentation with no visible publication date or version; checked 23 September 2026. Describes the difference between CLAUDE.md instructions and automatic memory, their scope and how they are loaded. Claude Code settings should not be assumed to carry over to other agents.
8. Gerber, Michael E., The E-Myth Revisited: Why Most Small Businesses Don't Work and What to Do About It, revised and updated edition / reissue, HarperCollins, 2009, 288 pp., Google Books record; book page. The bibliographic data and the limited edition description were reviewed, not the full text; full access to the book was not available here. For a practical explanation of systematising a process, the undated EMyth team article Create your Small Business Prototype and the undated overview 3 Groundbreaking Ideas from "The E-Myth Revisited" were also checked. These are EMyth team materials, not a separate quotation from Gerber himself. Extending the idea of systematised processes to documentation ownership is this unit's own conclusion.
9. Kleppmann, Martin, and Chris Riccomini, Designing Data-Intensive Applications, 2nd edition, O'Reilly Media, February 2026, International Standard Book Number (ISBN) 9781098119058; book page and available preview of the opening chapter, checked 26 September 2026. The reviewed excerpt and table of contents were used to confirm the discussion of trade-offs between different data stores and the section title "Systems of Record and Derived Data"; the full text was not available for this research, so conclusions are limited to the available preview. The derived-documentation example is an analogy to the book's terms, not a promise of transactional consistency for documents.
10. Kopp, Oliver, Anita Armbruster, and Olaf Zimmermann, "Markdown Architectural Decision Records: Format and Tool Support", Proceedings of the 10th Central European Workshop on Services and their Composition (ZEUS), Dresden, 8–9 February 2018, pp. 55–62; publication metadata checked 26 September 2026. A scholarly description of a structured architectural decision record. For the current example, MADR release 4.0.0, the README at that tag, the full template and the minimal template were used; checked 23 September 2026. The history of the name was checked against the changelog. This version and one public template are an example, not a norm for every team.

Limits of the sources and conclusions. The GitHub, Jira, OpenAI and Anthropic documentation describes the capabilities and behaviour of their own products in the versions current at the time of review; it does not prove that any particular file, status, environment or integration in a project is current. The bibliographic data and the openly available EMyth materials are not the same as a full reading of The E-Myth Revisited. The available table of contents and excerpt of DDIA 2 do not replace the full text; the comparison with documentation is deliberately limited to the ideas of a primary record, a derived representation and freshness. The MADR repository is one public example, not empirical proof that an ADR is better for every decision.