Source-of-Truth Map

This file explains which ICN sources outrank which other sources when repo material disagrees. It is an orientation and triage map, not a replacement for current state docs, code, ADRs, RFCs, or tests.

ICN has a large documentation and implementation surface. Some files are current implementation truth. Some are current architecture direction. Some are historical archaeology. Some are package-local. Some are generated. Some are deliberately aspirational.

The point of this map is simple:

Do not let old, detailed, or rhetorically strong documents outrank current code, current state docs, accepted decisions, and recent evidence.

Canonical hierarchy

When two sources appear to disagree, use this hierarchy by default.

Decision status vocabulary

Use the document front matter and local wording before treating a source as normative.

Current truth anchors

These are the first files to inspect before making claims about ICN’s current state.

Conflict rules

Code vs docs

If code/tests and docs disagree, prefer code/tests for implemented behavior and open a docs truth-sync issue or PR.

Do not assume the docs are wrong about intent. They may describe the intended direction. But do not describe intended direction as shipped behavior.

State docs vs project-index maps

If STATE.md / PHASE_PROGRESS.md and a project-index map disagree, prefer the state docs. Then update the map.

Project-index files are routing maps. They should be short and current enough to orient readers, but they are not the ledger of truth.

Accepted ADR/RFC vs proposed ADR/RFC

Accepted decisions define constraints. Proposed/draft ADRs and RFCs describe design direction.

When discussing proposed material, say so explicitly:

proposed, not implemented
accepted, not fully implemented
implemented but partial
implemented and exercised

Standalone NYCN repo vs ICN institutions/nycn/

Treat the standalone InterCooperative-Network/nycn repo as the active NYCN package/rehearsal home unless a current ICN state doc or follow-up reconciliation PR says otherwise.

Treat ICN institutions/nycn/ as boundary-sensitive scaffold / package-local material that needs explicit reconciliation before being treated as current operational truth.

Demo fixtures vs live state

Demo fixtures are fictional and deterministic. They prove UI/demo rendering and contract shape. They do not prove live participant state, live federation, production readiness, or formal NYCN pilot status.

Historical archive vs current doctrine

Historical archive material can contain valuable invariants, tests, and doctrine. It does not become current truth until hand-ported, reviewed, and merged against current main.

This applies especially to preserved WIP branches and old planning waves.

Required labels in summaries

When summarizing a subsystem, use one of these labels.

Overclaim guardrails

Do not claim any of the following unless current state docs and runtime evidence explicitly support it:

• ICN is production-ready.
• NYCN is a formal pilot.
• Live federation is deployed.
• Backend --demo-mode exists for the full stack.
• Demo fixtures are real participant state.
• Private-overlay activation has happened.
• ICN stores private partner data in public repos.
• CCL institutional-process language is implemented.
• External settlement bridge primitives are implemented beyond their accepted/draft design state.
• Tool Commons services are installable / live.
• Service hosting is ICN-native.
• Compute outputs decide governance outcomes.

Update procedure

Update this file when:

• a new canonical state source is introduced;
• a project-index map becomes stale enough to misroute readers;
• NYCN package/source-of-truth ownership changes;
• a design-direction doc is promoted to accepted ADR/RFC or implementation;
• a stale/historical document is archived, ported, or explicitly superseded;
• a new repo or major subsystem joins the ICN project family.

When in doubt, update the truth-bearing source first, then update this map.

Relationship to adjacent maps