source: .claude/rules/source-trust.md · generated — edit the markdown, not this file

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.md records 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.

Generated from .claude/rules/source-trust.md by .claude/lib/render-docs-html.js. Markdown is canonical.