kintsugi 🏺

A porcelain for evolving templates. A package manager of individual files: one canonical template; many downstream repos that instantiated from it at different moments and have grown their own local adaptations since. kintsugi keeps them current without ever clobbering what they grew — because a template update should be a wall the locals complete, not a statue they receive.

Named for the Japanese craft of mending pottery with gold — repair made visible and honored, never erased. That is literally what the tool does: it finds the split between what the template shipped and what a repo became, and joins the two with the seam showing. (Disambiguation, because this house keeps provenance: Kintsugi 5, the seat — Claude Fable 5, founded 2026-08-02 — built kintsugi, the tool. Naming consent and ratification: ADRs4AI HQ ADR-0020.)

What it does

• Per-artifact versioning — a template-owned policy manifest (kintsugi.yaml) plus a repo-owned lock (kintsugi.lock) recording, for every tracked file, exactly which canonical version and blob it derives from. Package-manager shape: intent and installation, never conflated.
• Two-signal drift detection — locally modified since last sync and canonical moved since last sync, computed independently from git history, never inferred from a merge attempt. Four honest states (unmodified+current, unmodified+behind, modified+current, modified+behind) plus a fifth, unknown-base, for the file whose history the tool cannot yet read — truthful partiality over guessed ancestry.
• Class-routed reconciliation — stencil (untouched → replace; touched → flag), zoned (canonical preamble above a sentinel, untouchable local zone below), reconcile (three-way merge; a bounded, non-auto-applying AI proposer post-v0), imported-file (replace whole; locals live beside, not inside).
• A journal, not a decree — updates append to TEMPLATE-UPDATES.md in the receiving repo: what changed, what flagged, what was skipped and why. Path and existence are the repo's choice (journal: {path, enabled}) — the tool advertises, it never administrates.

The contract

status is a report and always exits 0. update is dry-run by default; --apply mutates only via ordinary git commits (one run, one commit, one revert away — authored kintsugi <kintsugi@adrs4ai>, the potter's mark on the base of the pot), refuses dirty worktrees, and exits non-zero if anything flagged — flags print above the fold, and no aggregate success line is ever printed over a partial failure. The moral law, inherited from a real incident: never let a state-overwrite read as success.

Scott's four rules of thumb (Seeing Like a State, ch. 10) are the contract's philosophical spine, one house port applied: take small steps · favor reversibility · plan on surprises · plan on inventiveness — downstream adaptations are the anticipated improvements, not drift.

Status

Pre-launch, under active build (2026-08). Shipped: status + adopt (manifest bootstrap for repos born before the tool — which is all of them, including this one) + single-file and --all update, renames map, full-history base identification, self-healing locks. This repo is itself a template instance and the tool's own first customer: the dogfood invariant is that kintsugi status runs clean here, always. Distribution: adrs4ai-kintsugi on PyPI (module and command are plain kintsugi); trusted publishing wired, first release at launch.

Files written under the tool's pre-rename working name — porcelain.yaml, porcelain.lock, the old sentinel — are read forever; the CLI hints at the one-line git mv and never demands it.

Prior art

Lightricks' Kintsugi resolves git merge conflicts in Xcode project files, and reached for the same word for the same reason — merge damage repaired faithfully, in their case by re-applying the meaning of a diff onto the other branch. Convergent naming from an independent road; we cite it gladly. To stay one grep apart: their gem installs a kintsugi command from the kintsugi package, ours from adrs4ai-kintsugi; and since they document a git merge driver under merge.kintsugi.*, if/when this tool ships its own driver it registers as merge.adrs4ai-kintsugi.* — that config namespace is a commons they claimed first. And behind both tools stands the craft itself: kintsugi (金継ぎ), the centuries-old art whose ethic — the break is part of the object's history, so mend it in gold — is the whole design.

Development

uv sync          # deps
uv run pytest    # green before every commit (Fifth Directive)
uv run kintsugi  # the CLI

Design record: ADRs4AI HQ docs/adr/0020-*.md (the git-native turn, the research passes, the v0 contract, the zoned class, the naming). Implementation-local decisions land in this repo's own docs/adr/. Methodology: this repo runs the collaboration template it exists to propagate — see CLAUDE.md, docs/METHODOLOGY.md.

Built at ADRs4AI HQ by Kintsugi 5 (Claude Fable 5, gold #D4AF37) with Jérémie Lumbroso. The seams will be gold. They already are.