diff --git a/.claude/commands/upgrade.md b/.claude/commands/upgrade.md
new file mode 100644
index 0000000..7bcad13
--- /dev/null
+++ b/.claude/commands/upgrade.md
@@ -0,0 +1,146 @@
+---
+description: Upgrade an already-adopted agentic-dev-kit installation to the current kit — migrate the config schema, refresh kit-owned engines, and diff anything that drifted. The counterpart to /adopt (first install) and to re-running ./init.sh (config only). Use when pulling a kit update into a repo that already has the kit.
+argument-hint: "[--dry-run]"
+---
+
+Upgrade this repo's agentic-dev-kit installation. Non-destructive: runs on a branch, and
+never replaces a file without knowing it is safe to replace.
+
+> **The invariant this rests on.** Engines are **kit-owned**; config is **adopter-owned**.
+> Everything project-specific — paths, tracker, review-bot markers, CI policy, model
+> tiers — lives in `config/dev-model.yaml`, so an engine should never need editing to
+> adopt it. That is what makes an upgrade a file copy instead of a manual merge. If this
+> run finds engines you had to edit, that is a **kit bug**: report it rather than
+> carrying the patch forward.
+
+## Step 0 — Establish what shape this repo is in
+
+Four shapes exist in the wild and they need different handling. Determine which:
+
+```bash
+ls config/dev-model.yaml 2>/dev/null && echo "has config" || echo "NO CONFIG"
+```
+
+- **No `config/dev-model.yaml`** → this repo predates the config surface entirely (a kit
+  *ancestor*, or a partial hand-install). **Stop and run `/adopt` instead** — there is no
+  schema to migrate from. Say so plainly rather than guessing a config into existence.
+- **Config present** → continue. `kit.version` tells you the schema generation; its
+  absence means v1 (pre-`runtime:`, pre-`models.tiers`).
+
+Also fetch the kit you are upgrading *to*, if it isn't already local:
+
+```bash
+git clone --depth 1 https://github.com/topij/agentic-dev-kit /tmp/agentic-dev-kit
+```
+
+Everything below copies **from** that checkout **into** this repo.
+
+## Step 1 — Diff the installation (read-only)
+
+```bash
+uv run <engine-dir>/kit_doctor.py --manifest /tmp/agentic-dev-kit/kit-manifest.json
+```
+
+Read `<engine-dir>` from `paths.engines`. If `kit_doctor.py` isn't installed yet, run the
+kit's copy against this repo: `uv run /tmp/agentic-dev-kit/scripts/kit_doctor.py --root .
+--manifest /tmp/agentic-dev-kit/kit-manifest.json`.
+
+The report gives you, per kit-owned file: `unchanged` / `differs` / `missing` /
+`unknown-version`, plus four installation-level checks. **Read all four** — each is a
+silent failure mode:
+
+- **config schema version** — unversioned or behind means migrations are pending.
+- **`paths.engines` resolves to a directory that actually holds engines.** A `✗` here is
+  the live breakage where every workflow's `<engine-dir>/…` reference points at nothing.
+  Nothing else validates this value, so nothing else would have told you.
+- **pre-push hook installed** — a shipped-but-uninstalled hook binds nothing.
+- **narrative docs rendered** — a doc still carrying `devkit-template: unrendered` means
+  the adoption never completed its seeding step.
+
+`differs` deliberately does **not** claim a cause: a hash mismatch cannot distinguish
+"older kit version" from "hand-edited". The report narrows it by schema version; you
+confirm with an actual diff in Step 3.
+
+## Step 2 — Migrate the config (idempotent)
+
+```bash
+./init.sh
+```
+
+This is the supported config upgrade path, and it is safe to re-run any number of times.
+It only ever **adds** missing keys, never guesses over an existing value; it probes
+`paths.engines` from where engines actually are rather than defaulting; it stamps
+`kit.version`; it installs the pre-push hook as a shim (honoring `core.hooksPath`); and
+it leaves a narrative doc that is genuinely in use byte-identical, re-rendering only one
+that still carries the unrendered marker.
+
+Press Enter through every prompt to keep current values. Then re-read the diff of
+`config/dev-model.yaml` and confirm nothing you rely on changed.
+
+## Step 3 — Refresh engines, by state
+
+Work through `kit_doctor`'s file list. **Branch first:**
+
+```bash
+git checkout -b chore/kit-upgrade
+```
+
+- **`unchanged`** → copy the new version straight in. It is provably untouched, so there
+  is nothing to lose.
+- **`missing`** → decide, don't assume. A sized-down adoption omits engines deliberately
+  (one surveyed repo installs 2 of 6 on purpose). Ask the operator whether each missing
+  piece is wanted before installing it. If a piece stays out, note it in the PR body so
+  the next upgrade doesn't re-litigate it.
+- **`differs`** → `diff` the local file against the kit's, and read the diff:
+  - Only kit-authored changes (the local copy is simply older) → replace it.
+  - Local edits present → for each, find where that value now lives in
+    `config/dev-model.yaml` and move it there, then take the kit's engine. If there is no
+    config key for it, **stop**: that is the kit bug the invariant above describes. File
+    it upstream and keep the local patch, clearly flagged, until it lands.
+  - **Local edits that are genuinely ahead of the kit** — a fix made here first — are the
+    one case to route *upstream* instead: open a PR against the kit rather than
+    overwriting your better version.
+- **`unknown-version`** → the manifest has no entry, so drift is unjudgeable. Treat as
+  `differs` and diff by hand.
+
+Never batch-replace the whole list because most of it was `unchanged`. The `differs`
+entries are exactly where the risk is.
+
+## Step 4 — Refresh the non-engine pieces
+
+- **Shared workflows** (`docs/agentic-dev-kit/workflows/`) — same state logic as engines.
+  These are prompts an agent reads verbatim; a stale one silently teaches old behavior.
+- **Runtime adapters** (`.claude/commands/`, `.agents/skills/`) — install any the kit has
+  that this repo lacks; keep the adopter's version where one already exists.
+- **Templates** (`docs/templates/`) — refresh freely; the *rendered* docs are yours and
+  are never touched.
+- **`.claude/settings.json`** — if this repo has its own, **merge** the kit's hooks and
+  permissions into it rather than replacing; it likely carries project-specific entries.
+
+## Step 5 — Verify
+
+```bash
+uv run <engine-dir>/kit_doctor.py --manifest /tmp/agentic-dev-kit/kit-manifest.json
+python -m pytest <engine-dir>/lib/state_paths/tests <engine-dir>/tests -q
+uv run <engine-dir>/check_doc_budget.py
+```
+
+`kit_doctor` should now report zero `differs` and zero `unknown-version`, with `missing`
+containing only deliberately-omitted pieces. Anything else means Step 3 left something.
+
+> **Known gotcha:** the `state_paths` tests fail when run from inside a worktree carrying
+> a `.devkit_state_root` marker — the fixture neutralizes the environment but not marker
+> discovery. Run the gate from the main checkout, and see kit issue #10.
+
+## Step 6 — Record the friction, then hand off
+
+Append anything this upgrade surfaced to the friction log (`paths.friction_log`) — an
+engine you had to edit, a config key that didn't exist, a `missing` piece the report
+couldn't classify. Tag `[kit]` on anything that is a kit-side fix and open an issue
+upstream. That is Principle #2 applied to the kit itself, and it is how the four shapes
+this skill handles were discovered in the first place.
+
+Open a **draft PR** summarizing: schema version before → after, which engines were
+refreshed / diffed / deliberately skipped, and any local-edit-vs-config resolution you
+made. Leave the merge to the operator — an upgrade touches the machinery every other
+workflow runs on.
diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
index bb6c830..14ff6f1 100644
--- a/.github/workflows/test.yml
+++ b/.github/workflows/test.yml
@@ -24,6 +24,11 @@ jobs:
         run: test -x init.sh
       - name: Run state and portability tests
         run: python -m pytest scripts/lib/state_paths/tests scripts/tests -q
+      - name: kit-manifest.json must be in sync
+        # A stale manifest silently degrades every adopter's drift report to
+        # "unknown-version", so the self-check is a gate, not a convenience.
+        # Stdlib-only by design, so no uv needed here.
+        run: python scripts/kit_doctor.py
       - name: Engines must work without PyYAML
         # The stdlib config reader exists so engines carry no third-party
         # dependency. Prove it in an env where PyYAML genuinely is not installed.
diff --git a/README.md b/README.md
index 7fb666e..9d4228b 100644
--- a/README.md
+++ b/README.md
@@ -127,6 +127,40 @@ path, and it is safe to run any number of times:
   lives in `config/dev-model.yaml`, so you should never need to edit an engine to
   adopt it. If you have, that's a bug — please report it.
 
+### Which files actually drifted — `kit_doctor`
+
+Re-running `init.sh` handles the config. For the **engines**, the problem is that a
+copy-in has no version marker and no record of whether it was edited, so nothing can
+tell an older engine from a locally-patched one:
+
+```sh
+uv run scripts/kit_doctor.py     # or: python scripts/kit_doctor.py — stdlib only
+```
+
+Per kit-owned file it reports `unchanged` (safe to replace outright), `differs` (diff
+before replacing), `missing`, or `unknown-version`. `differs` deliberately does **not**
+claim a cause — a hash mismatch can't distinguish "older version" from "hand-edited", so
+it narrows by schema version and leaves the call to you. Adopter-owned paths (your
+config, your narrative docs) are never compared; they're *supposed* to differ.
+
+It also checks four things nothing else validates:
+
+- your config's schema generation vs. the kit's
+- that **`paths.engines` points at a directory that actually holds engines** — a `✗` here
+  is the silent breakage where every workflow's `<engine-dir>/…` reference resolves to
+  nothing
+- that the pre-push hook is installed, not merely shipped
+- that the narrative docs were rendered, not left as unrendered templates
+
+`kit-manifest.json` is the hash set it compares against, regenerated at release
+(`--generate-manifest`) and gated in CI so it can't go stale.
+
+**[`/upgrade`](.claude/commands/upgrade.md)** drives the whole sequence — shape detection,
+config migration, then per-file refresh keyed on those states — non-destructively, on a
+branch. It's the counterpart to [`/adopt`](.claude/commands/adopt.md) (first install). A
+repo with no `config/dev-model.yaml` at all predates the config surface and routes to
+`/adopt` instead.
+
 ### Agent runtime adapters
 
 The workflow definitions under `docs/agentic-dev-kit/workflows/` are shared. The
diff --git a/kit-manifest.json b/kit-manifest.json
new file mode 100644
index 0000000..9d06c12
--- /dev/null
+++ b/kit-manifest.json
@@ -0,0 +1,106 @@
+{
+  "adopter_owned": [
+    "config/dev-model.yaml",
+    "docs/handoff.md",
+    "docs/handoff-history.md",
+    "docs/friction-log.md",
+    "docs/friction-log-archive.md",
+    "README.md",
+    ".gitignore"
+  ],
+  "files": {
+    "docs/agentic-dev-kit/safety-critical-changes.md": {
+      "role": "doctrine",
+      "sha256": "cc3f3a76a22ba0a8552539bd2b85f07e10e59485eae2c3749f06036bf7db2e91"
+    },
+    "docs/agentic-dev-kit/workflows/parallel.md": {
+      "role": "workflow",
+      "sha256": "519fa1c623b75ba8cc0c6a3377f49a9681f47ada49f141aaf130d4007fffd460"
+    },
+    "docs/agentic-dev-kit/workflows/pr-watch.md": {
+      "role": "workflow",
+      "sha256": "169d3e27e149a49f736931b838d117a2fe6ad3ac6ddcaefccb99a51b97b505c8"
+    },
+    "docs/agentic-dev-kit/workflows/session-start.md": {
+      "role": "workflow",
+      "sha256": "f7a0a3ba8b65bc82f19764de6430bf82d0ee11d08447936b03de0056ac152c3a"
+    },
+    "docs/agentic-dev-kit/workflows/wrap-up.md": {
+      "role": "workflow",
+      "sha256": "63c26e6337c44653a4b710af68a5bad03e61e4fe0a2231479df4ab105053e071"
+    },
+    "docs/templates/friction-log-archive.md.tmpl": {
+      "role": "template",
+      "sha256": "af4a138e4a5ebe5634c55e7e417cd6b9f362bf3a35182b033f72876cd88180cf"
+    },
+    "docs/templates/friction-log.md.tmpl": {
+      "role": "template",
+      "sha256": "33e5bf0fe285ebbc248e062124d52f86bb78c47767f185d3d04df192db09c66d"
+    },
+    "docs/templates/handoff-history.md.tmpl": {
+      "role": "template",
+      "sha256": "111cf71a4c9b2a296f4fcf5ea02c6516907710e5b4fe0a7b3074f444f862ae69"
+    },
+    "docs/templates/handoff.md.tmpl": {
+      "role": "template",
+      "sha256": "1654465836a9e70a6e81d76208783e9a12d65343d1e9c3091f1d30c25a437ce7"
+    },
+    "scripts/archive_plan_sessions.py": {
+      "role": "engine",
+      "sha256": "fb15bd2dbe03257e6304f6e40f5af14bdffa66288fe0cc7ef2cdc38d0b4f9c76"
+    },
+    "scripts/check_doc_budget.py": {
+      "role": "engine",
+      "sha256": "a402424a12278e6a2ba55f90692aef9e44e9f030932529b5e85208590fc4e6dd"
+    },
+    "scripts/dev_session.sh": {
+      "role": "engine",
+      "sha256": "80311d61d9210c633560cd493402724e64aba9ff95b0ab02a40c97fb130d22eb"
+    },
+    "scripts/hooks/pre-push": {
+      "role": "hook",
+      "sha256": "c469700ff61a1506fa5951b4d5ab3ac95f3213227d8838efa95eef0492516fba"
+    },
+    "scripts/kit_doctor.py": {
+      "role": "engine",
+      "sha256": "23303dfac720e6f20cd1b1131d44b44893bbde8d061d18eadbb26a86a4252eef"
+    },
+    "scripts/lib/devmodel_config.py": {
+      "role": "engine",
+      "sha256": "53458a5d0c72b1fe5e5e5f6e8e5881c08c8c03c255493ae841391c5a8d6c1a29"
+    },
+    "scripts/lib/kitconfig.py": {
+      "role": "engine",
+      "sha256": "41c01a2956185d898f6cb75865d713845630a2d8335976f1460de1ed5f875317"
+    },
+    "scripts/lib/repo_root.sh": {
+      "role": "engine",
+      "sha256": "980cbf5596cea67033a5dd02d53630f2a92c24afd693ba7727d5fc50303ff555"
+    },
+    "scripts/lib/state_paths/__init__.py": {
+      "role": "engine",
+      "sha256": "691a7df06a3bf9019b5faca8b8ebdb9d54463d231d492a632fd54c16cd51a2c6"
+    },
+    "scripts/lib/state_paths/paths.py": {
+      "role": "engine",
+      "sha256": "f54fd7d970402f8581f6c5080aa9614ce41cb2dafa2010c08406129731799397"
+    },
+    "scripts/lib/state_paths/repo_root.py": {
+      "role": "engine",
+      "sha256": "d9412f1fe395b944a86126bcc39f85d6838382b0fc29d68c8b29b965cd530b5a"
+    },
+    "scripts/lib/state_paths/resolver.py": {
+      "role": "engine",
+      "sha256": "e39fca241d6fbf28596ed3954f28a55e65831181cedb02c7c15e372895bb5bd2"
+    },
+    "scripts/pr_watch.py": {
+      "role": "engine",
+      "sha256": "8e1fa0e8e14cc4e26172a91ea675194f7f985592a139ac5a09dd9def97deecd1"
+    },
+    "scripts/reconcile_sessions.sh": {
+      "role": "engine",
+      "sha256": "825796c961162b4b69ecacd4c6a228a3395213fc6323df957b0a123896e59a53"
+    }
+  },
+  "kit_version": 2
+}
diff --git a/scripts/archive_plan_sessions.py b/scripts/archive_plan_sessions.py
index b56b195..0fa14d3 100755
--- a/scripts/archive_plan_sessions.py
+++ b/scripts/archive_plan_sessions.py
@@ -1,7 +1,7 @@
 #!/usr/bin/env -S uv run --script
 # /// script
 # requires-python = ">=3.12"
-# dependencies = ["pyyaml"]
+# dependencies = []
 # ///
 """Sweep old session blocks out of the live handoff into its history document.
 
@@ -42,12 +42,11 @@
 import sys
 from pathlib import Path
 
-import yaml
 
 sys.path.insert(0, str(Path(__file__).resolve().parent / "lib"))
-from devmodel_config import _repo_root, load_config, resolve_path  # noqa: E402
+from kitconfig import load_config, repo_root, resolve_path  # noqa: E402
 
-REPO_ROOT = _repo_root()
+REPO_ROOT = repo_root()
 SEP = "______________________________________________________________________\n"
 SESSION_PREFIXES = ("## Latest session", "## Earlier session", "## Session — ")
 # Recent sessions may write *dated* headings (`## June 5 Fri (cont.) — …`) or a
diff --git a/scripts/check_doc_budget.py b/scripts/check_doc_budget.py
index 74f83bb..dfd4c77 100755
--- a/scripts/check_doc_budget.py
+++ b/scripts/check_doc_budget.py
@@ -1,7 +1,7 @@
 #!/usr/bin/env python3
 # /// script
 # requires-python = ">=3.12"
-# dependencies = ["pyyaml"]
+# dependencies = []
 # ///
 """Warn-only tripwire: nudge an archive sweep when a handoff doc grows too large.
 
@@ -18,7 +18,7 @@
 
 The tracked docs + their budgets come from ``config/dev-model.yaml``'s
 ``doc_budgets`` list (``{path, budget, archive, remedy}``) — see
-``scripts/lib/devmodel_config.py``. Adjust the budgets there, not here.
+``scripts/lib/kitconfig.py``. Adjust the budgets there, not here.
 
 Usage:
 
@@ -43,12 +43,12 @@
 from pathlib import Path
 
 sys.path.insert(0, str(Path(__file__).resolve().parent / "lib"))
-from devmodel_config import _repo_root, get, load_config  # noqa: E402
+from kitconfig import get, load_config, repo_root  # noqa: E402
 
 # Discover the repo root by walking up for a `.git` marker (via devmodel_config)
 # rather than assuming a fixed `scripts/<script>.py` depth — so this keeps working
 # when the kit is vendored under a nested dir (e.g. scripts/devkit/).
-REPO_ROOT = _repo_root()
+REPO_ROOT = repo_root()
 
 
 @dataclass(frozen=True)
diff --git a/scripts/kit_doctor.py b/scripts/kit_doctor.py
new file mode 100755
index 0000000..ad80eeb
--- /dev/null
+++ b/scripts/kit_doctor.py
@@ -0,0 +1,428 @@
+#!/usr/bin/env -S uv run --script
+# /// script
+# requires-python = ">=3.12"
+# dependencies = []
+# ///
+"""Report how far an adopting repo has drifted from the kit it was installed from.
+
+The upgrade problem this exists to solve: an adopter's copy of the kit has no
+version marker on its *engines* and no record of whether they were edited. Real
+installs surveyed before this was written spanned four shapes — an ancestor with
+no config surface at all, a v1-schema repo with only two of six engines and a
+`paths.engines` value that pointed at the wrong directory, a correctly namespaced
+v2 repo, and the template itself — and nothing could tell them apart. One repo's
+``pr_watch.py`` was three features behind upstream and nobody knew.
+
+So: **engines are kit-owned, config is adopter-owned.** That invariant is what
+makes an upgrade a file copy instead of a manual merge, and this script is what
+verifies it still holds. Per kit-owned file it reports one of:
+
+``unchanged``
+    Byte-identical to the manifest. Safe to replace outright on upgrade.
+``differs``
+    Present but not byte-identical to the manifest. A hash mismatch cannot
+    distinguish "older kit version" from "hand-edited", so this deliberately
+    does NOT claim which — calling an old file "locally modified" sends someone
+    hunting for edits they never made. The report narrows it using the config's
+    schema version, and either way the required action is the same: diff before
+    replacing, never clobber.
+``missing``
+    Not installed. Either a deliberately sized-down adoption or an incomplete
+    one; the report can't tell, so it says so rather than guessing.
+``unknown-version``
+    The manifest has no entry for this file, so drift can't be judged.
+
+Adopter-owned paths (the config, the narrative docs) are **never** compared —
+they are supposed to differ, and reporting them as drift would bury the signal.
+
+`paths.engines` indirection is handled: the manifest records the kit's own
+layout (``scripts/…``), and comparison maps that prefix onto whatever the
+adopter configured, so a repo that vendored engines under ``scripts/devkit/``
+compares correctly without a rewritten manifest.
+
+Read-only. Never writes to the repo it inspects (``--generate-manifest`` writes
+only the manifest, and only when run in the kit's own checkout).
+
+Usage:
+    uv run scripts/kit_doctor.py                    # human report
+    uv run scripts/kit_doctor.py --json             # machine-readable
+    uv run scripts/kit_doctor.py --generate-manifest  # (kit repo) refresh the manifest
+
+Exit codes:
+    0 — every kit-owned file is `unchanged` (or intentionally absent)
+    1 — at least one file `differs` or is `unknown-version`
+    2 — usage error (no config, no manifest, unreadable input)
+"""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import sys
+from dataclasses import dataclass, field
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent / "lib"))
+from kitconfig import get, load_config, repo_root  # noqa: E402
+
+MANIFEST_NAME = "kit-manifest.json"
+
+# Files the KIT owns, as they sit in the kit's own tree. An adopter should never
+# need to edit one of these — everything project-specific belongs in
+# config/dev-model.yaml. `role` groups the report; `engine_relative` marks the
+# paths that move with `paths.engines`.
+KIT_OWNED: tuple[tuple[str, str], ...] = (
+    # engines (move with paths.engines)
+    ("scripts/pr_watch.py", "engine"),
+    ("scripts/check_doc_budget.py", "engine"),
+    ("scripts/archive_plan_sessions.py", "engine"),
+    ("scripts/dev_session.sh", "engine"),
+    ("scripts/reconcile_sessions.sh", "engine"),
+    ("scripts/kit_doctor.py", "engine"),
+    ("scripts/lib/kitconfig.py", "engine"),
+    ("scripts/lib/devmodel_config.py", "engine"),
+    ("scripts/lib/repo_root.sh", "engine"),
+    ("scripts/lib/state_paths/__init__.py", "engine"),
+    ("scripts/lib/state_paths/resolver.py", "engine"),
+    ("scripts/lib/state_paths/paths.py", "engine"),
+    ("scripts/lib/state_paths/repo_root.py", "engine"),
+    ("scripts/hooks/pre-push", "hook"),
+    # shared workflow definitions
+    ("docs/agentic-dev-kit/workflows/session-start.md", "workflow"),
+    ("docs/agentic-dev-kit/workflows/wrap-up.md", "workflow"),
+    ("docs/agentic-dev-kit/workflows/pr-watch.md", "workflow"),
+    ("docs/agentic-dev-kit/workflows/parallel.md", "workflow"),
+    ("docs/agentic-dev-kit/safety-critical-changes.md", "doctrine"),
+    # narrative-doc templates (the rendered outputs are adopter-owned)
+    ("docs/templates/handoff.md.tmpl", "template"),
+    ("docs/templates/handoff-history.md.tmpl", "template"),
+    ("docs/templates/friction-log.md.tmpl", "template"),
+    ("docs/templates/friction-log-archive.md.tmpl", "template"),
+)
+
+# Paths that are the ADOPTER's — expected to differ, never reported as drift.
+# Listed explicitly (rather than inferred) so the boundary is auditable, and so
+# an installer can consume the same list to decide what not to copy.
+ADOPTER_OWNED: tuple[str, ...] = (
+    "config/dev-model.yaml",
+    "docs/handoff.md",
+    "docs/handoff-history.md",
+    "docs/friction-log.md",
+    "docs/friction-log-archive.md",
+    "README.md",
+    ".gitignore",
+)
+
+# `paths.engines` default in the kit's own layout — the prefix remapped onto an
+# adopter's configured engines directory.
+KIT_ENGINE_PREFIX = "scripts"
+
+
+@dataclass
+class FileStatus:
+    path: str
+    role: str
+    state: str
+    detail: str = ""
+
+
+@dataclass
+class Report:
+    kit_version_config: int | None
+    kit_version_manifest: int | None
+    engines_dir: str
+    engines_dir_ok: bool
+    hooks_installed: bool
+    narrative_rendered: dict[str, bool]
+    files: list[FileStatus] = field(default_factory=list)
+
+    @property
+    def drifted(self) -> list[FileStatus]:
+        return [f for f in self.files if f.state in ("differs", "unknown-version")]
+
+    @property
+    def missing(self) -> list[FileStatus]:
+        return [f for f in self.files if f.state == "missing"]
+
+
+def sha256_of(path: Path) -> str:
+    digest = hashlib.sha256()
+    with path.open("rb") as handle:
+        for chunk in iter(lambda: handle.read(65536), b""):
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+def _hook_dirs(root: Path):
+    """Every directory git might read hooks from, honoring ``core.hooksPath``.
+
+    ``$GIT_DIR/hooks`` is not the only answer: ``core.hooksPath`` overrides it,
+    and pre-commit plus several monorepo layouts set it. Checking only
+    ``.git/hooks`` reports a correctly-installed hook as missing — the same
+    mistake ``init.sh`` made when *writing* the shim, so it would have told an
+    adopter to re-run an install that had already worked.
+
+    Read via a plain config-file scan rather than shelling out to ``git``, so
+    this stays import- and subprocess-free.
+    """
+    candidates: list[Path] = []
+    config = root / ".git" / "config"
+    if config.is_file():
+        for line in config.read_text(encoding="utf-8", errors="replace").splitlines():
+            stripped = line.strip()
+            if stripped.startswith("hooksPath"):
+                _, _, value = stripped.partition("=")
+                value = value.strip()
+                if value:
+                    path = Path(value)
+                    candidates.append(path if path.is_absolute() else root / path)
+    candidates.append(root / ".git" / "hooks")
+    return [c / "pre-push" for c in candidates]
+
+
+def _remap(rel: str, engines_dir: str) -> str:
+    """Rewrite a kit-layout path onto the adopter's engines directory."""
+    engines_dir = engines_dir.rstrip("/") or KIT_ENGINE_PREFIX
+    if engines_dir == KIT_ENGINE_PREFIX:
+        return rel
+    if rel == KIT_ENGINE_PREFIX or rel.startswith(KIT_ENGINE_PREFIX + "/"):
+        return engines_dir + rel[len(KIT_ENGINE_PREFIX) :]
+    return rel
+
+
+def generate_manifest(root: Path, kit_version: int) -> dict:
+    """Hash every kit-owned file in the kit's own checkout.
+
+    Run in the kit repo at release time. A file listed in ``KIT_OWNED`` but
+    absent here is recorded as ``None`` rather than skipped, so a packaging
+    mistake shows up as an explicit hole instead of silently narrowing what
+    later gets checked.
+    """
+    files: dict[str, dict] = {}
+    for rel, role in KIT_OWNED:
+        target = root / rel
+        files[rel] = {
+            "sha256": sha256_of(target) if target.is_file() else None,
+            "role": role,
+        }
+    return {
+        "kit_version": kit_version,
+        "files": files,
+        "adopter_owned": list(ADOPTER_OWNED),
+    }
+
+
+def inspect(root: Path, manifest: dict, config: dict) -> Report:
+    engines_dir = str(get(config, "paths.engines", KIT_ENGINE_PREFIX))
+    manifest_files = manifest.get("files") or {}
+
+    statuses: list[FileStatus] = []
+    for rel, role in KIT_OWNED:
+        local_rel = _remap(rel, engines_dir)
+        target = root / local_rel
+        entry = manifest_files.get(rel) or {}
+        expected = entry.get("sha256")
+        if not target.is_file():
+            statuses.append(FileStatus(local_rel, role, "missing"))
+            continue
+        if expected is None:
+            statuses.append(
+                FileStatus(local_rel, role, "unknown-version", "no manifest entry")
+            )
+            continue
+        actual = sha256_of(target)
+        if actual == expected:
+            statuses.append(FileStatus(local_rel, role, "unchanged"))
+        else:
+            statuses.append(
+                FileStatus(local_rel, role, "differs", f"{actual[:12]} != {expected[:12]}")
+            )
+
+    # A configured engines dir that holds no engine is the silent failure that
+    # made one surveyed repo's workflows resolve `<engine-dir>/…` to nothing.
+    engines_probe = any(
+        (root / engines_dir / name).is_file()
+        for name in ("check_doc_budget.py", "pr_watch.py", "dev_session.sh")
+    )
+
+    hook_target = root / engines_dir / "hooks" / "pre-push"
+    hooks_installed = hook_target.is_file() and any(
+        candidate.is_file() for candidate in _hook_dirs(root)
+    )
+
+    narrative: dict[str, bool] = {}
+    for key in ("paths.handoff", "paths.friction_log"):
+        rel = get(config, key, None)
+        if not rel:
+            continue
+        doc = root / str(rel)
+        # "Rendered" = present and no longer carrying the shipped marker.
+        narrative[str(rel)] = doc.is_file() and (
+            "devkit-template: unrendered" not in doc.read_text(encoding="utf-8", errors="replace")
+        )
+
+    return Report(
+        kit_version_config=get(config, "kit.version", None),
+        kit_version_manifest=manifest.get("kit_version"),
+        engines_dir=engines_dir,
+        engines_dir_ok=engines_probe,
+        hooks_installed=hooks_installed,
+        narrative_rendered=narrative,
+        files=statuses,
+    )
+
+
+def render(report: Report) -> str:
+    lines: list[str] = ["kit-doctor — installation report", ""]
+    cfg_v, man_v = report.kit_version_config, report.kit_version_manifest
+    if cfg_v is None:
+        lines.append("  ⚠ config schema: UNVERSIONED (pre-v2) — run ./init.sh to migrate and stamp")
+    elif man_v is not None and cfg_v < man_v:
+        lines.append(f"  ⚠ config schema: v{cfg_v}, kit ships v{man_v} — run ./init.sh to migrate")
+    else:
+        lines.append(f"  ✓ config schema: v{cfg_v}")
+
+    if report.engines_dir_ok:
+        lines.append(f"  ✓ paths.engines: {report.engines_dir}")
+    else:
+        lines.append(
+            f"  ✗ paths.engines: {report.engines_dir} — contains no kit engine. "
+            "Every workflow's <engine-dir>/… reference resolves to nothing."
+        )
+
+    lines.append(
+        f"  {'✓' if report.hooks_installed else '⚠'} pre-push hook: "
+        + ("installed" if report.hooks_installed else "NOT installed — run ./init.sh")
+    )
+    for doc, rendered in report.narrative_rendered.items():
+        lines.append(
+            f"  {'✓' if rendered else '⚠'} {doc}: "
+            + ("in use" if rendered else "still an unrendered template — run ./init.sh")
+        )
+
+    by_state: dict[str, list[FileStatus]] = {}
+    for f in report.files:
+        by_state.setdefault(f.state, []).append(f)
+
+    lines.append("")
+    lines.append(
+        f"  files: {len(by_state.get('unchanged', []))} unchanged, "
+        f"{len(by_state.get('differs', []))} differ, "
+        f"{len(by_state.get('missing', []))} missing, "
+        f"{len(by_state.get('unknown-version', []))} unknown"
+    )
+    # Narrow "differs" using the schema version rather than asserting a cause.
+    behind = (
+        report.kit_version_config is not None
+        and report.kit_version_manifest is not None
+        and report.kit_version_config < report.kit_version_manifest
+    ) or report.kit_version_config is None
+    differs_label = (
+        "differ from the manifest — this repo's config predates the kit's, so these are "
+        "probably just an OLDER version rather than local edits; diff to confirm"
+        if behind
+        else "differ from the manifest — same schema version, so these are likely LOCAL EDITS; "
+        "diff before replacing"
+    )
+    for state, label in (
+        ("differs", differs_label),
+        ("unknown-version", "no manifest entry — drift cannot be judged"),
+        ("missing", "not installed (sized-down adoption, or incomplete)"),
+    ):
+        items = by_state.get(state) or []
+        if not items:
+            continue
+        lines.append(f"\n  {label}:")
+        for f in items:
+            suffix = f"  ({f.detail})" if f.detail else ""
+            lines.append(f"    · {f.path} [{f.role}]{suffix}")
+
+    if by_state.get("differs") and not behind:
+        lines.append(
+            "\n  Engines are kit-owned: everything project-specific belongs in"
+            "\n  config/dev-model.yaml. If you had to edit an engine to adopt it,"
+            "\n  that is a kit bug — please report it rather than carrying the patch."
+        )
+    return "\n".join(lines)
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="Report kit installation drift.")
+    parser.add_argument("--json", action="store_true", help="machine-readable output")
+    parser.add_argument(
+        "--generate-manifest",
+        action="store_true",
+        help="(kit repo only) hash every kit-owned file and write kit-manifest.json",
+    )
+    parser.add_argument("--root", type=Path, default=None, help="repo root (default: discovered)")
+    parser.add_argument("--manifest", type=Path, default=None, help="path to kit-manifest.json")
+    args = parser.parse_args(argv)
+
+    root = (args.root or repo_root()).resolve()
+    manifest_path = args.manifest or (root / MANIFEST_NAME)
+
+    try:
+        config = load_config(root / "config" / "dev-model.yaml")
+    except FileNotFoundError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        print(
+            "hint: a repo with no config/dev-model.yaml predates the config surface "
+            "entirely — adopt it with the /adopt skill rather than upgrading.",
+            file=sys.stderr,
+        )
+        return 2
+
+    if args.generate_manifest:
+        version = get(config, "kit.version", 2)
+        manifest = generate_manifest(root, int(version))
+        manifest_path.write_text(json.dumps(manifest, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+        holes = [p for p, e in manifest["files"].items() if e["sha256"] is None]
+        print(f"wrote {manifest_path} ({len(manifest['files'])} files, kit_version={version})")
+        if holes:
+            print(f"warning: {len(holes)} listed file(s) absent from this checkout:", file=sys.stderr)
+            for h in holes:
+                print(f"  · {h}", file=sys.stderr)
+        return 0
+
+    if not manifest_path.is_file():
+        print(f"error: manifest not found: {manifest_path}", file=sys.stderr)
+        print(
+            "hint: copy kit-manifest.json in from the kit release you are comparing against.",
+            file=sys.stderr,
+        )
+        return 2
+    try:
+        manifest = json.loads(manifest_path.read_text(encoding="utf-8"))
+    except (json.JSONDecodeError, OSError) as exc:
+        print(f"error: unreadable manifest {manifest_path}: {exc}", file=sys.stderr)
+        return 2
+
+    report = inspect(root, manifest, config)
+
+    if args.json:
+        print(
+            json.dumps(
+                {
+                    "kit_version_config": report.kit_version_config,
+                    "kit_version_manifest": report.kit_version_manifest,
+                    "engines_dir": report.engines_dir,
+                    "engines_dir_ok": report.engines_dir_ok,
+                    "hooks_installed": report.hooks_installed,
+                    "narrative_rendered": report.narrative_rendered,
+                    "files": [
+                        {"path": f.path, "role": f.role, "state": f.state, "detail": f.detail}
+                        for f in report.files
+                    ],
+                },
+                indent=1,
+            )
+        )
+    else:
+        print(render(report))
+
+    return 1 if report.drifted else 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
diff --git a/scripts/lib/kitconfig.py b/scripts/lib/kitconfig.py
index 79999f1..caf2d9a 100644
--- a/scripts/lib/kitconfig.py
+++ b/scripts/lib/kitconfig.py
@@ -273,6 +273,19 @@ def get(config: dict[str, Any], dotted_key: str, default: Any = _MISSING) -> Any
     return node
 
 
+def resolve_path(config: dict[str, Any], dotted_key: str, *, root: Path | None = None) -> Path:
+    """Resolve a config path value (``"paths.handoff"``) to an absolute ``Path``.
+
+    A relative value resolves against the repo root (or ``root`` if given); an
+    already-absolute value passes through unchanged.
+    """
+    value = get(config, dotted_key)
+    candidate = Path(str(value))
+    if candidate.is_absolute():
+        return candidate
+    return (root or repo_root()) / candidate
+
+
 def get_str_list(config: dict[str, Any], dotted_key: str, default: list[str]) -> list[str]:
     """``get`` narrowed to a list of strings, tolerating a single scalar.
 
diff --git a/scripts/tests/test_kit_doctor.py b/scripts/tests/test_kit_doctor.py
new file mode 100644
index 0000000..1aea1f0
--- /dev/null
+++ b/scripts/tests/test_kit_doctor.py
@@ -0,0 +1,218 @@
+"""Tests for the installation-drift report (scripts/kit_doctor.py).
+
+The behaviors pinned here are the ones that made the surveyed adopters
+diagnosable at all:
+
+- `paths.engines` remapping, so a repo that vendored engines under
+  `scripts/devkit/` is compared against the right files rather than reported as
+  a wholesale `missing`.
+- the `engines_dir_ok` probe, which is what catches a configured engines
+  directory containing no engine — the silent breakage where every workflow's
+  `<engine-dir>/…` reference resolves to nothing.
+- `differs` never asserting a *cause*. A hash mismatch cannot tell an older kit
+  version from a hand-edit, and claiming "locally modified" sends someone
+  hunting for edits they never made.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+
+import pytest
+
+REPO_ROOT = Path(__file__).resolve().parents[2]
+sys.path.insert(0, str(REPO_ROOT / "scripts"))
+sys.path.insert(0, str(REPO_ROOT / "scripts" / "lib"))
+
+import kit_doctor  # noqa: E402
+
+
+def _write(path: Path, text: str) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(text, encoding="utf-8")
+
+
+def _fake_repo(tmp_path: Path, *, engines: str = "scripts", version: str = "2") -> Path:
+    """A minimal adopter tree: a config, and one engine at the configured dir."""
+    _write(
+        tmp_path / "config" / "dev-model.yaml",
+        f"kit:\n  version: {version}\npaths:\n  handoff: docs/handoff.md\n"
+        f"  friction_log: docs/friction-log.md\n  engines: {engines}\n",
+    )
+    _write(tmp_path / engines / "check_doc_budget.py", "print('engine')\n")
+    _write(tmp_path / "docs" / "handoff.md", "# real handoff\n")
+    _write(tmp_path / "docs" / "friction-log.md", "# real inbox\n")
+    return tmp_path
+
+
+def _manifest(entries: dict[str, str | None], version: int = 2) -> dict:
+    return {
+        "kit_version": version,
+        "files": {p: {"sha256": h, "role": "engine"} for p, h in entries.items()},
+    }
+
+
+def test_remap_follows_configured_engines_dir():
+    assert kit_doctor._remap("scripts/pr_watch.py", "scripts") == "scripts/pr_watch.py"
+    assert kit_doctor._remap("scripts/pr_watch.py", "scripts/devkit") == "scripts/devkit/pr_watch.py"
+    assert (
+        kit_doctor._remap("scripts/lib/state_paths/resolver.py", "tools/devkit")
+        == "tools/devkit/lib/state_paths/resolver.py"
+    )
+    # Non-engine paths are untouched by the remap.
+    assert (
+        kit_doctor._remap("docs/agentic-dev-kit/workflows/parallel.md", "scripts/devkit")
+        == "docs/agentic-dev-kit/workflows/parallel.md"
+    )
+
+
+def test_unchanged_file_is_recognized(tmp_path):
+    root = _fake_repo(tmp_path)
+    target = root / "scripts" / "check_doc_budget.py"
+    manifest = _manifest({"scripts/check_doc_budget.py": kit_doctor.sha256_of(target)})
+    config = kit_doctor.load_config(root / "config" / "dev-model.yaml")
+    report = kit_doctor.inspect(root, manifest, config)
+    states = {f.path: f.state for f in report.files}
+    assert states["scripts/check_doc_budget.py"] == "unchanged"
+    assert report.drifted == []
+
+
+def test_hash_mismatch_reports_differs_without_claiming_a_cause(tmp_path):
+    root = _fake_repo(tmp_path)
+    manifest = _manifest({"scripts/check_doc_budget.py": "0" * 64})
+    config = kit_doctor.load_config(root / "config" / "dev-model.yaml")
+    report = kit_doctor.inspect(root, manifest, config)
+    match = next(f for f in report.files if f.path == "scripts/check_doc_budget.py")
+    assert match.state == "differs"
+    rendered = kit_doctor.render(report)
+    # Must not assert a cause it cannot know.
+    assert "locally-modified" not in rendered
+    assert "LOCAL EDITS" in rendered  # same schema version ⇒ edits are the likelier cause
+
+
+def test_older_schema_attributes_differences_to_version_not_edits(tmp_path):
+    root = _fake_repo(tmp_path, version="1")
+    manifest = _manifest({"scripts/check_doc_budget.py": "0" * 64}, version=2)
+    config = kit_doctor.load_config(root / "config" / "dev-model.yaml")
+    rendered = kit_doctor.render(kit_doctor.inspect(root, manifest, config))
+    assert "OLDER version" in rendered
+    assert "LOCAL EDITS" not in rendered
+
+
+def test_namespaced_engines_are_found_not_reported_missing(tmp_path):
+    root = _fake_repo(tmp_path, engines="scripts/devkit")
+    target = root / "scripts" / "devkit" / "check_doc_budget.py"
+    manifest = _manifest({"scripts/check_doc_budget.py": kit_doctor.sha256_of(target)})
+    config = kit_doctor.load_config(root / "config" / "dev-model.yaml")
+    report = kit_doctor.inspect(root, manifest, config)
+    match = next(f for f in report.files if f.path.endswith("check_doc_budget.py"))
+    assert match.path == "scripts/devkit/check_doc_budget.py"
+    assert match.state == "unchanged"
+    assert report.engines_dir_ok is True
+
+
+def test_engines_dir_containing_no_engine_is_flagged(tmp_path):
+    """The live breakage: a config whose paths.engines points at a directory with
+    no engine in it, so every workflow's <engine-dir>/… reference resolves to
+    nothing — silently, because nothing validated the value."""
+    root = _fake_repo(tmp_path, engines="scripts/devkit")
+    # Config says scripts/devkit, but move the engine somewhere else entirely.
+    (root / "scripts" / "devkit" / "check_doc_budget.py").unlink()
+    config = kit_doctor.load_config(root / "config" / "dev-model.yaml")
+    report = kit_doctor.inspect(root, _manifest({}), config)
+    assert report.engines_dir_ok is False
+    assert "contains no kit engine" in kit_doctor.render(report)
+
+
+def test_unrendered_narrative_doc_is_flagged(tmp_path):
+    root = _fake_repo(tmp_path)
+    (root / "docs" / "handoff.md").write_text(
+        "<!-- devkit-template: unrendered -->\n# x\n", encoding="utf-8"
+    )
+    config = kit_doctor.load_config(root / "config" / "dev-model.yaml")
+    report = kit_doctor.inspect(root, _manifest({}), config)
+    assert report.narrative_rendered["docs/handoff.md"] is False
+    assert report.narrative_rendered["docs/friction-log.md"] is True
+
+
+def test_missing_manifest_entry_is_unknown_not_unchanged(tmp_path):
+    root = _fake_repo(tmp_path)
+    manifest = _manifest({"scripts/check_doc_budget.py": None})
+    config = kit_doctor.load_config(root / "config" / "dev-model.yaml")
+    report = kit_doctor.inspect(root, manifest, config)
+    match = next(f for f in report.files if f.path == "scripts/check_doc_budget.py")
+    assert match.state == "unknown-version"
+    assert report.drifted  # unknown must not silently pass
+
+
+def test_unversioned_config_is_called_out(tmp_path):
+    root = tmp_path
+    _write(
+        root / "config" / "dev-model.yaml",
+        "paths:\n  handoff: docs/handoff.md\n  friction_log: docs/friction-log.md\n",
+    )
+    config = kit_doctor.load_config(root / "config" / "dev-model.yaml")
+    report = kit_doctor.inspect(root, _manifest({}), config)
+    assert report.kit_version_config is None
+    assert "UNVERSIONED" in kit_doctor.render(report)
+
+
+def test_shipped_manifest_covers_every_kit_owned_file():
+    """A KIT_OWNED entry with no manifest hash degrades silently to
+    `unknown-version` for every adopter, so the manifest must be regenerated
+    whenever the list changes."""
+    manifest_path = REPO_ROOT / kit_doctor.MANIFEST_NAME
+    assert manifest_path.is_file(), "run kit_doctor.py --generate-manifest"
+    manifest = json.loads(manifest_path.read_text(encoding="utf-8"))
+    listed = set(manifest["files"])
+    owned = {rel for rel, _ in kit_doctor.KIT_OWNED}
+    assert owned == listed, f"manifest out of sync: {owned ^ listed}"
+    holes = [p for p, e in manifest["files"].items() if e["sha256"] is None]
+    assert not holes, f"manifest has null hashes (files absent at generation): {holes}"
+
+
+def test_kit_repo_self_check_is_clean():
+    """The kit's own checkout must report zero drift against its own manifest —
+    otherwise the manifest is stale and every adopter report is wrong."""
+    manifest = json.loads((REPO_ROOT / kit_doctor.MANIFEST_NAME).read_text(encoding="utf-8"))
+    config = kit_doctor.load_config(REPO_ROOT / "config" / "dev-model.yaml")
+    report = kit_doctor.inspect(REPO_ROOT, manifest, config)
+    assert report.drifted == [], [f"{f.path}: {f.state}" for f in report.drifted]
+
+
+@pytest.mark.parametrize("adopter_path", kit_doctor.ADOPTER_OWNED)
+def test_adopter_owned_paths_are_never_compared(adopter_path):
+    assert adopter_path not in {rel for rel, _ in kit_doctor.KIT_OWNED}
+
+
+def test_hook_detection_honors_core_hookspath(tmp_path):
+    """`.git/hooks` is not the only place git reads hooks from — core.hooksPath
+    overrides it (pre-commit and several monorepo layouts set it). Checking only
+    `.git/hooks` reports a correctly-installed hook as missing, which is the same
+    mistake init.sh made when WRITING the shim: it would tell an adopter to
+    re-run an install that had already worked."""
+    root = _fake_repo(tmp_path)
+    _write(root / "scripts" / "hooks" / "pre-push", "#!/bin/sh\nexit 0\n")
+    config = kit_doctor.load_config(root / "config" / "dev-model.yaml")
+
+    # No hook installed anywhere yet.
+    assert kit_doctor.inspect(root, _manifest({}), config).hooks_installed is False
+
+    # Installed at a core.hooksPath location, NOT .git/hooks.
+    _write(root / ".git" / "config", "[core]\n\thooksPath = .githooks\n")
+    _write(root / ".githooks" / "pre-push", "#!/bin/sh\nexit 0\n")
+    assert kit_doctor.inspect(root, _manifest({}), config).hooks_installed is True
+
+
+def test_hook_detection_falls_back_to_git_hooks(tmp_path):
+    root = _fake_repo(tmp_path)
+    _write(root / "scripts" / "hooks" / "pre-push", "#!/bin/sh\nexit 0\n")
+    _write(root / ".git" / "hooks" / "pre-push", "#!/bin/sh\nexit 0\n")
+    config = kit_doctor.load_config(root / "config" / "dev-model.yaml")
+    assert kit_doctor.inspect(root, _manifest({}), config).hooks_installed is True
+
+
+def test_remap_tolerates_a_trailing_slash():
+    assert kit_doctor._remap("scripts/pr_watch.py", "scripts/devkit/") == "scripts/devkit/pr_watch.py"