docs(migration-playbook): record convention-seam ratification limitation

[kyle-sexton]

Summary

Closes the #1187 provenance audit with a durable decision record in MIGRATION-PLAYBOOK, rather than
a forgery-prone gate.

Finding: in this solo-autonomous setup the operator and every agent act as the same kyle-sexton
identity, so no in-repo signal (author / reviewer / merger / commit signature) distinguishes human
ratification from agent accretion — a repo-wide property, not a per-seam defect. All 12
docs/conventions/* seams are PR-introduced and cite a ratifying issue/PR; none was silently accreted.

Decision: decline CODEOWNERS / human-ratified label / signing gates under the shared identity —
an agent satisfies the same gate, so they manufacture false assurance (theater). The only real
distinguisher is a separate human-only identity/signing key agents don't hold; flagged as an infra
option with a revisit trigger, not imposed. Interim posture: ratification stays trust-based and
visible via cited issues/PRs + operator engagement, with the audit trail as the durable account.

Docs-only (marketplace governance doc — no plugin shipped-content change, no version bump).

Test plan

• lychee --offline docs/MIGRATION-PLAYBOOK.md — clean.
• Decision record follows the doc's existing dated-decision-record format.

Related

• Closes conventions: audit provenance/ratification of docs/conventions/* seams (human vs agent-as-kyle-sexton) #1187
• Concludes the #163434 work stream (feat(source-control): well-known default path for neutral convention SSOT (F1–F4) #1185 well-known path, docs(config-cascade): rename consumer-config-layering seam → config-cascade #1190 config-cascade rename, fix(source-control): state well-known rung git-tracked requirement on both surfaces #1192 cross-surface fix)

🤖 Generated with Claude Code

[claude]

Claude finished @kyle-sexton's task in 1m 49s —— View job

---

PR Review

• Gather context and read CLAUDE.md / REVIEW.md
• Read the PR diff
• Review the changed file
• Post review findings

---

This is a docs-only decision record appended to docs/MIGRATION-PLAYBOOK.md. No plugin shipped-content, no manifest, no version bump — the REVIEW.md blocking checks (authorization, secrets, injection, atomicity) don't apply here.

The reasoning is sound: under a shared-identity setup, any in-repo gate an agent can satisfy is theater, and the record is honest about that rather than papering over it. The format matches the existing dated-decision-record convention in the document.

Two clarity nits worth addressing before merge:

---

🟡 Nit 1 — Seam count vs directory count

The record states:

All 12 docs/conventions/* seams are PR-introduced…

docs/conventions/ currently contains 13 directories. The 13th is the consumer-config-layering/ compatibility tombstone left by PR #1190 — its README.md states it is preserved only for old cached plugin installs, not an active seam. The count of 12 is therefore correct, but a future reader browsing the directory will see 13 entries and have to investigate to reconcile the discrepancy.

Suggested addition (inline): "…All 12 active docs/conventions/* seams…" or a parenthetical note such as "(excluding the consumer-config-layering/ compatibility tombstone from #1190)".

---

🟡 Nit 2 — Opaque #163434 reference

Line 1170:

…the operator's explicit engagement on that thread (as in the #163434 session)…

Every other #-prefixed reference in this document is a GitHub issue or PR in the hundreds-to-low-thousands range (e.g. #649, #1187, #1192). #163434 is five digits, which either means it lives in a different system (a session ID, a Slack thread, an external tracker) or is an unusually high-numbered item. Either way it's opaque to a reader who isn't familiar with the specific audit session. A brief qualifier — e.g. "session #163434" → "the 2026-07-23 audit session" or "issue #163434 in melodic-software/medley" — would make the reference self-explanatory.

---

Overall: the decision is clearly articulated, honestly scoped, and follows the document's record format. Neither nit is blocking; the logic and posture are correct as written.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: cfdda99473

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[claude]

Claude finished @kyle-sexton's task in 1m 46s —— View job

---

PR Review

• Gather context
• Read the PR diff (HEAD: df795b9)
• Review changed file
• Post findings

---

Review of docs/MIGRATION-PLAYBOOK.md — decision record (2026-07-23)

This review covers both commits in the PR: the original record (cfdda99) and the correction commit (df795b98) that addressed the Codex P2 findings.

The correction commit does its job. The two Codex P2s are properly addressed:

1. Identity claim — the original over-broad "operator and every agent act as the same kyle-sexton identity" was directly contradicted by this record's own commit author (Codex <codex@openai.com>). The fix splits the analysis into two provenance layers (git commit metadata vs. GitHub account actions), which is the accurate and useful distinction. The "soft, not proof" caveat on commit-author metadata is correct (any agent can spoof git config user.email).

2. In-doc citation coverage — the original claim that each seam "cites a ratifying issue/PR" was incorrect for hook-precision and seam-phrasing (verified: neither README has an issue reference). The fix accurately narrows this to "PR-introduced from git history" with honest acknowledgement that in-doc citation is inconsistent today.

---

Two residual items not addressed in df795b9:

🟡 Nit 1 — #163434 is still an opaque reference (line 1183)

…the operator's explicit engagement on that thread (as in the #163434 session) is
the ratification signal.

Every other #-prefixed identifier in this document is a GitHub issue or PR (e.g. #649, #1187, #1192). #163434 is five digits and doesn't appear in this repository's issue tracker, so a reader has no way to resolve it. If it's a session ID, a Slack thread, or an issue in a different repo, a brief qualifier would make it self-explanatory — e.g. "the 2026-07-23 audit session" or "session #163434 (melodic-software/medley)".

This was flagged by the previous Claude review and remains unaddressed. Not blocking, but will confuse a future auditor. Fix this →

🟡 Nit 2 — "12 seams" count without "active" qualifier (line 1145)

docs/conventions/ now contains 13 directories: 12 active seams + the consumer-config-layering/ compatibility tombstone. The text says "All 12 docs/conventions/* seams" which is correct, but a reader browsing the directory will see 13 entries and have to investigate. Adding "active" (or a parenthetical excluding the tombstone) removes that friction. The tombstone is explained elsewhere in the document, but not at the point where the count appears. Fix this →

---

Overall: The decision record is well-reasoned and the correction commit substantially improves accuracy. The two-provenance-layer model is the right framing and it's now correctly documented. Neither residual nit is blocking. The posture — naming the limitation honestly rather than installing theater gates — is sound.