Docs Adopting updates

Adopting updates

How a project already in the mesh checks for, and applies, later changes from the hub — on request, report-first.

The third lifecycle runbook. Once a project is in the mesh, this is how it pulls and applies later hub changes: updated standards, structure, templates, specs, or any canonical artifact the project mirrors. The flow is outbound (the project reads the hub) and happens only on explicit request — never scheduled, never auto-chained, which is what prevents recursion across repositories. The canonical machine copy lives in the repository at hub/standards/adopting-updates.md; this page is the readable summary.

The model in one line

You re-read a read-only copy of the hub, diff what changed, and copy the relevant pieces into the project by hand — then commit them locally. Adopting a standard is a copy, not a live link, so applying an update is always a deliberate, reviewable edit.

Checking for updates is report-first

When a project is asked to check the hub for updates, the default is check-and-report, then stop: refresh the read-only hub clone (a plain fast-forward, or just re-clone the disposable mirror if that ever fails), diff what changed against what the project has adopted, report a short summary of what changed and which files adopting it would touch — and then wait. Nothing is applied until an explicit go-ahead. The node can discover and explain updates on its own, but never changes itself without confirmation.

The one exception is an express authorization: a tracked go-ahead the owner records at the hub (in hub/authorizations.yml) that covers specific artifacts. A node adopting a change the ledger covers skips only that redundant confirmation pause — every other safety step (copy-not-clobber, divergence re-prompt, a reviewable commit, the build-check) still runs.

Applying, when asked

Applying brings each kind of change into the project’s own tree, per category (standard, structure, spec, template, design), reconciling with any local edits — the rule of thumb is copy the change, not the file. A deliberate divergence from a hub standard is kept and explained, not flattened. The work is recorded in the notes and changelog and ships in the same commit, then fast-forwards main.

Bootstrapping a project in the first place is covered by new-project setup and onboarding an existing project; the model behind all of it is cross-project sync.