Canonical Core

This repository is the canonical core — the single, versioned model of the company from which all operational artefacts derive. It is read by humans and by AI. Both are first-class consumers.

The corpus/canonical-core domain contains the specification that governs this repository. Start there.

---

Structure

Range	Domain
000–019	Canonical core
020–039	Strategic
040–099	Commercial
100–149	Brand
150–199	Legal
200–299	People
300–399	Process
400–499	Technical
500–699	Product
700–899	Reserved — no files, available for company-specific domains
_meta/	Index, logs, gap catalogue — outside the number sequence
_retired/	Superseded nodes — outside the number sequence

Each file in corpus/ is a node. Every node has a frontmatter block declaring its type, owner, version, status, and derivation relationships. See corpus/canonical-core/spec.md for the full schema.

---

How to propose a change

1. Branch from main
2. Edit or create the relevant node(s)
3. Update derives-from, conflicts-with, or supersedes in frontmatter if relationships have changed
4. Open a pull request with a description of what changed and why
5. The domain owner reviews and merges — or escalates if the change affects a node in another domain

Changes to nodes in corpus/canonical-core require review by a corpus shaper (see corpus/people/roles/corpus-shaper.md).

No node is edited directly on main. The git history is the event log.

---

If you have forked this repo

Forks accumulate two kinds of change: framework improvements (changes to corpus/canonical-core/ that would benefit any company using this system) and company content (everything in the other domain folders, which is yours alone).

The discipline that keeps these separable is simple: when working in corpus/canonical-core/, keep it in its own commit — no company-domain changes in the same commit. This makes framework improvements cherry-pickable back to upstream without carrying company-specific content with them.

Setup

git remote add upstream https://github.com/hiddenvalues/canonical-core.git

Pull framework improvements from upstream into your fork

git fetch upstream
git merge upstream/main

Push a framework improvement back to upstream

# Find the commit hash of the isolated framework change
git log --oneline corpus/canonical-core/

# In a local checkout of upstream, cherry-pick it
git cherry-pick <commit-hash>

# Then open a PR to hiddenvalues/canonical-core

What belongs upstream

Change	Upstream?
Governance, landscape, or other companion doc completed	Yes
Spec clarification or correction	Yes
Node template improved or extended	Yes — upstream first, then merge down to fork
New resolution benchmark example	Yes
New generalisable domain added (e.g. /partnerships)	Upstream the empty stub; keep company content in the fork
Any node in /strategic, /commercial, /product, or other company domains	No

When in doubt: if the change would make the framework more useful to a company that is not yours, it belongs upstream.