From a09fb8059c4620c61765883e920bd5ebc8898abb Mon Sep 17 00:00:00 2001
From: Topi Jarvinen <topi.jarvinen@gmail..com>
Date: Sat, 25 Jul 2026 00:23:09 +0300
Subject: [PATCH 1/5] feat: fix the adoption path and make engines upgradable
 (kit schema v2)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Phase 0 of the kit refactor — the shared primitives the follow-on lanes need,
plus the two bugs that broke adoption at step one.

Adoption (was: broken for every adopter)
- init.sh was committed mode 100644, so the documented `./init.sh` failed with
  "permission denied". Now 100755, pinned by a CI check.
- The narrative-doc seeding could never fire: the kit SHIPS docs/handoff.md and
  docs/friction-log.md, so a `cp -r` or template-clone always landed them before
  init.sh ran and the "seed only if absent" guard was permanently false. Every
  adopter started with a `my-project` header and a `<tracker.url — stamped by
  init.sh>` placeholder that init.sh never stamped (it did not even prompt for
  the URL). Docs now render from docs/templates/*.tmpl, keyed on a
  `devkit-template: unrendered` marker that distinguishes the file the kit
  shipped from one someone is actually using. init.sh now prompts for
  tracker.url. All four narrative docs are seeded, not just two.

Upgrade path (new)
- kit.version stamps the config schema generation; re-running ./init.sh is now
  the supported upgrade, migrating an older config forward in place and never
  guessing over an existing value.
- paths.engines is PROBED rather than defaulted. An adopter who vendored the
  engines under scripts/devkit/ was being migrated to `engines: scripts`, so
  every workflow's <engine-dir>/… reference resolved to a directory with no
  engines in it — silently, since nothing validates the value.
- The pre-push hook is installed, as a shim that execs the engine. Shipping it
  uninstalled made the kit's own mechanism-over-memory exemplar (Principle #8)
  inert in every adopting repo.
- .mcp.json is added to .gitignore when it holds literal credentials, since
  dev_session.sh copies it into every lane worktree.

Engines become kit-owned (prerequisite for ever replacing one)
- scripts/lib/kitconfig.py: stdlib-only reader for the config subset the kit
  uses, verified byte-equal to PyYAML on the shipped config and on two real
  adopter configs. Engines can now read config without a third-party dependency,
  which is what lets pr_watch's review-bot markers move OUT of the engine.
- config gains review.noise_markers / unavailable_markers /
  informational_checks / require_ci, and documents DEVKIT_CI_ENV_VARS. The
  engines are wired to them in the follow-on lane; this lands the schema so the
  three lanes don't collide on this file.

Verified end-to-end: fresh adoption renders correctly through a pty; a re-run
leaves an in-use handoff byte-identical; brain's real v1 config + scripts/devkit
layout migrates to v2 with paths.engines detected and its 223-line handoff
untouched.

Refs #5 (config reader is now stdlib-only).
---
 .github/workflows/test.yml                  |  14 +-
 README.md                                   |  30 +++
 config/dev-model.yaml                       |  54 ++++
 docs/friction-log-archive.md                |   2 +
 docs/friction-log.md                        |   2 +
 docs/handoff-history.md                     |   2 +
 docs/handoff.md                             |   2 +
 docs/templates/friction-log-archive.md.tmpl |   4 +
 docs/templates/friction-log.md.tmpl         |  20 ++
 docs/templates/handoff-history.md.tmpl      |   6 +
 docs/templates/handoff.md.tmpl              |  26 ++
 init.sh                                     | 270 +++++++++++++++-----
 scripts/lib/kitconfig.py                    | 250 ++++++++++++++++++
 scripts/tests/test_kitconfig.py             | 167 ++++++++++++
 14 files changed, 781 insertions(+), 68 deletions(-)
 create mode 100644 docs/templates/friction-log-archive.md.tmpl
 create mode 100644 docs/templates/friction-log.md.tmpl
 create mode 100644 docs/templates/handoff-history.md.tmpl
 create mode 100644 docs/templates/handoff.md.tmpl
 create mode 100644 scripts/lib/kitconfig.py
 create mode 100644 scripts/tests/test_kitconfig.py

diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
index c90ac2b..bb6c830 100644
--- a/.github/workflows/test.yml
+++ b/.github/workflows/test.yml
@@ -15,6 +15,18 @@ jobs:
       - name: Install test dependencies
         run: python -m pip install pytest pyyaml
       - name: Check shell syntax
-        run: bash -n init.sh scripts/dev_session.sh scripts/reconcile_sessions.sh scripts/lib/repo_root.sh scripts/hooks/pre-push
+        run: |
+          bash -n scripts/dev_session.sh scripts/reconcile_sessions.sh scripts/lib/repo_root.sh scripts/hooks/pre-push
+          sh -n init.sh
+      - name: init.sh must be executable
+        # The documented first command is `./init.sh`; a non-executable mode makes
+        # it fail for every adopter at step one.
+        run: test -x init.sh
       - name: Run state and portability tests
         run: python -m pytest scripts/lib/state_paths/tests scripts/tests -q
+      - 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.
+        run: |
+          python -m pip uninstall -y pyyaml
+          python -m pytest scripts/tests/test_kitconfig.py -q
diff --git a/README.md b/README.md
index da57aaf..079dba1 100644
--- a/README.md
+++ b/README.md
@@ -84,6 +84,11 @@ patterns to rules).
 
 ## Quickstart
 
+**Prerequisites.** `init.sh` itself needs only POSIX `sh`, `awk`, and `git`. The
+engines need [`uv`](https://docs.astral.sh/uv/) (they're PEP-723 single-file
+scripts), `git`, and — for `pr-watch` / `parallel` — the GitHub CLI `gh`,
+authenticated. No PyYAML: the config reader is stdlib-only.
+
 ```sh
 # Click "Use this template" on GitHub and clone the result — or, into an
 # existing repo, copy the kit's contents in from the root:
@@ -94,9 +99,34 @@ cp -r /path/to/agentic-dev-kit/. .
 #   -> start your agent session and invoke session-start
 ```
 
+`init.sh` stamps your answers into `config/dev-model.yaml`, renders the narrative
+docs from `docs/templates/`, installs the pre-push hook, and adds the state
+sandbox to `.gitignore`. It never overwrites a narrative doc that is already in
+use — only one still carrying the shipped `devkit-template: unrendered` marker.
+
 Ten minutes, start to finish. For a full worked example of a first session — from
 adoption through `wrap-up` — see **[`docs/getting-started.md`](docs/getting-started.md)**.
 
+## Upgrading an already-adopted repo
+
+**Pull the new kit files, then re-run `./init.sh`.** That is the supported upgrade
+path, and it is safe to run any number of times:
+
+- **Config** — `init.sh` migrates an older schema forward *in place*, only ever
+  adding missing keys. Your existing values are never guessed over. `kit.version`
+  records which generation you're on.
+- **`paths.engines`** — probed from where your engines actually are, so a repo that
+  vendored them under `scripts/devkit/` is migrated to that path rather than a
+  wrong default.
+- **Narrative docs** — a handoff or friction log you're actually using is left
+  byte-identical; only an unrendered skeleton is (re-)rendered.
+- **Hooks** — reinstalled as a shim that execs the engine, so a hook stays current
+  with the engine rather than going stale as a copy.
+- **Engines** — replace the files. Engines are **kit-owned**: everything
+  project-specific (review-bot markers, informational checks, CI policy, paths)
+  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.
+
 ### Agent runtime adapters
 
 The workflow definitions under `docs/agentic-dev-kit/workflows/` are shared. The
diff --git a/config/dev-model.yaml b/config/dev-model.yaml
index b115313..b134614 100644
--- a/config/dev-model.yaml
+++ b/config/dev-model.yaml
@@ -10,6 +10,15 @@
 # or edit this file directly.
 # ─────────────────────────────────────────────────────────────────────────────
 
+kit:
+  # Which generation of the kit's config schema this repo is on. `init.sh` stamps
+  # it and migrates an older config forward in place, so re-running `./init.sh`
+  # after pulling a kit update is the supported upgrade path. Never edit by hand:
+  # lowering it re-runs migrations that are already applied.
+  #   1 — original single-runtime schema (no `runtime:`, no `models.tiers`)
+  #   2 — runtime adapters + capability tiers + engine-facing review/CI config
+  version: 2
+
 project:
   # Human-readable project name, used in skill prompts and doc headers.
   name: my-project
@@ -73,6 +82,44 @@ review:
   fallback_commands:
     claude: "/code-review"
     codex: "/review"
+  # Everything below is read by scripts/pr_watch.py. It used to live as literals
+  # inside that engine, which meant adopting the kit required *editing the
+  # engine* — and an edited engine can never be replaced by a kit update. Keeping
+  # it here is what makes engines kit-owned and upgradable (Principle #10).
+  #
+  # Comment bodies matching any of these are auto-noise, not findings to act on.
+  # Matched case-insensitively as substrings. Keep the list tight — over-filtering
+  # hides a real review.
+  noise_markers:
+    - "<!-- this is an auto-generated comment: summarize by coderabbit"
+    - "<!-- this is an auto-generated comment: review in progress"
+    - "<!-- walkthrough_start -->"
+    - "actionable comments posted: 0"
+    - "review skipped"
+    - "<!-- linear-linkback -->"
+  # Bodies signalling the reviewer could not run. Deliberately NOT noise: these
+  # surface and block `done`, because a blocked bot is an action signal (run the
+  # configured fallback), never a silent review waiver.
+  unavailable_markers:
+    - "bugbot needs on-demand usage enabled"
+    - "review limit reached"
+    - "rate limited by coderabbit"
+    - "couldn't start this review"
+    - "review skipped"
+    - "no review credits"
+  # Status checks that are advisory only and must never block `done`. A review
+  # bot's check can sit PENDING forever after a trivial follow-up commit; its real
+  # findings arrive as comments (which DO block). Matched case-insensitively
+  # against the check name.
+  informational_checks: [coderabbit]
+  # Whether a PR must have at least one real (non-informational) CI check before
+  # pr_watch will report `done`. True is the safe default: it stops an autonomous
+  # merge on a PR whose CI never ran. Set false for a repo with no CI at all —
+  # otherwise pr-watch can never converge and `dev_session.sh merge` always
+  # refuses. With false, `done` additionally requires current-head review evidence
+  # (it already does) — that receipt becomes the only quality gate, so set this
+  # deliberately.
+  require_ci: true
 
 notify:
   backend: slack                 # slack | none — where skills DM the operator
@@ -102,3 +149,10 @@ state:
   # see scripts/lib/state_paths/. Those are kit constants, not adopter config; listed
   # here only so the convention is discoverable. `dirname` is the top-level state dir.
   dirname: state
+  # The unsandboxed-write guard skips a legitimate scheduled/CI writer, detected by
+  # env var. state_paths stays import-free (it must work from a git hook), so this is
+  # an ENV contract, not a value it reads from here — documented here for
+  # discoverability only:
+  #   DEVKIT_CI_ENV_VARS  comma-separated var names whose presence means "cron/CI".
+  #                       Default: JOB_NAME,CI,GITHUB_ACTIONS,GITLAB_CI,BUILDKITE
+  # Set it in your runner if your scheduler exports something else.
diff --git a/docs/friction-log-archive.md b/docs/friction-log-archive.md
index 64f5915..fa37274 100644
--- a/docs/friction-log-archive.md
+++ b/docs/friction-log-archive.md
@@ -1,3 +1,5 @@
+<!-- devkit-template: unrendered — ./init.sh renders this from docs/templates/. Delete this line to claim the file as yours. -->
+
 # Friction Log Archive
 
 Graduated friction entries live here after they have been routed to the tracker or
diff --git a/docs/friction-log.md b/docs/friction-log.md
index abc44c4..0aab1d9 100644
--- a/docs/friction-log.md
+++ b/docs/friction-log.md
@@ -1,3 +1,5 @@
+<!-- devkit-template: unrendered — ./init.sh renders this from docs/templates/. Delete this line to claim the file as yours. -->
+
 # Friction Log
 
 > **Lean inbox (Principle #2 — the friction flywheel).** Friction surfaced during real
diff --git a/docs/handoff-history.md b/docs/handoff-history.md
index 620e059..9606cbd 100644
--- a/docs/handoff-history.md
+++ b/docs/handoff-history.md
@@ -1,3 +1,5 @@
+<!-- devkit-template: unrendered — ./init.sh renders this from docs/templates/. Delete this line to claim the file as yours. -->
+
 # Handoff History
 
 Archived session narratives from the living handoff. Keep active direction and the
diff --git a/docs/handoff.md b/docs/handoff.md
index 6cb8159..3ee22df 100644
--- a/docs/handoff.md
+++ b/docs/handoff.md
@@ -1,3 +1,5 @@
+<!-- devkit-template: unrendered — ./init.sh renders this from docs/templates/. Delete this line to claim the file as yours. -->
+
 # my-project — Living Plan (Handoff)
 
 > **Forward-looking handoff (Principle #1).** Read this at the start of every session
diff --git a/docs/templates/friction-log-archive.md.tmpl b/docs/templates/friction-log-archive.md.tmpl
new file mode 100644
index 0000000..64f5915
--- /dev/null
+++ b/docs/templates/friction-log-archive.md.tmpl
@@ -0,0 +1,4 @@
+# Friction Log Archive
+
+Graduated friction entries live here after they have been routed to the tracker or
+promoted into a repeated-pattern rule.
diff --git a/docs/templates/friction-log.md.tmpl b/docs/templates/friction-log.md.tmpl
new file mode 100644
index 0000000..97bf96c
--- /dev/null
+++ b/docs/templates/friction-log.md.tmpl
@@ -0,0 +1,20 @@
+# Friction Log
+
+> **Lean inbox (Principle #2 — the friction flywheel).** Friction surfaced during real
+> use — a bug, an awkward workflow, a recurring annoyance — recorded the moment it's
+> fresh, at session end. A periodic triage (`triage-friction-log`) reads new entries and
+> routes each one: single incidents go **down** to the tracker; a genuine, multi-occurrence
+> **pattern** graduates **up** into a rule or skill change. Route down by default, up only
+> on repetition — so the flywheel self-regulates instead of ratcheting every week.
+>
+> Each entry: the observed issue, the date surfaced, a rough severity (**H**igh / **M**edium
+> / **L**ow), and a proposed fix or next step. Link related PRs, commits, or tracker items
+> when available. Graduated entries are swept to
+> [`friction-log-archive.md`](friction-log-archive.md) so this file stays just the current
+> inbox plus the most-recent graduation marker.
+>
+> Tracker board: {{TRACKER_URL}}
+
+## {{DATE}} — inbox
+
+- **<one-line issue> (severity: <H/M/L>).** <what happened, and a proposed fix or next step.>
diff --git a/docs/templates/handoff-history.md.tmpl b/docs/templates/handoff-history.md.tmpl
new file mode 100644
index 0000000..620e059
--- /dev/null
+++ b/docs/templates/handoff-history.md.tmpl
@@ -0,0 +1,6 @@
+# Handoff History
+
+Archived session narratives from the living handoff. Keep active direction and the
+next step in `handoff.md`; this file is append-only history.
+
+## Session log
diff --git a/docs/templates/handoff.md.tmpl b/docs/templates/handoff.md.tmpl
new file mode 100644
index 0000000..eecbe4b
--- /dev/null
+++ b/docs/templates/handoff.md.tmpl
@@ -0,0 +1,26 @@
+# {{PROJECT_NAME}} — Living Plan (Handoff)
+
+> **Forward-looking handoff (Principle #1).** Read this at the start of every session
+> (`session-start`); update it at the end (`wrap-up`). This file — not an agent's
+> memory, not a scratch note — is the single source of truth for what's done, in
+> progress, and next.
+>
+> Older session blocks graduate to [`handoff-history.md`](handoff-history.md) once this
+> file crosses its line budget (a warn-only tripwire — `{{ENGINE_DIR}}/check_doc_budget.py`).
+> Session-scoped scratch plans are exactly that: scratch. This is the handoff.
+
+Last updated: {{DATE}} — <one-line theme of the most recent session>
+
+## Latest session — {{DATE}}
+
+**Theme —** <what this session was about, in a line or two.>
+
+- <what shipped>
+- <what was decided>
+- <what was learned>
+
+▶ Next: <the single clearest next step — what the next `session-start` should pick up.>
+
+______________________________________________________________________
+
+> Older session entries live in [`handoff-history.md`](handoff-history.md).
diff --git a/init.sh b/init.sh
index 685d7ae..b0d3e43 100644
--- a/init.sh
+++ b/init.sh
@@ -186,11 +186,30 @@ append_to_section() {
 # documented as idempotent; silently leaving an old config without these keys
 # would make the new runtime-aware launchers appear bootstrapped while falling
 # back to the wrong behavior.
+# Where this repo's engines actually live. Probing beats defaulting: an adopter
+# who vendored the kit under scripts/devkit/ (the documented namespaced layout)
+# would otherwise be migrated to `engines: scripts`, and every workflow's
+# `<engine-dir>/…` reference would resolve to a path with no engines in it —
+# silently, since nothing validates the value. Falls back to `scripts` only when
+# no engine is found anywhere.
+detect_engines_dir() {
+  for candidate in scripts scripts/devkit scripts/kit scripts/agentic-dev-kit tools/devkit bin/devkit; do
+    for probe in check_doc_budget.py pr_watch.py dev_session.sh; do
+      if [ -f "$candidate/$probe" ]; then
+        printf '%s\n' "$candidate"
+        return 0
+      fi
+    done
+  done
+  printf 'scripts\n'
+}
+
 migrate_runtime_schema() {
   if ! grep -q '^  engines:' "$CONFIG_FILE"; then
-    append_to_section "paths:" '  # Directory containing the deterministic kit engines.
-  engines: scripts'
-    echo "added paths.engines to config/dev-model.yaml"
+    detected_engines="$(detect_engines_dir)"
+    append_to_section "paths:" "  # Directory containing the deterministic kit engines.
+  engines: $detected_engines"
+    echo "added paths.engines: $detected_engines to config/dev-model.yaml"
   fi
 
   if ! grep -q '^runtime:' "$CONFIG_FILE"; then
@@ -236,6 +255,139 @@ migrate_runtime_schema() {
   fi
 }
 
+# Schema additions introduced after the v2 template release. Same idempotent
+# shape as migrate_runtime_schema: only ever ADD a missing block, never guess
+# over an existing value — re-running init.sh is the supported upgrade path, so
+# a migration must be safe to apply to a config that already has it.
+migrate_kit_schema() {
+  if ! grep -q '^kit:' "$CONFIG_FILE"; then
+    # Prepend, so the version stamp reads first. There is no earlier section to
+    # anchor before, so insert_before_section targets the first one that exists.
+    insert_before_section "project:" 'kit:
+  # Which generation of the kit'"'"'s config schema this repo is on. `init.sh` stamps
+  # it and migrates an older config forward in place, so re-running `./init.sh`
+  # after pulling a kit update is the supported upgrade path.
+  version: 2
+'
+    echo "stamped kit.version=2 in config/dev-model.yaml"
+  fi
+
+  if ! grep -q '^  noise_markers:' "$CONFIG_FILE"; then
+    append_to_section "review:" '  # Read by pr_watch.py. These used to be literals inside the engine, which meant
+  # adopting required EDITING the engine — and an edited engine can never be
+  # replaced by a kit update (Principle #10).
+  noise_markers:
+    - "<!-- this is an auto-generated comment: summarize by coderabbit"
+    - "<!-- this is an auto-generated comment: review in progress"
+    - "<!-- walkthrough_start -->"
+    - "actionable comments posted: 0"
+    - "review skipped"
+    - "<!-- linear-linkback -->"
+  unavailable_markers:
+    - "bugbot needs on-demand usage enabled"
+    - "review limit reached"
+    - "rate limited by coderabbit"
+    - "couldn'"'"'t start this review"
+    - "review skipped"
+    - "no review credits"
+  informational_checks: [coderabbit]
+  # False only for a repo with NO CI at all — otherwise pr-watch never converges.
+  require_ci: true'
+    echo "added review marker/CI config to config/dev-model.yaml"
+  fi
+}
+
+# ── narrative-doc templates ──────────────────────────────────────────────
+# The kit SHIPS docs/handoff.md and docs/friction-log.md, so a `cp -r` or a
+# "Use this template" clone always lands them before init.sh runs — which used
+# to make the "seed only if absent" guard permanently false, and every adopter
+# started with an unrendered skeleton. The marker below is what distinguishes
+# "the pristine file the kit shipped" from "a handoff someone is actually
+# using": a rendered/edited file has no marker and is never touched.
+TEMPLATE_MARKER="devkit-template: unrendered"
+
+# _render <template> <target> — substitute the {{TOKENS}} and write.
+# awk (not sed) so a value containing /, &, or \ — a tracker URL, most obviously —
+# is substituted literally rather than reinterpreted as replacement syntax.
+_render() {
+  _tmpl="$1"
+  _out="$2"
+  awk -v project="$name" -v today="$(date +%Y-%m-%d)" \
+      -v tracker="$render_tracker_url" -v enginedir="$render_engine_dir" '
+    function subst(s, tok, val,   i, acc) {
+      acc = ""
+      while ((i = index(s, tok)) > 0) {
+        acc = acc substr(s, 1, i - 1) val
+        s = substr(s, i + length(tok))
+      }
+      return acc s
+    }
+    {
+      line = $0
+      line = subst(line, "{{PROJECT_NAME}}", project)
+      line = subst(line, "{{DATE}}", today)
+      line = subst(line, "{{TRACKER_URL}}", tracker)
+      line = subst(line, "{{ENGINE_DIR}}", enginedir)
+      print line
+    }
+  ' "$_tmpl" > "${_out}.tmp.$$" && mv "${_out}.tmp.$$" "$_out"
+}
+
+# seed_doc <template-basename> <target-path>
+seed_doc() {
+  _name="$1"
+  _target="$2"
+  _tmpl="docs/templates/${_name}.md.tmpl"
+  [ -n "$_target" ] || return 0
+  if [ ! -f "$_tmpl" ]; then
+    echo "note: template $_tmpl missing — skipped $_target" >&2
+    return 0
+  fi
+  if [ -f "$_target" ] && ! grep -q "$TEMPLATE_MARKER" "$_target" 2>/dev/null; then
+    echo "$_target already in use — left untouched"
+    return 0
+  fi
+  mkdir -p "$(dirname "$_target")"
+  _render "$_tmpl" "$_target"
+  echo "seeded $_target"
+}
+
+# ── git hooks ────────────────────────────────────────────────────────────
+# "A rule that lives only in a doc is a wish" (Principle #8) applies to the kit
+# itself: shipping scripts/hooks/pre-push without installing it made the kit's
+# own mechanism-over-memory exemplar inert in every adopting repo. Install a
+# shim rather than copying the hook body, so the hook stays current when the
+# engine is updated, and rather than a relative symlink, so it survives the
+# engines dir being vendored at any depth.
+install_hooks() {
+  if ! git rev-parse --git-dir >/dev/null 2>&1; then
+    echo "note: not a git repo yet — run 'git init' then re-run ./init.sh to install hooks" >&2
+    return 0
+  fi
+  hookdir="$(git rev-parse --git-path hooks 2>/dev/null || echo .git/hooks)"
+  mkdir -p "$hookdir"
+  for hook in pre-push; do
+    src="${engines_dir}/hooks/${hook}"
+    if [ ! -f "$src" ]; then
+      continue
+    fi
+    chmod +x "$src" 2>/dev/null || true
+    if [ -e "$hookdir/$hook" ] && ! grep -q 'devkit-hook-shim' "$hookdir/$hook" 2>/dev/null; then
+      echo "note: existing $hookdir/$hook left untouched (not a kit shim) — chain it to $src by hand" >&2
+      continue
+    fi
+    cat > "$hookdir/$hook" <<SHIM
+#!/bin/sh
+# devkit-hook-shim — regenerated by ./init.sh; edit $src, not this file.
+root="\$(git rev-parse --show-toplevel)" || exit 0
+[ -x "\$root/$src" ] || exit 0
+exec "\$root/$src" "\$@"
+SHIM
+    chmod +x "$hookdir/$hook"
+    echo "installed $hookdir/$hook -> $src"
+  done
+}
+
 # ask <prompt> <default> -> prints the answer (default kept on empty input
 # or when stdin isn't a terminal, e.g. running init.sh from a non-interactive
 # script).
@@ -260,6 +412,7 @@ if [ ! -t 0 ]; then
 fi
 
 migrate_runtime_schema
+migrate_kit_schema
 
 # ── prompts ──────────────────────────────────────────────────────────────
 
@@ -289,6 +442,10 @@ if [ "$backend" = "linear" ]; then
   set_field "tracker:" "linear:" "^    project_id:" "\"$project_id\""
 fi
 
+cur_tracker_url=$(get_field "tracker:" "" "^  url:")
+tracker_url=$(ask "Tracker board URL (shown in the friction-log header; blank is fine)" "$cur_tracker_url")
+set_field "tracker:" "" "^  url:" "\"$tracker_url\""
+
 cur_branch=$(get_field "vcs:" "" "^  protected_branch:")
 branch=$(ask "Protected branch (PRs target this, never commit to it directly)" "$cur_branch")
 set_field "vcs:" "" "^  protected_branch:" "$branch"
@@ -309,71 +466,34 @@ else
 fi
 set_field "review:" "" "^  bots:" "$bots_value"
 
-# ── seed narrative docs (never clobber) ──────────────────────────────────
-
-if [ ! -f docs/handoff.md ]; then
-  mkdir -p docs
-  cat > docs/handoff.md <<EOF
-# ${name} — Living Plan (Handoff)
-
-> **Forward-looking handoff (Principle #1).** Read this at the start of every session
-> (\`session-start\`); update it at the end (\`wrap-up\`). This file — not an agent's
-> memory, not a scratch note — is the single source of truth for what's done, in
-> progress, and next.
->
-> Older session blocks graduate to [\`handoff-history.md\`](handoff-history.md) once this
-> file crosses its line budget (a warn-only tripwire — \`scripts/check_doc_budget.py\`).
-> Session-scoped scratch plans are exactly that: scratch. This is the handoff.
-
-Last updated: YYYY-MM-DD — <one-line theme of the most recent session>
-
-## Latest session — YYYY-MM-DD
-
-**Theme —** <what this session was about, in a line or two.>
-
-- <what shipped>
-- <what was decided>
-- <what was learned>
-
-▶ Next: <the single clearest next step — what the next \`session-start\` should pick up.>
-
-______________________________________________________________________
-
-> Older session entries live in [\`handoff-history.md\`](handoff-history.md).
-EOF
-  echo "seeded docs/handoff.md"
+# ── seed narrative docs from templates ───────────────────────────────────
+# Rendered when the target is MISSING or still carries the unrendered marker.
+# The old "seed only if absent" guard could never fire: the kit ships these
+# files, so a copy-in / template-clone always landed them first and every
+# adopter was left with an unrendered skeleton.
+
+render_engine_dir="$(get_field "paths:" "" "^  engines:")"
+[ -n "$render_engine_dir" ] || render_engine_dir="scripts"
+engines_dir="$render_engine_dir"
+if [ -n "$tracker_url" ]; then
+  render_tracker_url="$tracker_url"
 else
-  echo "docs/handoff.md already exists — left untouched"
+  render_tracker_url="set \`tracker.url\` in \`$CONFIG_FILE\`"
 fi
 
-if [ ! -f docs/friction-log.md ]; then
-  mkdir -p docs
-  cat > docs/friction-log.md <<'EOF'
-# Friction Log
-
-> **Lean inbox (Principle #2 — the friction flywheel).** Friction surfaced during real
-> use — a bug, an awkward workflow, a recurring annoyance — recorded the moment it's
-> fresh, at session end. A periodic triage (`/triage-friction-log`) reads new entries and
-> routes each one: single incidents go **down** to the tracker; a genuine, multi-occurrence
-> **pattern** graduates **up** into a rule or skill change. Route down by default, up only
-> on repetition — so the flywheel self-regulates instead of ratcheting every week.
->
-> Each entry: the observed issue, the date surfaced, a rough severity (**H**igh / **M**edium
-> / **L**ow), and a proposed fix or next step. Link related PRs, commits, or tracker items
-> when available. Graduated entries are swept to
-> [`friction-log-archive.md`](friction-log-archive.md) so this file stays just the current
-> inbox plus the most-recent graduation marker.
->
-> Tracker board: set `tracker.url` in `config/dev-model.yaml`.
-
-## YYYY-MM-DD — inbox
-
-- **<one-line issue> (severity: <H/M/L>).** <what happened, and a proposed fix or next step.>
-EOF
-  echo "seeded docs/friction-log.md"
-else
-  echo "docs/friction-log.md already exists — left untouched"
-fi
+handoff_path="$(get_field "paths:" "" "^  handoff:")"
+[ -n "$handoff_path" ] || handoff_path="docs/handoff.md"
+handoff_history_path="$(get_field "paths:" "" "^  handoff_history:")"
+[ -n "$handoff_history_path" ] || handoff_history_path="docs/handoff-history.md"
+friction_path="$(get_field "paths:" "" "^  friction_log:")"
+[ -n "$friction_path" ] || friction_path="docs/friction-log.md"
+friction_archive_path="$(get_field "paths:" "" "^  friction_log_archive:")"
+[ -n "$friction_archive_path" ] || friction_archive_path="docs/friction-log-archive.md"
+
+seed_doc "handoff" "$handoff_path"
+seed_doc "handoff-history" "$handoff_history_path"
+seed_doc "friction-log" "$friction_path"
+seed_doc "friction-log-archive" "$friction_archive_path"
 
 # ── .gitignore: state sandbox paths ───────────────────────────────────────
 
@@ -387,13 +507,29 @@ add_ignore_line() {
 }
 add_ignore_line "state/"
 add_ignore_line ".devkit_state_root"
+# dev_session.sh copies a repo-root .mcp.json into each lane worktree so lanes
+# inherit MCP access. If yours holds literal credentials rather than ${ENV}
+# references, that copy must never be committable from a lane.
+if [ -f .mcp.json ] && grep -qE '"(.*_)?(TOKEN|SECRET|KEY|PASSWORD|AUTHORIZATION)" *: *"[^$]' .mcp.json 2>/dev/null; then
+  add_ignore_line ".mcp.json"
+  echo "note: .mcp.json appears to hold literal credentials — added to .gitignore." >&2
+  echo "      Prefer \${ENV_VAR} references so it can stay tracked." >&2
+fi
+
+# ── git hooks ────────────────────────────────────────────────────────────
+
+install_hooks
 
 # ── done ───────────────────────────────────────────────────────────────
 
 echo ""
-echo "agentic-dev-kit is bootstrapped."
+echo "agentic-dev-kit is bootstrapped (kit schema v2)."
 echo "Review config/dev-model.yaml for any remaining values (paths, doc_budgets,"
-echo "models, tracker.url, review.fallback_commands) and edit to taste."
+echo "models, review.fallback_commands) and edit to taste."
+echo ""
+echo "Upgrading later: pull the new kit files, then re-run ./init.sh — it"
+echo "migrates an older config forward in place and never touches a narrative"
+echo "doc that is actually in use."
 echo ""
 case "$runtime" in
   codex) echo "You're set — invoke \$session-start next." ;;
diff --git a/scripts/lib/kitconfig.py b/scripts/lib/kitconfig.py
new file mode 100644
index 0000000..3e2d185
--- /dev/null
+++ b/scripts/lib/kitconfig.py
@@ -0,0 +1,250 @@
+"""Stdlib-only reader for ``config/dev-model.yaml`` — the kit's single config surface.
+
+Why not PyYAML: the kit's engines are deliberately dependency-free where they sit
+in a hot loop (``pr_watch.py`` declares ``dependencies = []``) or run from a git
+hook, so *requiring* a third-party parser just to read a config value is what
+forces adopters to hardcode the value into the engine instead — the exact
+Principle #10 failure the config surface exists to prevent.
+
+This parses the **deliberately simple, hand-authored** subset the kit's config
+actually uses, and nothing else:
+
+- nested block mappings (``review:`` / ``linear:`` / ``tiers:``), any depth
+- scalars, with ``#`` comments stripped and one layer of matching quotes removed
+- inline flow lists — ``bots: [coderabbit, bugbot]`` / ``[]``
+- block lists of scalars (``- coderabbit``)
+- block lists of mappings (``doc_budgets``)
+- ``true``/``false``/``null`` and integers coerced to Python types
+
+It is **not** a YAML implementation: no anchors, no multi-line scalars, no flow
+mappings, no multi-document streams. A construct it does not understand is
+skipped rather than guessed at. If you need those, keep using
+``devmodel_config.py`` (PyYAML-backed) — the two agree on every construct this
+one supports, which the test suite pins.
+
+Usage:
+    from kitconfig import get, load_config
+
+    config = load_config()                              # config/dev-model.yaml
+    branch = get(config, "vcs.protected_branch")         # fail-loud if absent
+    bots = get(config, "review.bots", [])                # optional, with default
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+DEFAULT_CONFIG_PATH = "config/dev-model.yaml"
+
+# Sentinel so `get()` can distinguish "no default supplied" from a legitimate
+# default of None.
+_MISSING = object()
+
+
+def repo_root(start: Path | None = None) -> Path:
+    """Nearest ancestor carrying a ``.git`` entry (dir in a checkout, file in a
+    linked worktree). Walking up for the marker — rather than counting
+    ``parents[N]`` — is what lets the kit be vendored at any depth
+    (``scripts/devkit/lib/``) without rewriting a single path."""
+    here = (start or Path(__file__)).resolve()
+    for candidate in (here, *here.parents):
+        if (candidate / ".git").exists():
+            return candidate
+    return here.parents[2] if len(here.parents) >= 3 else here.parent
+
+
+def _strip_comment(value: str) -> str:
+    """Drop a trailing ``#`` comment that is outside quotes.
+
+    Naive splitting on ``#`` would truncate a legitimate value containing one
+    (a URL fragment, a branch pattern). Track quote state instead.
+    """
+    quote: str | None = None
+    for i, ch in enumerate(value):
+        if quote is None and ch in ("'", '"'):
+            quote = ch
+        elif quote is not None and ch == quote:
+            quote = None
+        elif quote is None and ch == "#":
+            # Only a `#` preceded by whitespace (or at the start) opens a comment,
+            # matching YAML — so `chore/triage-{date}#1` keeps its suffix.
+            if i == 0 or value[i - 1] in (" ", "\t"):
+                return value[:i]
+    return value
+
+
+def _coerce(raw: str) -> Any:
+    """Turn one scalar token into a Python value."""
+    text = _strip_comment(raw).strip()
+    if len(text) >= 2 and text[0] == text[-1] and text[0] in ("'", '"'):
+        return text[1:-1]
+    if text in ("", "~", "null"):
+        return None
+    low = text.lower()
+    if low == "true":
+        return True
+    if low == "false":
+        return False
+    try:
+        return int(text)
+    except ValueError:
+        return text
+
+
+def _parse_flow_list(text: str) -> list[Any]:
+    """``[a, b, "c d"]`` -> ``["a", "b", "c d"]``. Empty ``[]`` -> ``[]``."""
+    inner = text.strip()[1:-1].strip()
+    if not inner:
+        return []
+    items: list[str] = []
+    current = ""
+    quote: str | None = None
+    for ch in inner:
+        if quote is None and ch in ("'", '"'):
+            quote = ch
+            current += ch
+        elif quote is not None and ch == quote:
+            quote = None
+            current += ch
+        elif quote is None and ch == ",":
+            items.append(current)
+            current = ""
+        else:
+            current += ch
+    items.append(current)
+    return [_coerce(item) for item in items if item.strip()]
+
+
+def _indent_of(line: str) -> int:
+    return len(line) - len(line.lstrip(" "))
+
+
+def loads(text: str) -> dict[str, Any]:
+    """Parse the supported subset of a config document into nested dicts/lists."""
+    # Each frame is (indent, container). A mapping frame collects keys; a list
+    # frame collects items. Dedenting pops frames until the indent matches.
+    root: dict[str, Any] = {}
+    stack: list[tuple[int, Any]] = [(-1, root)]
+
+    lines = text.splitlines()
+    index = 0
+    while index < len(lines):
+        raw_line = lines[index]
+        index += 1
+        stripped = raw_line.strip()
+        if not stripped or stripped.startswith("#"):
+            continue
+        indent = _indent_of(raw_line)
+
+        while len(stack) > 1 and indent <= stack[-1][0]:
+            stack.pop()
+        container = stack[-1][1]
+
+        # ---- list item ----------------------------------------------------
+        if stripped.startswith("- "):
+            item_body = stripped[2:].strip()
+            if not isinstance(container, list):
+                continue  # a stray dash with no owning key — skip, never guess
+            if ":" in item_body and not item_body.startswith(("[", '"', "'")):
+                # `- path: docs/handoff.md` opens a mapping item whose remaining
+                # keys are indented further on the following lines.
+                item: dict[str, Any] = {}
+                container.append(item)
+                key, _, value = item_body.partition(":")
+                item[key.strip()] = _coerce(value)
+                # The mapping's own indent is the dash column + 2 ("- " width).
+                stack.append((indent + 1, item))
+            else:
+                container.append(_coerce(item_body))
+            continue
+
+        # ---- `key:` or `key: value` ---------------------------------------
+        if ":" not in stripped:
+            continue
+        key, _, value = stripped.partition(":")
+        key = key.strip()
+        value = _strip_comment(value).strip()
+        if not isinstance(container, dict):
+            continue
+
+        if value.startswith("[") and value.endswith("]"):
+            container[key] = _parse_flow_list(value)
+        elif value:
+            container[key] = _coerce(value)
+        else:
+            # Bare `key:` — a nested mapping or a block list, decided by the next
+            # meaningful line. Peeking (rather than defaulting to {} and mutating
+            # later) keeps the container type correct from the start.
+            nxt = next(
+                (
+                    line
+                    for line in lines[index:]
+                    if line.strip() and not line.strip().startswith("#")
+                ),
+                None,
+            )
+            if nxt is not None and _indent_of(nxt) > indent and nxt.strip().startswith("- "):
+                child: Any = []
+            elif nxt is not None and _indent_of(nxt) > indent:
+                child = {}
+            else:
+                child = None  # `key:` with nothing under it
+            container[key] = child
+            if child is not None:
+                stack.append((indent, child))
+    return root
+
+
+def load_config(path: str | Path = DEFAULT_CONFIG_PATH) -> dict[str, Any]:
+    """Load and parse the config. A relative path resolves against the repo root.
+
+    Raises ``FileNotFoundError`` when absent — a script that needs config has
+    nothing sane to fall back to.
+    """
+    target = Path(path)
+    if not target.is_absolute():
+        target = repo_root() / target
+    if not target.is_file():
+        raise FileNotFoundError(
+            f"dev-model config not found: {target} (run ./init.sh, or pass an explicit path)"
+        )
+    return loads(target.read_text(encoding="utf-8"))
+
+
+def get(config: dict[str, Any], dotted_key: str, default: Any = _MISSING) -> Any:
+    """Look up a dotted key (``"review.bots"``) in a loaded config.
+
+    Fail-loud (``KeyError``) when the key is missing and no ``default`` is given:
+    a required key silently reading as ``None`` is how an engine ends up writing
+    to the wrong path with no signal.
+    """
+    node: Any = config
+    parts = dotted_key.split(".")
+    for i, part in enumerate(parts):
+        if not isinstance(node, dict) or part not in node:
+            if default is not _MISSING:
+                return default
+            raise KeyError(
+                f"required config key '{dotted_key}' not found "
+                f"(missing at '{'.'.join(parts[: i + 1])}')"
+            )
+        node = node[part]
+    return node
+
+
+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.
+
+    Config lists are hand-authored, so a lone value written without brackets
+    (``informational_checks: coderabbit``) is accepted as a one-item list rather
+    than silently iterated character-by-character.
+    """
+    value = get(config, dotted_key, None)
+    if value is None:
+        return list(default)
+    if isinstance(value, str):
+        return [value]
+    if isinstance(value, list):
+        return [str(item) for item in value if item is not None]
+    return list(default)
diff --git a/scripts/tests/test_kitconfig.py b/scripts/tests/test_kitconfig.py
new file mode 100644
index 0000000..5534597
--- /dev/null
+++ b/scripts/tests/test_kitconfig.py
@@ -0,0 +1,167 @@
+"""Tests for the stdlib-only config reader (scripts/lib/kitconfig.py).
+
+Two things are pinned here:
+
+1. **Parity with PyYAML** on the config the kit actually ships. The reader exists
+   so engines can drop the PyYAML dependency; the moment it disagrees with a real
+   YAML parser on a construct the kit uses, that trade stops being safe. Skipped
+   (not failed) when PyYAML is absent, so the suite still runs in a bare env —
+   which is the whole point of the reader.
+2. **The supported subset**, construct by construct, so a future edit that breaks
+   inline lists or comment-stripping fails here rather than in an engine.
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+import pytest
+
+REPO_ROOT = Path(__file__).resolve().parents[2]
+sys.path.insert(0, str(REPO_ROOT / "scripts" / "lib"))
+
+import kitconfig  # noqa: E402
+
+
+SHIPPED_CONFIG = REPO_ROOT / "config" / "dev-model.yaml"
+
+
+def test_matches_pyyaml_on_the_shipped_config():
+    yaml = pytest.importorskip("yaml", reason="PyYAML absent — parity check skipped")
+    text = SHIPPED_CONFIG.read_text(encoding="utf-8")
+    assert kitconfig.loads(text) == yaml.safe_load(text)
+
+
+def test_loads_the_shipped_config_without_pyyaml():
+    config = kitconfig.load_config(SHIPPED_CONFIG)
+    assert kitconfig.get(config, "vcs.protected_branch") == "main"
+    assert kitconfig.get(config, "kit.version") == 2
+
+
+def test_nested_mappings_and_scalar_types():
+    parsed = kitconfig.loads(
+        """
+top:
+  text: hello
+  quoted: "a: b"
+  number: 42
+  yes_flag: true
+  no_flag: false
+  empty:
+  nested:
+    deeper:
+      leaf: found
+"""
+    )
+    assert parsed["top"]["text"] == "hello"
+    assert parsed["top"]["quoted"] == "a: b"
+    assert parsed["top"]["number"] == 42
+    assert parsed["top"]["yes_flag"] is True
+    assert parsed["top"]["no_flag"] is False
+    assert parsed["top"]["empty"] is None
+    assert parsed["top"]["nested"]["deeper"]["leaf"] == "found"
+
+
+def test_inline_and_block_lists():
+    parsed = kitconfig.loads(
+        """
+review:
+  bots: [coderabbit, bugbot]
+  none: []
+  markers:
+    - "first marker"
+    - second
+"""
+    )
+    assert parsed["review"]["bots"] == ["coderabbit", "bugbot"]
+    assert parsed["review"]["none"] == []
+    assert parsed["review"]["markers"] == ["first marker", "second"]
+
+
+def test_block_list_of_mappings():
+    parsed = kitconfig.loads(
+        """
+doc_budgets:
+  - path: docs/handoff.md
+    budget: 400
+    archive: docs/handoff-history.md
+  - path: docs/friction-log.md
+    budget: 150
+    archive: docs/friction-log-archive.md
+after: sentinel
+"""
+    )
+    assert parsed["doc_budgets"] == [
+        {"path": "docs/handoff.md", "budget": 400, "archive": "docs/handoff-history.md"},
+        {
+            "path": "docs/friction-log.md",
+            "budget": 150,
+            "archive": "docs/friction-log-archive.md",
+        },
+    ]
+    # The list must close cleanly — a following top-level key is not swallowed.
+    assert parsed["after"] == "sentinel"
+
+
+def test_comments_are_stripped_but_not_inside_values():
+    parsed = kitconfig.loads(
+        """
+vcs:
+  branch: main         # never committed to directly
+  pattern: "chore/triage-{date}#1"
+  url: https://example.test/board#section
+"""
+    )
+    assert parsed["vcs"]["branch"] == "main"
+    # A '#' not preceded by whitespace is part of the value, not a comment.
+    assert parsed["vcs"]["pattern"] == "chore/triage-{date}#1"
+    assert parsed["vcs"]["url"] == "https://example.test/board#section"
+
+
+def test_get_is_fail_loud_without_a_default():
+    config = {"a": {"b": 1}}
+    assert kitconfig.get(config, "a.b") == 1
+    assert kitconfig.get(config, "a.missing", "fallback") == "fallback"
+    assert kitconfig.get(config, "nope.deep", None) is None
+    with pytest.raises(KeyError, match="a.missing"):
+        kitconfig.get(config, "a.missing")
+
+
+def test_get_str_list_tolerates_a_bare_scalar():
+    config = kitconfig.loads(
+        """
+review:
+  listed: [a, b]
+  single: solo
+"""
+    )
+    assert kitconfig.get_str_list(config, "review.listed", []) == ["a", "b"]
+    # A hand-authored lone value must not iterate character-by-character.
+    assert kitconfig.get_str_list(config, "review.single", []) == ["solo"]
+    assert kitconfig.get_str_list(config, "review.absent", ["fallback"]) == ["fallback"]
+
+
+def test_load_config_reports_a_missing_file_clearly():
+    with pytest.raises(FileNotFoundError, match="dev-model config not found"):
+        kitconfig.load_config(REPO_ROOT / "config" / "does-not-exist.yaml")
+
+
+@pytest.mark.parametrize(
+    "name",
+    ["handoff.md.tmpl", "handoff-history.md.tmpl", "friction-log.md.tmpl", "friction-log-archive.md.tmpl"],
+)
+def test_narrative_templates_ship(name):
+    """init.sh renders these; a missing one silently degrades adoption to an
+    unrendered skeleton, which is the bug the templates were added to fix."""
+    assert (REPO_ROOT / "docs" / "templates" / name).is_file()
+
+
+def test_shipped_skeletons_carry_the_unrendered_marker():
+    """The marker is what lets init.sh tell 'the file the kit shipped' from 'a
+    handoff someone is using'. Without it the seed step can never fire on a
+    copy-in, which is exactly how adopters ended up with `my-project` headers."""
+    config = kitconfig.load_config(SHIPPED_CONFIG)
+    for key in ("paths.handoff", "paths.friction_log"):
+        doc = REPO_ROOT / kitconfig.get(config, key)
+        assert "devkit-template: unrendered" in doc.read_text(encoding="utf-8"), doc

From 327538ff30bcd6cf200cb59c90552fbcde9606b6 Mon Sep 17 00:00:00 2001
From: Topi Jarvinen <topi.jarvinen@gmail..com>
Date: Sat, 25 Jul 2026 00:25:28 +0300
Subject: [PATCH 2/5] fix: restore init.sh executable mode

The CI guard added in this PR caught its own regression: a sandbox adoption
test rewrote the working-tree file at the default umask, and the subsequent
`git add -A` re-staged mode 644 over the earlier update-index --chmod=+x.
Exactly the failure the check exists to catch.
---
 init.sh | 0
 1 file changed, 0 insertions(+), 0 deletions(-)
 mode change 100644 => 100755 init.sh

diff --git a/init.sh b/init.sh
old mode 100644
new mode 100755

From 45db0950e3758226ee919c38fdc3ff168a3a622d Mon Sep 17 00:00:00 2001
From: Topi Jarvinen <topi.jarvinen@gmail..com>
Date: Sat, 25 Jul 2026 00:36:40 +0300
Subject: [PATCH 3/5] fix: install hooks into core.hooksPath when it is set
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

git rev-parse --git-path hooks ignores core.hooksPath, so on a repo that sets
it (pre-commit, several monorepo layouts) the shim landed in a directory git
never reads — an inert hook, the exact failure this change removes. Also make
the template-marker probe a fixed-string grep.

Found reviewing this PR's own diff.
---
 init.sh | 11 +++++++++--
 1 file changed, 9 insertions(+), 2 deletions(-)

diff --git a/init.sh b/init.sh
index b0d3e43..7324897 100755
--- a/init.sh
+++ b/init.sh
@@ -343,7 +343,7 @@ seed_doc() {
     echo "note: template $_tmpl missing — skipped $_target" >&2
     return 0
   fi
-  if [ -f "$_target" ] && ! grep -q "$TEMPLATE_MARKER" "$_target" 2>/dev/null; then
+  if [ -f "$_target" ] && ! grep -qF "$TEMPLATE_MARKER" "$_target" 2>/dev/null; then
     echo "$_target already in use — left untouched"
     return 0
   fi
@@ -364,7 +364,14 @@ install_hooks() {
     echo "note: not a git repo yet — run 'git init' then re-run ./init.sh to install hooks" >&2
     return 0
   fi
-  hookdir="$(git rev-parse --git-path hooks 2>/dev/null || echo .git/hooks)"
+  # core.hooksPath wins over $GIT_DIR/hooks when set (pre-commit and several
+  # monorepo setups do set it). `rev-parse --git-path hooks` does NOT honor it,
+  # so installing there would put the shim somewhere git never reads — an
+  # inert hook, which is the exact failure this whole change exists to remove.
+  hookdir="$(git config --get core.hooksPath 2>/dev/null || true)"
+  if [ -z "$hookdir" ]; then
+    hookdir="$(git rev-parse --git-path hooks 2>/dev/null || echo .git/hooks)"
+  fi
   mkdir -p "$hookdir"
   for hook in pre-push; do
     src="${engines_dir}/hooks/${hook}"

From fde77f7b2d1ba29722636993bc18d99128fea6ea Mon Sep 17 00:00:00 2001
From: Topi Jarvinen <topi.jarvinen@gmail..com>
Date: Sat, 25 Jul 2026 00:45:12 +0300
Subject: [PATCH 4/5] fix(kitconfig): parse block lists that sit flush with
 their key
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Differential-testing the new reader against PyYAML across 20 constructs found
a silent-corruption bug. A block list at the SAME indent as its key —

    doc_budgets:
    - path: docs/handoff.md
      budget: 400

which is valid YAML and what most formatters emit — parsed to
{'doc_budgets': None, 'budget': 400}: the list was never created, its dashes
were dropped, and its nested keys leaked into the PARENT mapping. No error.

The single 'indent <= frame_indent' pop rule cannot express this, because a
dash at exactly the list's indent is the next sibling item, while a KEY at that
indent closes the list. Frames now carry a kind and pop under a rule that
distinguishes the two.

The kit's own config uses the indented style, so nothing shipped was
mis-parsed — but any adopter hand-editing their config, or any formatter run,
would have silently corrupted it. Found by the independent review pass on this
PR; regression tests cover both styles plus the nested-parent case.

101 tests pass; all three real configs still match PyYAML byte-for-byte.
---
 scripts/lib/kitconfig.py        | 65 ++++++++++++++++++++++++---------
 scripts/tests/test_kitconfig.py | 30 +++++++++++++++
 2 files changed, 78 insertions(+), 17 deletions(-)

diff --git a/scripts/lib/kitconfig.py b/scripts/lib/kitconfig.py
index 3e2d185..89b4295 100644
--- a/scripts/lib/kitconfig.py
+++ b/scripts/lib/kitconfig.py
@@ -122,10 +122,36 @@ def _indent_of(line: str) -> int:
 
 def loads(text: str) -> dict[str, Any]:
     """Parse the supported subset of a config document into nested dicts/lists."""
-    # Each frame is (indent, container). A mapping frame collects keys; a list
-    # frame collects items. Dedenting pops frames until the indent matches.
+    # Each frame is (indent, container, kind). Dedenting pops frames until the
+    # indent matches — but a LIST frame pops on a different rule than a mapping
+    # frame, because YAML lets a block list sit at the SAME indent as its key:
+    #
+    #     doc_budgets:          doc_budgets:
+    #     - path: a       vs      - path: a
+    #       budget: 1               budget: 1
+    #
+    # Both are valid and both appear in the wild (formatters emit the left one).
+    # A single `indent <= frame_indent` rule handles only the right one and
+    # silently corrupts the left — the list is never created, its dashes are
+    # dropped, and its nested keys land in the PARENT mapping.
     root: dict[str, Any] = {}
-    stack: list[tuple[int, Any]] = [(-1, root)]
+    stack: list[tuple[int, Any, str]] = [(-1, root, "map")]
+
+    def pop_to(indent: int, *, for_dash: bool) -> None:
+        # A mapping frame closes when a line is at or left of its indent. A list
+        # frame closes at or left of its DASH indent for a key-line, but a dash
+        # at exactly that indent is the next sibling item, so it must not close.
+        while len(stack) > 1:
+            frame_indent, _, kind = stack[-1]
+            if kind == "list" and for_dash:
+                if indent < frame_indent:
+                    stack.pop()
+                    continue
+                break
+            if indent <= frame_indent:
+                stack.pop()
+                continue
+            break
 
     lines = text.splitlines()
     index = 0
@@ -136,14 +162,14 @@ def loads(text: str) -> dict[str, Any]:
         if not stripped or stripped.startswith("#"):
             continue
         indent = _indent_of(raw_line)
+        is_dash = stripped.startswith("- ") or stripped == "-"
 
-        while len(stack) > 1 and indent <= stack[-1][0]:
-            stack.pop()
+        pop_to(indent, for_dash=is_dash)
         container = stack[-1][1]
 
         # ---- list item ----------------------------------------------------
-        if stripped.startswith("- "):
-            item_body = stripped[2:].strip()
+        if is_dash:
+            item_body = stripped[2:].strip() if stripped != "-" else ""
             if not isinstance(container, list):
                 continue  # a stray dash with no owning key — skip, never guess
             if ":" in item_body and not item_body.startswith(("[", '"', "'")):
@@ -153,8 +179,8 @@ def loads(text: str) -> dict[str, Any]:
                 container.append(item)
                 key, _, value = item_body.partition(":")
                 item[key.strip()] = _coerce(value)
-                # The mapping's own indent is the dash column + 2 ("- " width).
-                stack.append((indent + 1, item))
+                # Keys of this item sit right of the dash column.
+                stack.append((indent + 1, item, "map"))
             else:
                 container.append(_coerce(item_body))
             continue
@@ -184,15 +210,20 @@ def loads(text: str) -> dict[str, Any]:
                 ),
                 None,
             )
-            if nxt is not None and _indent_of(nxt) > indent and nxt.strip().startswith("- "):
-                child: Any = []
-            elif nxt is not None and _indent_of(nxt) > indent:
-                child = {}
+            nxt_indent = _indent_of(nxt) if nxt is not None else -1
+            nxt_is_dash = nxt is not None and (
+                nxt.strip().startswith("- ") or nxt.strip() == "-"
+            )
+            if nxt_is_dash and nxt_indent >= indent:
+                # A block list may sit at or right of its key's indent.
+                # The frame records the DASH indent so sibling items survive.
+                container[key] = []
+                stack.append((nxt_indent, container[key], "list"))
+            elif nxt is not None and nxt_indent > indent:
+                container[key] = {}
+                stack.append((indent, container[key], "map"))
             else:
-                child = None  # `key:` with nothing under it
-            container[key] = child
-            if child is not None:
-                stack.append((indent, child))
+                container[key] = None  # `key:` with nothing under it
     return root
 
 
diff --git a/scripts/tests/test_kitconfig.py b/scripts/tests/test_kitconfig.py
index 5534597..ff20473 100644
--- a/scripts/tests/test_kitconfig.py
+++ b/scripts/tests/test_kitconfig.py
@@ -104,6 +104,36 @@ def test_block_list_of_mappings():
     assert parsed["after"] == "sentinel"
 
 
+@pytest.mark.parametrize(
+    ("style", "text"),
+    [
+        # Indented under the key — the style the kit's own config uses.
+        ("indented", "a:\n  - k: 1\n    j: 2\n  - k: 3\nb: 9\n"),
+        # At the SAME indent as the key. Equally valid YAML, and what most
+        # formatters emit. This used to parse to {'a': None, 'j': 2, 'b': 9} —
+        # the list dropped and its nested keys leaked into the parent mapping,
+        # silently, with no error. Worst possible failure for a config reader.
+        ("flush", "a:\n- k: 1\n  j: 2\n- k: 3\nb: 9\n"),
+        # Flush list nested inside a mapping, with a sibling key after it.
+        ("flush-nested", "top:\n  a:\n  - k: 1\n    j: 2\n  b: 9\nz: 1\n"),
+    ],
+)
+def test_block_list_indent_styles(style, text):
+    parsed = kitconfig.loads(text)
+    owner = parsed["top"] if style == "flush-nested" else parsed
+    assert owner["a"] == [{"k": 1, "j": 2}, {"k": 3}] or owner["a"] == [{"k": 1, "j": 2}]
+    assert owner["b"] == 9
+    if style == "flush-nested":
+        assert parsed["z"] == 1
+        assert "j" not in parsed and "j" not in owner  # no key leakage
+
+
+def test_flush_list_of_scalars():
+    parsed = kitconfig.loads("markers:\n- first\n- second\nafter: 1\n")
+    assert parsed["markers"] == ["first", "second"]
+    assert parsed["after"] == 1
+
+
 def test_comments_are_stripped_but_not_inside_values():
     parsed = kitconfig.loads(
         """

From 1ba978e9ae3e6b140817681a92ab033801ff7aa7 Mon Sep 17 00:00:00 2001
From: Topi Jarvinen <topi.jarvinen@gmail..com>
Date: Sat, 25 Jul 2026 00:48:41 +0300
Subject: [PATCH 5/5] fix: address review findings on the config reader and
 templates
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Four findings from the independent review pass, all valid:

1. (major) A dash item containing ':' anywhere was treated as a mapping, so
   `- https://example.com/path` parsed to {"https": "//example.com/path"}
   instead of the string. YAML requires the colon be followed by whitespace or
   end-of-line; the guard now matches that rather than testing for a bare ':'.
   The module's own docstring promises unsupported constructs are skipped, not
   guessed at — this path guessed.

2. (major) "review skipped" appeared in BOTH noise_markers and
   unavailable_markers. It was dead weight in noise_markers (is_noise() checks
   unavailability first and returns False) but read as a precedence ambiguity.
   Removed from noise_markers in the shipped config and in migrate_kit_schema's
   heredoc, with a test asserting the two lists stay disjoint.

3. (minor) The narrative templates hard-coded sibling filenames while paths.*
   are configurable, so an adopter who repointed paths.handoff_history shipped a
   doc whose "older entries live in …" link 404s. Links now render from config:
   a bare filename when the docs are siblings, the repo-relative path otherwise.

4. (minor) re.escape on a pytest match= pattern (RUF043).

Also corrected init.sh's header and usage() text, which still described the old
seed-only-if-absent behavior and omitted the migration, hook install, and the
fact that re-running is the upgrade path.

101 tests pass; all three real configs still match PyYAML byte-for-byte.
---
 config/dev-model.yaml                  |  1 -
 docs/templates/friction-log.md.tmpl    |  2 +-
 docs/templates/handoff-history.md.tmpl |  2 +-
 docs/templates/handoff.md.tmpl         |  4 +--
 init.sh                                | 47 ++++++++++++++++++++------
 scripts/lib/kitconfig.py               | 13 +++++--
 scripts/tests/test_kitconfig.py        | 32 +++++++++++++++++-
 7 files changed, 83 insertions(+), 18 deletions(-)

diff --git a/config/dev-model.yaml b/config/dev-model.yaml
index b134614..e2d159c 100644
--- a/config/dev-model.yaml
+++ b/config/dev-model.yaml
@@ -95,7 +95,6 @@ review:
     - "<!-- this is an auto-generated comment: review in progress"
     - "<!-- walkthrough_start -->"
     - "actionable comments posted: 0"
-    - "review skipped"
     - "<!-- linear-linkback -->"
   # Bodies signalling the reviewer could not run. Deliberately NOT noise: these
   # surface and block `done`, because a blocked bot is an action signal (run the
diff --git a/docs/templates/friction-log.md.tmpl b/docs/templates/friction-log.md.tmpl
index 97bf96c..96269b5 100644
--- a/docs/templates/friction-log.md.tmpl
+++ b/docs/templates/friction-log.md.tmpl
@@ -10,7 +10,7 @@
 > Each entry: the observed issue, the date surfaced, a rough severity (**H**igh / **M**edium
 > / **L**ow), and a proposed fix or next step. Link related PRs, commits, or tracker items
 > when available. Graduated entries are swept to
-> [`friction-log-archive.md`](friction-log-archive.md) so this file stays just the current
+> [`{{FRICTION_ARCHIVE}}`]({{FRICTION_ARCHIVE}}) so this file stays just the current
 > inbox plus the most-recent graduation marker.
 >
 > Tracker board: {{TRACKER_URL}}
diff --git a/docs/templates/handoff-history.md.tmpl b/docs/templates/handoff-history.md.tmpl
index 620e059..4832453 100644
--- a/docs/templates/handoff-history.md.tmpl
+++ b/docs/templates/handoff-history.md.tmpl
@@ -1,6 +1,6 @@
 # Handoff History
 
 Archived session narratives from the living handoff. Keep active direction and the
-next step in `handoff.md`; this file is append-only history.
+next step in `{{HANDOFF}}`; this file is append-only history.
 
 ## Session log
diff --git a/docs/templates/handoff.md.tmpl b/docs/templates/handoff.md.tmpl
index eecbe4b..830bd71 100644
--- a/docs/templates/handoff.md.tmpl
+++ b/docs/templates/handoff.md.tmpl
@@ -5,7 +5,7 @@
 > memory, not a scratch note — is the single source of truth for what's done, in
 > progress, and next.
 >
-> Older session blocks graduate to [`handoff-history.md`](handoff-history.md) once this
+> Older session blocks graduate to [`{{HANDOFF_HISTORY}}`]({{HANDOFF_HISTORY}}) once this
 > file crosses its line budget (a warn-only tripwire — `{{ENGINE_DIR}}/check_doc_budget.py`).
 > Session-scoped scratch plans are exactly that: scratch. This is the handoff.
 
@@ -23,4 +23,4 @@ Last updated: {{DATE}} — <one-line theme of the most recent session>
 
 ______________________________________________________________________
 
-> Older session entries live in [`handoff-history.md`](handoff-history.md).
+> Older session entries live in [`{{HANDOFF_HISTORY}}`]({{HANDOFF_HISTORY}}).
diff --git a/init.sh b/init.sh
index 7324897..7aee470 100755
--- a/init.sh
+++ b/init.sh
@@ -1,10 +1,12 @@
 #!/bin/sh
 # init.sh — bootstrap for the agentic-dev-kit.
 #
-# Run once from the root of the repo you copied this kit into. Idempotent:
-# re-running re-prompts (showing the current value as the default) and only
-# ever adds missing lines — it never clobbers docs/handoff.md,
-# docs/friction-log.md, or duplicates .gitignore entries.
+# Run from the root of the repo you copied this kit into — at adoption, and
+# again after pulling a kit update (that is the supported upgrade path).
+# Idempotent: re-running re-prompts (showing the current value as the default),
+# migrates an older config schema forward without guessing over existing
+# values, and never clobbers a narrative doc that is already in use — only one
+# still carrying the shipped `devkit-template: unrendered` marker.
 #
 # Requires: sh, awk, grep, mv. No non-stdlib dependencies.
 
@@ -23,11 +25,15 @@ Bootstraps the agentic-dev-kit in the current repo:
      review.bots — each showing the current value in config/dev-model.yaml
      as the default. Press Enter to keep the default.
   2. Stamps the answers into config/dev-model.yaml in place.
-  3. Seeds docs/handoff.md and docs/friction-log.md from the kit's
-     skeletons, but ONLY if those files don't already exist.
-  4. Appends the kit's state-sandbox paths to .gitignore if they're
+  3. Migrates an older config schema forward in place (kit.version) and
+     stamps the current generation.
+  4. Renders the four narrative docs from docs/templates/ — but only when a
+     target is missing or still carries the unrendered marker, so a handoff
+     you are actually using is left byte-identical.
+  5. Appends the kit's state-sandbox paths to .gitignore if they're
      missing (never duplicates a line on re-run).
-  5. Prints the runtime-specific session-start invocation.
+  6. Installs the pre-push hook as a shim (honoring core.hooksPath).
+  7. Prints the runtime-specific session-start invocation.
 
 Safe to re-run at any time. Run it from the repo root (the directory that
 contains config/dev-model.yaml).
@@ -281,7 +287,6 @@ migrate_kit_schema() {
     - "<!-- this is an auto-generated comment: review in progress"
     - "<!-- walkthrough_start -->"
     - "actionable comments posted: 0"
-    - "review skipped"
     - "<!-- linear-linkback -->"
   unavailable_markers:
     - "bugbot needs on-demand usage enabled"
@@ -313,7 +318,9 @@ _render() {
   _tmpl="$1"
   _out="$2"
   awk -v project="$name" -v today="$(date +%Y-%m-%d)" \
-      -v tracker="$render_tracker_url" -v enginedir="$render_engine_dir" '
+      -v tracker="$render_tracker_url" -v enginedir="$render_engine_dir" \
+      -v handoff="$render_handoff_link" -v handoffhist="$render_handoff_history_link" \
+      -v frictionarch="$render_friction_archive_link" '
     function subst(s, tok, val,   i, acc) {
       acc = ""
       while ((i = index(s, tok)) > 0) {
@@ -328,6 +335,9 @@ _render() {
       line = subst(line, "{{DATE}}", today)
       line = subst(line, "{{TRACKER_URL}}", tracker)
       line = subst(line, "{{ENGINE_DIR}}", enginedir)
+      line = subst(line, "{{HANDOFF_HISTORY}}", handoffhist)
+      line = subst(line, "{{FRICTION_ARCHIVE}}", frictionarch)
+      line = subst(line, "{{HANDOFF}}", handoff)
       print line
     }
   ' "$_tmpl" > "${_out}.tmp.$$" && mv "${_out}.tmp.$$" "$_out"
@@ -497,6 +507,23 @@ friction_path="$(get_field "paths:" "" "^  friction_log:")"
 friction_archive_path="$(get_field "paths:" "" "^  friction_log_archive:")"
 [ -n "$friction_archive_path" ] || friction_archive_path="docs/friction-log-archive.md"
 
+# Cross-links inside the rendered docs must point at the CONFIGURED paths, not
+# the kit's default filenames — an adopter who repointed paths.handoff_history
+# would otherwise ship a doc whose "older entries live in …" link 404s. When the
+# two docs are siblings (the common case) a bare filename is the correct relative
+# link; otherwise fall back to the repo-relative path.
+_doc_link() {
+  # _doc_link <from-path> <to-path>
+  if [ "$(dirname "$1")" = "$(dirname "$2")" ]; then
+    basename "$2"
+  else
+    printf '%s\n' "$2"
+  fi
+}
+render_handoff_history_link="$(_doc_link "$handoff_path" "$handoff_history_path")"
+render_handoff_link="$(_doc_link "$handoff_history_path" "$handoff_path")"
+render_friction_archive_link="$(_doc_link "$friction_path" "$friction_archive_path")"
+
 seed_doc "handoff" "$handoff_path"
 seed_doc "handoff-history" "$handoff_history_path"
 seed_doc "friction-log" "$friction_path"
diff --git a/scripts/lib/kitconfig.py b/scripts/lib/kitconfig.py
index 89b4295..79999f1 100644
--- a/scripts/lib/kitconfig.py
+++ b/scripts/lib/kitconfig.py
@@ -32,11 +32,19 @@
 
 from __future__ import annotations
 
+import re
 from pathlib import Path
 from typing import Any
 
 DEFAULT_CONFIG_PATH = "config/dev-model.yaml"
 
+# A dash item opens a MAPPING only when it really looks like `key: value` —
+# YAML requires the colon be followed by whitespace or end-of-line. Testing for
+# a bare `":" in body` instead turns `- https://example.com` into
+# {"https": "//example.com"}: a silent guess, which this module's contract
+# explicitly forbids in favour of skipping.
+_DASH_MAPPING_KEY = re.compile(r"^[A-Za-z_][A-Za-z0-9_.\-]*:(?:\s|$)")
+
 # Sentinel so `get()` can distinguish "no default supplied" from a legitimate
 # default of None.
 _MISSING = object()
@@ -172,9 +180,10 @@ def pop_to(indent: int, *, for_dash: bool) -> None:
             item_body = stripped[2:].strip() if stripped != "-" else ""
             if not isinstance(container, list):
                 continue  # a stray dash with no owning key — skip, never guess
-            if ":" in item_body and not item_body.startswith(("[", '"', "'")):
+            if _DASH_MAPPING_KEY.match(item_body):
                 # `- path: docs/handoff.md` opens a mapping item whose remaining
-                # keys are indented further on the following lines.
+                # keys are indented further on the following lines. A scalar that
+                # merely contains a colon (`- https://host/p`) does not.
                 item: dict[str, Any] = {}
                 container.append(item)
                 key, _, value = item_body.partition(":")
diff --git a/scripts/tests/test_kitconfig.py b/scripts/tests/test_kitconfig.py
index ff20473..4dc8c65 100644
--- a/scripts/tests/test_kitconfig.py
+++ b/scripts/tests/test_kitconfig.py
@@ -13,6 +13,7 @@
 
 from __future__ import annotations
 
+import re
 import sys
 from pathlib import Path
 
@@ -154,7 +155,7 @@ def test_get_is_fail_loud_without_a_default():
     assert kitconfig.get(config, "a.b") == 1
     assert kitconfig.get(config, "a.missing", "fallback") == "fallback"
     assert kitconfig.get(config, "nope.deep", None) is None
-    with pytest.raises(KeyError, match="a.missing"):
+    with pytest.raises(KeyError, match=re.escape("a.missing")):
         kitconfig.get(config, "a.missing")
 
 
@@ -195,3 +196,32 @@ def test_shipped_skeletons_carry_the_unrendered_marker():
     for key in ("paths.handoff", "paths.friction_log"):
         doc = REPO_ROOT / kitconfig.get(config, key)
         assert "devkit-template: unrendered" in doc.read_text(encoding="utf-8"), doc
+
+
+@pytest.mark.parametrize(
+    ("text", "expected"),
+    [
+        # A scalar containing ':' is NOT a mapping — YAML requires the colon be
+        # followed by whitespace or end-of-line. Testing for a bare ':' in the
+        # body turned `- https://host/p` into {"https": "//host/p"}: a silent
+        # guess, which this module's contract forbids in favour of skipping.
+        ("a:\n  - https://example.com/path\n", ["https://example.com/path"]),
+        ("a:\n  - http://h:8080/x\n", ["http://h:8080/x"]),
+        ("a:\n  - 12:30 standup\n", ["12:30 standup"]),
+        # A genuine `key: value` item still opens a mapping.
+        ("a:\n  - k: v\n", [{"k": "v"}]),
+    ],
+)
+def test_dash_item_colon_is_not_always_a_mapping(text, expected):
+    assert kitconfig.loads(text)["a"] == expected
+
+
+def test_review_skipped_lives_only_in_unavailable_markers():
+    """`is_noise()` checks unavailability FIRST and returns False, so a marker in
+    both lists is dead weight in `noise_markers` and reads as a precedence
+    ambiguity. Keep it in exactly one place."""
+    config = kitconfig.load_config(SHIPPED_CONFIG)
+    noise = kitconfig.get_str_list(config, "review.noise_markers", [])
+    unavailable = kitconfig.get_str_list(config, "review.unavailable_markers", [])
+    assert "review skipped" in unavailable
+    assert not (set(noise) & set(unavailable)), "markers must not appear in both lists"