From 1b3b33c96cfb3f6011cc38def9a921559d284366 Mon Sep 17 00:00:00 2001
From: Kyle Sexton <153232337+kyle-sexton@users.noreply.github.com>
Date: Sun, 4 Oct 2026 20:16:34 -0400
Subject: [PATCH 1/3] docs(plugin-philosophy): run local-scope test installs
 outside a worktree

From a linked worktree, `--scope local` writes the main checkout's
.claude/settings.local.json, so a test install leaks to every session
there. State the rule under Evidence and validation with its docs basis.

Refs #6375

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 docs/plugin-philosophy.md | 13 +++++++++++++
 1 file changed, 13 insertions(+)

diff --git a/docs/plugin-philosophy.md b/docs/plugin-philosophy.md
index 12e1bcae37..36a0c35631 100644
--- a/docs/plugin-philosophy.md
+++ b/docs/plugin-philosophy.md
@@ -912,6 +912,19 @@ path and prerequisite tests, local `--plugin-dir` smoke tests, and the repositor
 Apply the standards principles of explicit behavior, fail-fast boundaries, idempotency, one mechanism
 per concern, cross-platform operation, and stress-testing before presentation.
 
+Run a test install (`claude plugin install` or `claude plugin marketplace add` with
+`--scope local`) from a throwaway folder outside any git repository, never from a linked worktree.
+Local scope writes `.claude/settings.local.json`, and in a worktree Claude Code keeps that file at
+the main checkout's root, so the install enables the plugin for every session there and outlives the
+worktree. Outside a git repository the file stays in the folder you ran from.
+
+- **Pointer:** [Where Claude Code keeps the local file in a git repository](https://code.claude.com/docs/en/settings#where-claude-code-keeps-the-local-file-in-a-git-repository);
+  [`--scope` names the settings file written](https://code.claude.com/docs/en/plugins/cli-reference).
+  Observed for `plugin install --scope local` on Claude Code 2.1.289, WSL2.
+- **As of:** 2026-10-04.
+- **Recheck trigger:** that settings section stops placing a worktree's local file at the main
+  checkout, or a release note changes where `--scope local` writes.
+
 ## Instruction economy
 
 Every standing instruction this marketplace ships is a per-session tax on every consumer, paid

From 5c3da2d259e6c355d3d3ed8e3778e9350f3babba Mon Sep 17 00:00:00 2001
From: Kyle Sexton <153232337+kyle-sexton@users.noreply.github.com>
Date: Sun, 4 Oct 2026 20:41:21 -0400
Subject: [PATCH 2/3] docs(plugin-philosophy): name the source of the
 local-scope observation

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 docs/plugin-philosophy.md | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/docs/plugin-philosophy.md b/docs/plugin-philosophy.md
index 36a0c35631..ea60745b76 100644
--- a/docs/plugin-philosophy.md
+++ b/docs/plugin-philosophy.md
@@ -920,7 +920,8 @@ worktree. Outside a git repository the file stays in the folder you ran from.
 
 - **Pointer:** [Where Claude Code keeps the local file in a git repository](https://code.claude.com/docs/en/settings#where-claude-code-keeps-the-local-file-in-a-git-repository);
   [`--scope` names the settings file written](https://code.claude.com/docs/en/plugins/cli-reference).
-  Observed for `plugin install --scope local` on Claude Code 2.1.289, WSL2.
+  Observed for `plugin install --scope local` on Claude Code 2.1.289, WSL2, during the
+  install-and-test run recorded in melodic-software/claude-code-plugins#6375.
 - **As of:** 2026-10-04.
 - **Recheck trigger:** that settings section stops placing a worktree's local file at the main
   checkout, or a release note changes where `--scope local` writes.

From e3e0a1405593923b4de4f3858917680d04b9ff34 Mon Sep 17 00:00:00 2001
From: Kyle Sexton <153232337+kyle-sexton@users.noreply.github.com>
Date: Sun, 4 Oct 2026 20:44:04 -0400
Subject: [PATCH 3/3] docs(plugin-philosophy): cite the run and the report for
 the local-scope observation

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 docs/plugin-philosophy.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/plugin-philosophy.md b/docs/plugin-philosophy.md
index ea60745b76..b664284bbd 100644
--- a/docs/plugin-philosophy.md
+++ b/docs/plugin-philosophy.md
@@ -921,7 +921,7 @@ worktree. Outside a git repository the file stays in the folder you ran from.
 - **Pointer:** [Where Claude Code keeps the local file in a git repository](https://code.claude.com/docs/en/settings#where-claude-code-keeps-the-local-file-in-a-git-repository);
   [`--scope` names the settings file written](https://code.claude.com/docs/en/plugins/cli-reference).
   Observed for `plugin install --scope local` on Claude Code 2.1.289, WSL2, during the
-  install-and-test run recorded in melodic-software/claude-code-plugins#6375.
+  install-and-test run in melodic-software/claude-code-plugins#6318, reported in #6375.
 - **As of:** 2026-10-04.
 - **Recheck trigger:** that settings section stops placing a worktree's local file at the main
   checkout, or a release note changes where `--scope local` writes.