docs: codify batch-1 operator precedents (two-lane defaults + built-in-first gate) (#557)

[kyle-sexton]

Summary

Two fleet-wide operator precedents from decision-session batch 1 (2026-07-19) were established as rulings inside issue-specific comment threads (#415, #423) but never written into the shared source-of-truth doc. This transcribes both into docs/PLUGIN-PHILOSOPHY.md (SSOT) in the file's existing voice, and points the migration playbook up at them. Docs-only; no plugin code touched.

The task framing assumed one PHILOSOPHY section + one pointer, but the file's reality overrode it faithfully: Precedent 2's home already exists (the Native-first section already carries its thesis), so it was strengthened rather than duplicated; Precedent 1 had no home, so it got a new section. The convention-resolution mechanism lives in the playbook, so the pointer attaches there. Two touchpoints, no duplicated prose — more faithful to the repo's pointer-over-copy convention than restating Native-first would have been.

Change

• docs/PLUGIN-PHILOSOPHY.md § Native-first — Precedent 2 (built-in-first customization gate, from the verification: consumer override seams gestured ("when the project documents…") but no declared location exists #423 ruling). Added the build-time gate the section lacked: before building any custom config surface (YAML concern file, bespoke seam), verify against current official Claude Code plugin documentation that no native mechanism (userConfig, environment variables, built-in per-repo config) can host the need; custom is the fallback only on genuine misfit. The section already said "prefer native / build custom only on misfit" — only the doc-verification gate is net-new, so only that was added.
• docs/PLUGIN-PHILOSOPHY.md § Two-lane convention posture — Precedent 1 (from the planning: branch-name grammar hardcoded to Conventional Commits types, no consumer seam #415 ruling). New section: a pre-prescribed convention is a hardcoded dependency to externalize; lane 1 is non-conflicting good-practice defaults, lane 2 is discover-via-setup and externalize as configuration extensibility points. States the durable principle only — the runtime mechanism (the ladder) stays in the playbook and points back up.
• docs/MIGRATION-PLAYBOOK.md § Convention-resolution ladder — pointer, not copy. The ladder now names the new posture as its durable principle and links to it, using the repo's existing §-label link style. No prose restated.

Transcribed from the primary-source operator ruling comments on #415 and #423, not paraphrased from the #557 body. Provenance stays in those rulings and this PR/commit; PHILOSOPHY does not inline-cite issue numbers (matching how the fresh-eyes doctrine landed via #306).

Verification

Precedents now live in PLUGIN-PHILOSOPHY.md (diff excerpt):

New section:

+## Two-lane convention posture
+
+A plugin must not arrive at an arbitrary consuming repo carrying pre-prescribed conventions. A
+convention baked in as a fixed default ... is a hardcoded assumption ...; that is the definition of
+a dependency, and dependencies are externalized and abstracted, not shipped as defaults ...
+1. **Non-conflicting good-practice defaults.** A shipped default is legitimate only when it ... cannot conflict in *any* repo ...
+2. **Discover via setup, externalize as configuration.** ... the plugin's setup action or skill discovers the consuming repo's conventions ... and externalizes them as configuration extensibility points ...

Native-first gate (added paragraph):

+Built-in-first is a gate on every customization surface, not a preference. Before building
+any custom config surface — a YAML concern file, a bespoke seam — first verify against the *current*
+official Claude Code plugin documentation that no native mechanism (`userConfig`, environment
+variables, a built-in per-repo config surface) can host the need ...

Migration-playbook pointer resolves to the right section. The repo has zero fragment-anchor links in docs/*.md (grep -roE '\]\([^)]+\.md#[a-z0-9-]+\)' docs/*.md → 0 matches); the established convention is a file-level link with a § Section Name label (existing examples at MIGRATION-PLAYBOOK.md:267 and :575). The new link [PLUGIN-PHILOSOPHY.md § Two-lane convention posture](PLUGIN-PHILOSOPHY.md) matches that convention exactly, and its § label names the new section heading verbatim.

Markdown linter clean (real output, .markdownlint-cli2.jsonc — the config the CI Lint markdown lane uses):

markdownlint-cli2 v0.18.1 (markdownlint v0.38.0)
Linting: 2 file(s)
Summary: 0 error(s)

editorconfig-checker clean (config .editorconfig-checker.json, the CI editorconfig lane's config): exit 0, no findings.

Version bump: none required, and none made — deliberately. This is a docs-only change touching no plugin.json (git diff --name-only → only the two docs/*.md files). The controlling precedent is #306 (e4c996cf "docs: codify the fresh-eyes checkpoint rule in plugin doctrine") — the closest analog, also a doctrine-codification change to PLUGIN-PHILOSOPHY.md; git show --stat confirms it touched only docs/PLUGIN-PHILOSOPHY.md and bumped no plugin version. Per-plugin CHANGELOG.md / version-bump delivery applies to changes to a plugin's own files (the version is the update cache key); a docs/ change delivers nothing to a consumer and has no bump vehicle.

Closes #557

Related

• convention: codify batch-1 operator precedents — two-lane defaults (discover via setup, never pre-prescribe) + built-in-first customization gate #557 — this codification issue.
• planning: branch-name grammar hardcoded to Conventional Commits types, no consumer seam #415 — source ruling for Precedent 1 (two-lane convention posture). Not edited; its ruling remains the decision provenance.
• verification: consumer override seams gestured ("when the project documents…") but no declared location exists #423 — source ruling for Precedent 2 (built-in-first customization gate). Not edited; its ruling remains the decision provenance.
• ci: portability lint lane — enforce declared agnosticism mechanically (19-issue coupling class + top review-churn source) #531 — the future portability-lint lane. A backlog comment was posted noting both precedents as future mechanical-check candidates, with links to the new PHILOSOPHY sections — no code/label change there: ci: portability lint lane — enforce declared agnosticism mechanically (19-issue coupling class + top review-churn source) #531 (comment)

🤖 Generated with a Claude Code implementation subagent (issue #557)

[claude]

Claude finished @kyle-sexton's task in 2m 0s —— View job

---

PR Review

• Gather context and understand the request
• Read changed files (docs/PLUGIN-PHILOSOPHY.md, docs/MIGRATION-PLAYBOOK.md)
• Review diff for correctness, style, and alignment with CLAUDE.md / PLUGIN-PHILOSOPHY conventions
• Post review findings

---

Docs-only, no blocking issues. Two precedents correctly transcribed from primary-source rulings into the SSOT. Changes are internally consistent, match the document's voice, and respect the repo's pointer-over-copy convention.

docs/PLUGIN-PHILOSOPHY.md — Native-first gate paragraph

Lines 80–85

The paragraph lands cleanly between the existing opener ("Build custom only on genuine misfit…") and the "Adoption gate" list. Reading it in sequence, the opener states the principle, the new paragraph operationalizes it (verify current docs, then build), and the gate then defines fitness for the native case. The flow is correct.

One minor phrasing observation: "a built-in per-repo config surface" (line 83) is intentionally abstract — the sentence sends the reader to fetch current docs rather than enumerate possibilities — so the vagueness is defensible and consistent with the "Evidence and validation" fetch-don't-recall mandate. A future reader will not be misled.

docs/PLUGIN-PHILOSOPHY.md — Two-lane convention posture

Lines 119–136

Section is well-written, matches the document's voice, and draws a clear boundary between the two lanes. The Conventional Commits parenthetical in lane 1 is well-chosen — it is a real convention a consumer could already be committed to the opposite of, which illustrates exactly why lane 1 is "narrow."

Placement between "Component stances" and "Configuration ownership and scope" is a defensible call. One could argue the posture has closer affinity with "Design boundary" (no hardcoded consumer layout) near the top, but the document is organized thematically rather than strictly hierarchically, and this is consistent with how other standalone principles (Fresh-eyes checkpoints, Authoritative references) sit further down without losing authority.

docs/MIGRATION-PLAYBOOK.md — Convention-resolution ladder pointer

Lines 263–267

Link style [PLUGIN-PHILOSOPHY.md § Two-lane convention posture](PLUGIN-PHILOSOPHY.md) matches the established pattern exactly (compare lines 273 and 581: § Setup is explicit and repeatable and § Configuration ownership and scope). No fragment anchors, file-level links with § labels — consistent. The pointer summarises the principle inline without duplicating the PHILOSOPHY prose.

One negligible compression: the pointer text drops the any emphasis from lane 1's qualifier ("cannot conflict in any repo") — the emphasis lives in PHILOSOPHY and a reader following the link will find it. Not a defect.

Other checks

• Version bump: correctly omitted; the controlling precedent (e4c996cf) confirms docs-only doctrine changes to PLUGIN-PHILOSOPHY.md carry no plugin version bump.
• No issue-number inline citations in PHILOSOPHY.md: matches the fresh-eyes doctrine precedent from docs: codify the fresh-eyes checkpoint rule in plugin doctrine #306.
• grep -roE '\]\([^)]+\.md#[a-z0-9-]+\)' returns zero matches: repo has no fragment-anchor links, and the new pointer adds none.

Summary: Clean execution. The two precedents are now durably owned in the SSOT, the playbook pointer is wired correctly, and no prose was duplicated. Ready to merge.

[kyle-sexton]

Post-green review classification

No findings requiring action. Reviewer's own checks confirm: version-bump correctly omitted (precedent e4c996cf/#306), link style matches established pattern, no duplicated prose (pointer-over-copy respected), #531 backlog comment posted as instructed.

CI green (15/15). Flipping to ready for review.

[claude]

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

---

PR Review

• Gather context and understand the request
• Read changed files (docs/PLUGIN-PHILOSOPHY.md, docs/MIGRATION-PLAYBOOK.md)
• Review diff for correctness, style, and alignment with CLAUDE.md / PLUGIN-PHILOSOPHY conventions
• Post review findings

---

Docs-only. No blocking issues. Both precedents are correctly transcribed and land cleanly in the existing document structure. The review below is a complete independent pass.

---

docs/PLUGIN-PHILOSOPHY.md — Native-first gate paragraph

Lines 80–85

The paragraph is correctly placed: the section opener states the principle ("Build custom only on genuine misfit"), the new paragraph operationalizes it as a mandatory doc-verification step, and the "Adoption gate" list that follows defines what fitness for the native surface means. The sequence is coherent and non-redundant.

The "re-fetch the documentation rather than trusting memory or an old summary" instruction is consistent with — and does not duplicate — the broader "Evidence and validation" section further down. That section governs research methodology generally; this paragraph specifically gates the customization decision. Two different scopes, correctly separated.

"a built-in per-repo config surface" is intentionally abstract — the sentence sends the reader to fetch current docs rather than enumerate an enumeration that may rot. This is the correct call for a principle-level SSOT.

docs/PLUGIN-PHILOSOPHY.md — Two-lane convention posture

Lines 119–136

The section is well-scoped and internally consistent. Three things checked explicitly:

1. No overlap with "Design boundary". That section covers layout/runtime dependencies; this section covers shipped convention defaults. Adjacent territory, different concerns.
2. No overlap with "Configuration ownership and scope". That section says which mechanism owns which value (userConfig, tracked file, etc.). This section says which conventions may be shipped as defaults at all, and how the rest are handled. Distinct.
3. The Conventional Commits parenthetical in lane 1 is the right concrete example — it names a real convention a consumer may already have an opposing opinion on, which makes "this lane is narrow" immediately intuitive rather than abstract.

Placement between "Component stances" and "Configuration ownership and scope" is defensible. A reader scanning top-to-bottom hits the design-boundary constraints (no hardcoded layout), then the component adoption decisions, then this posture (conventions as a class of dependency), then configuration ownership (how values flow at runtime). The ordering works.

The section closes without a "see playbook" pointer, which is correct — the pointer lives in the playbook, not repeated back up here.

docs/MIGRATION-PLAYBOOK.md — Convention-resolution ladder pointer

Lines 263–267

Link style [PLUGIN-PHILOSOPHY.md § Two-lane convention posture](PLUGIN-PHILOSOPHY.md) matches the repo's established pattern exactly. Compared against existing examples at lines 273 (§ Setup is explicit and repeatable) and 581 (§ Configuration ownership and scope): file-level links, § Section Name label, no fragment anchors. Consistent.

The inline summary ("a pre-prescribed convention is a hardcoded dependency, so a plugin ships a default only in lane 1 … and otherwise takes lane 2 — its setup discovers the consumer's convention and externalizes it as an extensibility point the ladder then resolves") accurately maps lanes 1 and 2 to the ladder's steps 2–3 without restating the full PHILOSOPHY prose. Pointer-over-copy convention followed correctly.

One minor compression: the summary drops the any emphasis from lane 1's qualifier. That emphasis lives in PHILOSOPHY and a reader following the link finds it. Not a defect.

Other checks

• Version bump correctly omitted. git diff --name-only → only two docs/*.md files. Controlling precedent: e4c996cf (docs: codify the fresh-eyes checkpoint rule in plugin doctrine #306, "docs: codify the fresh-eyes checkpoint rule in plugin doctrine") — same shape, no plugin version bump. Correct.
• No inline issue citations in PHILOSOPHY. Matches the docs: codify the fresh-eyes checkpoint rule in plugin doctrine #306 precedent for doctrine-codification changes.
• No fragment anchors added. grep -roE '\]\([^)]+\.md#[a-z0-9-]+\)' docs/*.md → 0 matches remains true after this PR.
• No prose duplicated across files. The two PHILOSOPHY sections are the SSOT; the playbook carries a pointer summary only.

Ready to merge.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 641f004910

ℹ️ 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 38s —— View job

---

PR Review

• Gather context and understand the request
• Read changed files (docs/PLUGIN-PHILOSOPHY.md, docs/MIGRATION-PLAYBOOK.md)
• Review changes for correctness, alignment with CLAUDE.md, and Codex feedback
• Post review findings

---

This is an independent pass covering the full two-commit diff. Two prior Claude reviews covered the initial commit (641f004); this review focuses on the follow-up commit (583acb3) that dropped environment variables from the native-first gate, while also confirming no regressions in the surrounding content.

---

583acb3 — env-var drop: Codex P2 finding correctly resolved

The Codex finding was valid. The original gate text listed three mechanisms:

no native mechanism (`userConfig`, environment variables, a built-in per-repo config surface)

This created a logical inconsistency: the Configuration ownership and scope section (same document, lines ~138–186) explicitly retires custom env channels and requires every personal/admin scalar to migrate to userConfig. As Codex noted, a developer whose need didn't fit userConfig could satisfy the gate by reaching for a new env var rather than the required tracked consumer config — defeating the gate's purpose.

The fix is minimal and correct:

-official Claude Code plugin documentation that no native mechanism (`userConfig`, environment
-variables, a built-in per-repo config surface) can host the need; the platform moves, so re-fetch
+official Claude Code plugin documentation that no native mechanism (`userConfig`, a built-in
+per-repo config surface) can host the need; the platform moves, so re-fetch

The commit message's reasoning holds: CLAUDE_PLUGIN_OPTION_* is userConfig's hook read-path, not an independent config host, so it was never a separate native mechanism to enumerate here. The two remaining entries map cleanly onto the Configuration ownership and scope table:

Remaining mechanism	Maps to
userConfig	"Personal or administrator-provided scalar"
a built-in per-repo config surface	"Tracked repository convention or rich team policy — a documented file under the consumer project"

The intentional abstraction of "a built-in per-repo config surface" is correct — it avoids enumerating a surface that might be renamed or split as the platform evolves, and the surrounding "re-fetch the documentation" instruction directs the reader to discover the current form.

Permalink: docs/PLUGIN-PHILOSOPHY.md lines 80–85

---

Residual checks

• No regression in Two-lane convention posture (lines 119–136) or the MIGRATION-PLAYBOOK.md pointer (lines 263–267). These are unchanged from 641f004 and were fully verified in the prior two passes.
• Internal consistency confirmed. The gate now enumerates only mechanisms the document elsewhere endorses; the retirement of custom env channels (lines 168–172) and the gate (lines 80–85) no longer pull in opposite directions.
• No prose duplicated. The PHILOSOPHY doc is the SSOT; the playbook carries the summary pointer only.
• Version bump correctly omitted. No plugin.json touched; consistent with the docs: codify the fresh-eyes checkpoint rule in plugin doctrine #306 precedent.
• Markdown clean. The two-line edit is a drop with no formatting change; the surrounding paragraph structure is unaffected.

---

No blocking issues. Clean execution of both the original transcription and the Codex-driven correction. Ready to merge.