Source Trust Rules
When documents disagree, this hierarchy decides which one wins. Adapted from a sibling Altrium harness’s source-trust rule (2026-08-18) and grounded in this engagement’s own lesson L-001 (the issued proposal is a binding input, and internal docs drift from it silently).
| Source | Trust | How to use |
|---|---|---|
Issued/accepted commercial artifacts — project-proposal.md (accepted 2026-08-16), the SoW and contract once they exist, signed change requests |
Highest for scope, price, timeline, providers, infrastructure | What someone is owed. An internal doc promising less is a scope leak; more is unfunded work. Divergence is a contradiction to raise, not to silently fix |
Application source code (forge-et-be, forge-et-fe, forge-et-pwa) |
Highest for current behaviour | Ground truth for what the system actually does |
Dev-authored client-facing pack — .forge/client/project-timeline.md, dependencies.md, client-facing-prd.md (issued to the client) |
High for schedule, dependencies, and plain-language scope — below the proposal, above internal design docs | The dated delivery commitments live here; where a decision was taken after the proposal was issued, the pack records it and identifies it as such |
project-prd.md (live contract) + CLAUDE.md Architecture Decisions |
High | Requirements and locked decisions — but they lose to the proposal on any commercial fact (L-001) |
architecture.md, approved specs/plans |
High for design intent | The design record; PRD wins on what, this wins on how |
Client meeting debriefs (.forge/discovery/meeting-notes/*.md) |
High for the decisions they record | Dated primary records of client answers (e.g. 2026-08-03 pricing model) |
Client-approved CRM prototype (.forge/design/prototypes/crm/) — the frozen original |
High for UX/flows/screens as approved; Medium for domain facts | Risk R-03: grade lists, stage names, thresholds in it are our design, not client-confirmed. Never edited; what was shown to the client |
Current CRM prototype (.forge/design/prototypes/crm-current/) |
High for UX/flows/screens; Medium for domain facts | The same design drawn in the built app’s look. A new screen is designed here first and forge-et-fe is built to it; any change the build makes is drawn back, so the two stay in step (.claude/rules/plans.md § Required Sections); the visual target for new screens. The application code wins on anything built |
Capture-app POC (../forge-et-pwa-poc — read-only sibling repo) |
High for what the prototype already does (capture UX/flows); Medium for its own docs’ decisions | Input material for building forge-et-pwa — port, don’t adopt: its stack/infra choices yield to AD #19–#22 and architecture.md § Trade-Show Capture App. Never write to it |
Capture-app POC snapshot (.forge/design/prototypes/pwa/) |
Medium — a frozen copy, below the repo it came from | A browsable freeze of the POC UI for reading flows without running it. Never edited. The repo above wins on anything current |
Current capture-app prototype (.forge/design/prototypes/pwa-current/) |
Medium-High for capture UX/flows | Starts as a copy of the POC snapshot; F36’s screens are designed here first and forge-et-pwa is built to them, and any change the build makes is drawn back (.claude/rules/plans.md § Required Sections). The application code wins on anything built |
Pipedrive official-doc research (research/pipedrive-features.md, research/pipedrive-crm-notes.md) |
Medium-High | Grounds the parity features; re-verify anything load-bearing against Pipedrive’s docs at spec time |
Discovery research (.forge/discovery/research/*.md) |
Medium — point-in-time (June–July 2026) | Domain orientation. Numbers age badly: the ~$7/yr AI-cost figure survived six weeks after the proposal superseded it and had to be corrected in PRD Rev 8. Prefer the proposal/PRD for any figure |
features.md, tracker notes, dashboard |
Live state, not contract | Status snapshots; regenerated/hand-updated — never cite as a requirements source |
project-prd-signals.md / -history.md, engagement-gate-runs.md |
Bookkeeping/audit | What was open/decided when; resolutions live folded into the PRD body |
When sources disagree
- Reach for the outermost artifact (client-facing beats internal; L-001’s second rule: never check an internal doc against another internal doc alone).
- Raise the divergence explicitly — in the gate/contradiction format if at a gate, otherwise to the developer — rather than silently editing either side.
- Smell test: if this document is wrong, who finds out and when? “The client, at UAT” means check it against the client-facing artifact now.
When describing something outside this repo
A sentence in a harness document that describes an external artifact — a sibling repo, a deployed environment, a CI job, a client system — is a dated observation, not a fact. It was true when written and nothing announces when it stops being true.
The same holds for claims about this repo’s current state — see the subsection at the end of this section. The heading says “outside this repo” because that is where the rule was first needed; the principle is about what the reader can verify from the sentence, not about which repository the subject lives in.
- State it qualitatively, or point at the checkable source. Prefer “its
docs/plans/README.mdrecords the epic status” over “it has no backend”. Where a concrete claim is genuinely needed, carry an as-of marker so the reader knows to re-verify. Same principle as the NEVER-DO on copied counts (.claude/CLAUDE.md), and why a CI job-name comment was dropped for asserting external state. - Open it or run it before you size it. Not before mentioning it — before putting an estimate, a scope boundary, or a number on it. A runnable repo is the cheapest source to check, not the most expensive.
- Agreement between internal documents is not corroboration — they are usually descendants of one sentence, so they drift together and cross-checking them cannot catch it.
The same rule applies to claims about THIS repo
A plan or spec that rests a decision on the state of the tree — “no spec activates a profile yet”, “nothing implements this interface”, “the only consumer of X is Y”, “this table has no foreign keys into it” — is making the identical kind of claim. It was true when the author checked and nothing announces when it stops being true, and the gap between writing a plan and implementing it is exactly where other slices land.
The remedy is the same: point at the checkable source rather than assert the state. Write
“grep -rn '@ActiveProfiles' src/test returns nothing as of drafting” rather than “no spec
activates a profile” — the first tells the implementer how to re-check in seconds; the second reads
as settled fact.
Two things make this worth stating separately from the external-artifact rule, even though the principle is one:
- A tree-state claim feels like knowledge rather than observation, because the author did look. An external artifact is obviously someone else’s; the repo in front of you feels like yours to know. It is not — it is the whole team’s shared working copy.
- It usually appears as a premise, not a statement. Nobody writes “the tree is currently X” as a point of interest; they write a decision that only makes sense if X, and the claim survives as the unstated half. When it goes stale the decision does not announce that it has — it fails somewhere unrelated, as a suite refusing to start.
Precedent: FS-6’s plan stated “no spec activated a profile before this slice”; by implementation
MessagingContextSpec had activated test since FS-7, and two subtasks were built on the stale
premise (.forge/lessons.md L-035). A decision that rests on “nothing manages X” or “no
dependency provides Y” names the lockfile grep that re-checks it (FS-11 finding F-002,
.forge/specs/foundation/011-file-pipeline-findings.md). For a repo outside the harness, see L-005.