chore: update handoff — first real adopter upgrade shipped, 17 issues filed

[topij]

Session wrap-up for the adopter-upgrade session.

What shipped

5 PRs merged across two repos:

OpenKitchen #256	pre-v2 install → schema v2: config migrated with no value changed, pre-push hook finally installed, all 10 differs files refreshed
OpenKitchen #257	review.bots: [] — that repo has no bot that delivers a verdict
OpenKitchen #258	doc sync (one commit behind after #43)
kit #43	panel isolation must be of the repo under review
kit #49	test suite detached from ambient config (closes #48)

What the session actually produced

The upgrade worked. What it mostly produced was evidence about the kit — 17 issues, and one recurring shape:

The kit's quality mechanisms each cover a different subset of the kit, and nothing checks they agree. KIT_OWNED tracks 24 of 37 shipped files; the manifest tracks 0 test files; the suite covers 0 lines of pre-push. Every gap between them is where a file can be shipped, depended on, linked to, and invisible to all three. That is the root cause of #36, #40, #41 and #51, and it is how a dangling doc link shipped to an adopter under a clean 0 differ, 0 unknown report. #47 is the single check that closes the class and is the highest-leverage item in the backlog.

Two others worth reading before the next session:

• pre-push is all-or-nothing: an adopter with its own hook logic must choose between it and the kit's #46 — pre-push is all-or-nothing, and it blocks cs-toolkit: that repo's hook carries two guards the kit's does not (auto/daily protection, detect-secrets) and no config key can express either.
• Mutation testing can leave a stale .pyc that survives the restore — every result after it is suspect #50 — a mutation preserving source length leaves stale bytecode Python treats as valid, so a git-clean restore does not restore. This casts doubt backwards on mutation evidence gathered earlier in the session, including on the already-merged #256. The code that landed there is byte-identical to the kit and passed the kit's own CI, so I do not believe anything is wrong — but "the mutants were killed" is not a claim that can be stood behind for that PR.

Housekeeping done

• archive_plan_sessions.py --keep 4 — handoff 447 → 377 lines, back under budget; the 2026-07-25 block moved to kit-handoff-history.md verbatim. Both files staged.
• No friction-log entry, deliberately: the log is AT its 150-line budget carrying an explicit "sweep required before the next entry" tripwire, and this session's friction was routed straight to Issues — which is the Principle feat: add Codex-compatible workflows #2 routing, not a neglected inbox. The handoff records that triage-friction-log is now blocking, and that the claim-drift pattern already in the inbox gained five more instances this session.

Next session

cs-toolkit Phase 1 only — install config/dev-model.yaml + init.sh +
kit-manifest.json + kitconfig.py + kit_doctor.py (additive, zero behaviour
change), get a real kit_doctor reading, then stop.

Deferring the pr_watch swap (the nightly fixer is in active development this week) and the pre-push swap (blocked on #46).

One correction to the written runbook, recorded in the handoff so the next session does not lose an hour: the done → converged change is in .claude/commands/pr-watch.md lines 11/13/39, not nightly-fixer.md, which only delegates to it. Following the runbook literally finds nothing there — and the failure mode is a silent infinite poll, not an error.

https://claude.ai/code/session_01V27wAgECMEApqAvmJMFyqm

Summary by CodeRabbit

• Documentation
  • Added a detailed archived handoff record for the July 25 session, including resolved issues, decisions, and lessons learned.
  • Updated the latest handoff guidance with July 26 adopter upgrade outcomes, observed invariants, decisions, and next-run instructions.
  • Clarified where older session entries and active follow-up items are maintained.

[coderabbitai]

📝 Walkthrough

Walkthrough

The PR updates handoff documentation with archived 2026-07-25 session details, a new 2026-07-26 adopter-upgrade summary, revised next steps, and an updated cross-reference for older session entries.

Changes

Handoff documentation

Layer / File(s)	Summary
Archive the 2026-07-25 session docs/kit-handoff-history.md	Adds the session narrative, corrected issues, decisions, lessons, and supersession note.
Update the current adopter-upgrade handoff docs/kit-handoff.md	Adds the latest session outcomes and next steps, and redirects older-session references to the history document.

Estimated code review effort: 2 (Simple) | ~8 minutes

Possibly related issues

• Derive KIT_OWNED from the shipped tree and fail CI when they diverge #47 — The updated handoff records ownership-boundary and drift-authority concerns described by this issue.

Possibly related PRs

• topij/agentic-dev-kit#30 — Updates the same handoff documents with related Phase 3b lessons and session continuity.
• topij/agentic-dev-kit#34 — Updates docs/kit-handoff.md with overlapping adopter-upgrade and fallback-review outcomes.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Linked Issues check	⚠️ Warning	The PR only updates handoff documentation and does not implement the test-suite isolation required by #48.	Add the code or fixture changes that stop kit tests from inheriting ambient review.bots, such as explicit injection or per-test config pinning.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly reflects the handoff update and the adopter-upgrade session summary.
Out of Scope Changes check	✅ Passed	The changes stay within handoff documentation updates and do not introduce unrelated code or features.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch chore/update-handoff-2026-07-26

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/kit-handoff.md`:
- Around line 373-374: Reconcile the archive reference near the “Open for next
session” section with the older session blocks still present in this document:
either move the blocks covered by the archive pointer into
kit-handoff-history.md, or revise the pointer text so it accurately states that
those entries remain here.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: c9acba6e-6ff7-4ccb-8bc1-cdff2b39108d

📥 Commits

Reviewing files that changed from the base of the PR and between 567d566 and 9ac7353.

📒 Files selected for processing (2)

• docs/kit-handoff-history.md
• docs/kit-handoff.md

[coderabbitai]

🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

Reconcile the archive pointer with the entries still in this file.

This text says older entries live in kit-handoff-history.md, but this document still contains earlier session blocks at Lines 105-369. Either move those blocks to the history file or change the wording so readers are not directed away from entries that remain here.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/kit-handoff.md` around lines 373 - 374, Reconcile the archive reference
near the “Open for next session” section with the older session blocks still
present in this document: either move the blocks covered by the archive pointer
into kit-handoff-history.md, or revise the pointer text so it accurately states
that those entries remain here.

[topij]

Valid finding — thank you. Not fixed here, deliberately: the defect is in the engine, and filed as #53.

The pointer text is not authored in this document. It is generated by scripts/archive_plan_sessions.py:73-74, which hardcodes both lines and rewrote the previous pointer during this PR's sweep. Hand-editing it in kit-handoff.md would be overwritten by the next sweep, and editing the engine to suit one repo is the anti-pattern the kit exists to prevent.

Checked the substance rather than taking it on trust, and it is worse than the comment suggests — the second line is false in two independent ways:

1. It references a section that does not exist.

grep -c 'Open for next session' docs/kit-handoff.md   -> 1

That one occurrence is the generated pointer itself. This handoff calls the section **Open, and owned by nothing yet** (3 occurrences), and docs/templates/handoff.md.tmpl — the skeleton shipped to adopters — contains the phrase 0 times. So every adopter who runs a sweep inherits the same dangling reference.

2. It claims a step the script never performs. There is no folding logic in the file; it moves blocks verbatim, as its own docstring says. On this sweep that was harmless — the swept 2026-07-25 block ended ✔ Superseded by the Phase 3a session, so it carried nothing open — but a future sweep of a block with live open items would move them out while the pointer asserts they were carried forward. That is exactly how an item gets silently dropped between sessions.

On the first half of the suggestion (move the older blocks into the history file): the four remaining blocks are the intended live set — archive_plan_sessions.py --keep 4 was run precisely to bring the handoff from 447 back to 377 lines against a 400-line budget. Sweeping more would be correct only if the budget demanded it, and it does not.

Fittingly, this is the same failure this PR's own session block is about: a narrative surface asserting something the artifact does not support. The distinguishing feature here is that an engine generates the false claim, so it reproduces identically in every adopter rather than depending on an author's carelessness.