From ad8e179c9eff2714df2ee151bf3b4fe5ff7880be Mon Sep 17 00:00:00 2001
From: Topi Jarvinen <topi.jarvinen@gmail..com>
Date: Sat, 25 Jul 2026 08:58:47 +0300
Subject: [PATCH 1/2] =?UTF-8?q?feat:=20kit=5Fdoctor=20+=20/upgrade=20?=
 =?UTF-8?q?=E2=80=94=20make=20an=20already-adopted=20install=20diagnosable?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Phase 2. Re-running ./init.sh (landed in #8) already handles the config half of
an upgrade. This is the engine half, which was the part nothing could see.

The problem, measured rather than assumed. Surveying the real installs turned up
four distinct shapes, none of them versioned at the engine level:

  · an ancestor with no config surface at all
  · a v1-schema repo with 2 of 6 engines and a paths.engines value pointing at a
    directory containing no engine — so every workflow's <engine-dir>/… reference
    resolved to nothing, silently, because nothing validates that value
  · a correctly namespaced v2 repo whose pr_watch.py was 3 features behind
  · the template itself

Nothing could tell an older engine from a hand-patched one, which is what makes
"just copy the new files in" unsafe.

scripts/kit_doctor.py — read-only drift report against a released
kit-manifest.json (path -> sha256). Per kit-owned file: unchanged / differs /
missing / unknown-version. Plus the four installation-level checks nothing else
performs: schema generation, whether paths.engines actually holds engines,
whether the pre-push hook is installed rather than merely shipped, and whether
the narrative docs were rendered.

Two deliberate design calls:

  · `differs` does NOT claim a cause. A hash mismatch cannot distinguish "older
    version" from "hand-edited", and labelling an old file "locally modified"
    sends someone hunting for edits they never made — this was caught by running
    the tool against a real adopter, which reported 4 files as locally-modified
    when they were almost certainly just old. It now narrows by schema version
    and leaves the call to the operator.
  · paths.engines indirection is handled by remapping the manifest's kit-layout
    prefix, so a repo with engines under scripts/devkit/ compares correctly
    against an unmodified manifest.

Adopter-owned paths are never compared — they are supposed to differ, and
reporting them would bury the signal. That list is explicit (not inferred) so an
installer can consume the same boundary.

/upgrade (.claude/commands/upgrade.md) — drives the sequence: detect which of the
four shapes this repo is, migrate config via init.sh, then refresh per file keyed
on kit_doctor's states. Routes a config-less repo to /adopt instead of guessing a
config into existence. Names the case worth routing UPSTREAM: a local edit that
is genuinely ahead of the kit should become a kit PR, not be overwritten.

Also closes #5: check_doc_budget.py and archive_plan_sessions.py now read config
through the stdlib kitconfig instead of PyYAML, so every shipped engine is
dependency-free — including the SessionStart hook path added in #13. This is the
same invariant kit_doctor asserts: an engine an adopter must edit (or install a
dependency for) can never be safely replaced.

CI gates the manifest against the tree, since a stale manifest silently degrades
every adopter's report to unknown-version.

184 tests pass. Verified against both real adopter repos read-only: brain's
missing-engine breakage and OpenKitchen's 4 drifted files are both correctly
diagnosed, with the engines-dir failure called out explicitly.

Closes #5.
---
 .claude/commands/upgrade.md      | 146 +++++++++++
 .github/workflows/test.yml       |   5 +
 README.md                        |  34 +++
 kit-manifest.json                | 106 ++++++++
 scripts/archive_plan_sessions.py |   7 +-
 scripts/check_doc_budget.py      |   8 +-
 scripts/kit_doctor.py            | 399 +++++++++++++++++++++++++++++++
 scripts/lib/kitconfig.py         |  13 +
 scripts/tests/test_kit_doctor.py | 187 +++++++++++++++
 9 files changed, 897 insertions(+), 8 deletions(-)
 create mode 100644 .claude/commands/upgrade.md
 create mode 100644 kit-manifest.json
 create mode 100755 scripts/kit_doctor.py
 create mode 100644 scripts/tests/test_kit_doctor.py

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..e30143b
--- /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": "7dfd0f45e68b28602dd6c8fac07571e2ccf893163244915b38400a83518ab595"
+    },
+    "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..d416098
--- /dev/null
+++ b/scripts/kit_doctor.py
@@ -0,0 +1,399 @@
+#!/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 _remap(rel: str, engines_dir: str) -> str:
+    """Rewrite a kit-layout path onto the adopter's engines directory."""
+    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"
+    installed = root / ".git" / "hooks" / "pre-push"
+    hooks_installed = installed.is_file() and hook_target.is_file()
+
+    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..5b0d46c
--- /dev/null
+++ b/scripts/tests/test_kit_doctor.py
@@ -0,0 +1,187 @@
+"""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}

From a1baa661b71372caa19ebdb3d2c783303c83f407 Mon Sep 17 00:00:00 2001
From: Topi Jarvinen <topi.jarvinen@gmail..com>
Date: Sat, 25 Jul 2026 09:03:42 +0300
Subject: [PATCH 2/2] fix(kit_doctor): honor core.hooksPath when detecting the
 installed hook
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Found by the fallback review pass on this PR. `.git/hooks` is not the only
place git reads hooks from — core.hooksPath overrides it, and pre-commit plus
several monorepo layouts set it. Checking only `.git/hooks` reports a
correctly-installed hook as missing, so the report would tell an adopter to
re-run an install that had already worked.

This is the same bug class fixed in init.sh for the WRITE side earlier in this
stack, reintroduced on the READ side. Read via a plain .git/config scan rather
than shelling out to git, keeping kit_doctor subprocess-free.

Also strip a trailing slash from paths.engines before remapping.
---
 kit-manifest.json                |  2 +-
 scripts/kit_doctor.py            | 33 ++++++++++++++++++++++++++++++--
 scripts/tests/test_kit_doctor.py | 31 ++++++++++++++++++++++++++++++
 3 files changed, 63 insertions(+), 3 deletions(-)

diff --git a/kit-manifest.json b/kit-manifest.json
index e30143b..9d06c12 100644
--- a/kit-manifest.json
+++ b/kit-manifest.json
@@ -63,7 +63,7 @@
     },
     "scripts/kit_doctor.py": {
       "role": "engine",
-      "sha256": "7dfd0f45e68b28602dd6c8fac07571e2ccf893163244915b38400a83518ab595"
+      "sha256": "23303dfac720e6f20cd1b1131d44b44893bbde8d061d18eadbb26a86a4252eef"
     },
     "scripts/lib/devmodel_config.py": {
       "role": "engine",
diff --git a/scripts/kit_doctor.py b/scripts/kit_doctor.py
index d416098..ad80eeb 100755
--- a/scripts/kit_doctor.py
+++ b/scripts/kit_doctor.py
@@ -154,8 +154,36 @@ def sha256_of(path: Path) -> str:
     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 + "/"):
@@ -219,8 +247,9 @@ def inspect(root: Path, manifest: dict, config: dict) -> Report:
     )
 
     hook_target = root / engines_dir / "hooks" / "pre-push"
-    installed = root / ".git" / "hooks" / "pre-push"
-    hooks_installed = installed.is_file() and hook_target.is_file()
+    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"):
diff --git a/scripts/tests/test_kit_doctor.py b/scripts/tests/test_kit_doctor.py
index 5b0d46c..1aea1f0 100644
--- a/scripts/tests/test_kit_doctor.py
+++ b/scripts/tests/test_kit_doctor.py
@@ -185,3 +185,34 @@ def test_kit_repo_self_check_is_clean():
 @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"