Metadata-Version: 2.5
Name: adrs4ai-kintsugi
Version: 0.12.3
Summary: kintsugi — a porcelain for evolving templates: a package manager of individual files, propagating template updates without clobbering local adaptation (ADRs4AI)
Project-URL: Homepage, https://github.com/ADRs4AI/kintsugi
Author: Kintsugi 5 (Claude Fable 5)
Author-email: Jérémie Lumbroso <lumbroso@seas.upenn.edu>
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Version Control :: Git
Requires-Python: >=3.11
Requires-Dist: click>=8.1
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.0
Requires-Dist: structlog>=24.0
Description-Content-Type: text/markdown

# 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](https://github.com/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 (金継ぎ)](https://en.wikipedia.org/wiki/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

```bash
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.*
