chore: document docs repo worktree hygiene

.github/pull_request_template.md

@@ -13,3 +13,4 @@
 - [ ] This PR keeps ownership scoped to docs canon
 - [ ] This PR does not overclaim implementation ownership
 - [ ] This PR does not replace org overview as registry layer
+- [ ] This PR does not add nested local repos or worktrees under `OpenSIN-documentation/`

.github/workflows/docs.yml

@@ -17,8 +17,16 @@ name: Docs Build & Deploy
 on:
   push:
     branches: [main, fix/docs-modernize-standards]
+    paths-ignore:
+      - 'worktrees/**'
+      - '.worktrees/**'
+      - '*.wt/**'
   pull_request:
     branches: [main]
+    paths-ignore:
+      - 'worktrees/**'
+      - '.worktrees/**'
+      - '*.wt/**'
 
 # =============================================================================
 # Environment variables — Bun version pinned for reproducibility
@@ -98,6 +106,9 @@ jobs:
             --include="*.sh" \
             --exclude-dir=node_modules \
             --exclude-dir=.git \
+            --exclude-dir=worktrees \
+            --exclude-dir=.worktrees \
+            --exclude-dir='*.wt' \
             --exclude-dir=.vitepress \
             --exclude-dir=.github \
             --exclude=AGENTS.md \

.github/workflows/repo-health-check.yml

@@ -3,8 +3,16 @@ name: Repo Health Check
 on:
   push:
     branches: [main]
+    paths-ignore:
+      - 'worktrees/**'
+      - '.worktrees/**'
+      - '*.wt/**'
   pull_request:
     branches: [main]
+    paths-ignore:
+      - 'worktrees/**'
+      - '.worktrees/**'
+      - '*.wt/**'
   workflow_dispatch:
     inputs:
       scan_all_repos:
@@ -96,9 +104,9 @@ jobs:
           echo "### Secret Detection" >> $GITHUB_STEP_SUMMARY
           SECRETS_FOUND=0
 
-          # Scan for common secret patterns
+          # Scan for common secret patterns (worktree & .git excluded to prevent recursive descent and false positives)
           for pattern in "api_key\s*=\s*['\"][^'\"]*['\"]" "password\s*=\s*['\"][^'\"]*['\"]" "secret\s*=\s*['\"][^'\"]*['\"]" "token\s*=\s*sk-"; do
-            RESULTS=$(grep -rl --include="*.js" --include="*.ts" --include="*.py" --include="*.json" --include="*.env" -E "$pattern" . 2>/dev/null | grep -v node_modules | grep -v .git || true)
+            RESULTS=$(grep -rl --exclude-dir=.git --exclude-dir=node_modules --exclude-dir=venv --exclude-dir=.opencode --exclude-dir=worktrees --exclude-dir=.worktrees --exclude-dir='*.wt' --include="*.js" --include="*.ts" --include="*.py" --include="*.json" --include="*.env" -E "$pattern" . 2>/dev/null || true)
             if [ -n "$RESULTS" ]; then
               echo "- 🔴 Potential secret found matching pattern: \`$pattern\`" >> $GITHUB_STEP_SUMMARY
               echo "$RESULTS" | while read -r f; do echo "  - \`$f\`" >> $GITHUB_STEP_SUMMARY; done

.github/workflows/repo-health.yml

@@ -3,8 +3,16 @@ name: Repo Health Check
 on:
   push:
     branches: [main]
+    paths-ignore:
+      - 'worktrees/**'
+      - '.worktrees/**'
+      - '*.wt/**'
   pull_request:
     branches: [main]
+    paths-ignore:
+      - 'worktrees/**'
+      - '.worktrees/**'
+      - '*.wt/**'
 
 jobs:
   health-check:
@@ -40,10 +48,10 @@ jobs:
 
       - name: Check for banned package-lock.json
         run: |
-          LOCK_FILES=$(find . -name "package-lock.json" -not -path "*/node_modules/*" 2>/dev/null | wc -l)
+          LOCK_FILES=$(find . -name "package-lock.json" 2>/dev/null | grep -v '/node_modules/' | grep -v '/.git/' | grep -v '/worktrees/' | grep -v '/.worktrees/' | grep -v '\.wt/' | wc -l)
           if [ "$LOCK_FILES" -gt 0 ]; then
             echo "❌ Found $LOCK_FILES package-lock.json files (npm is banned, use bun)"
-            find . -name "package-lock.json" -not -path "*/node_modules/*"
+            find . -name "package-lock.json" 2>/dev/null | grep -v '/node_modules/' | grep -v '/.git/' | grep -v '/worktrees/' | grep -v '/.worktrees/' | grep -v '\.wt/'
             exit 1
           fi
           echo "✅ No package-lock.json files found (bun mandate compliance)"
@@ -80,7 +88,7 @@ jobs:
 
       - name: Check for package-lock.json after install
         run: |
-          if [ -f "package-lock.json" ]; then
+          if find . -name "package-lock.json" 2>/dev/null | grep -v '/node_modules/' | grep -v '/.git/' | grep -v '/worktrees/' | grep -v '/.worktrees/' | grep -v '\.wt/' | grep -q .; then
             echo "❌ package-lock.json was created! Remove it and use only bun.lockb"
             exit 1
           fi

.gitignore

@@ -25,3 +25,11 @@ pool-chrome-profiles/
 rotator-temp/
 source-of-truth/
 website-member.opensin.ai/
+
+# Worktree & nested git isolation (prevents recursive scans, secret false positives & watcher loops)
+/worktrees/
+/.worktrees/
+*.wt/
+.git/worktrees/
+**/.git/
+**/.git

CONTRIBUTING.md

@@ -29,12 +29,21 @@ bun ./scripts/dev-docs.mjs
 bun ./scripts/build-docs.mjs
 ```
 
+## Workspace hygiene
+
+Keep `OpenSIN-documentation/` scoped to this repo only.
+
+- Put companion repos, local clones, and worktrees in sibling directories such as `~/dev/<repo>`.
+- Do **not** place side repos inside the docs repo root, even if they are temporary.
+- Before opening a PR, verify the root stays clean with `git status --short`.
+
 ## PR checklist
 
 - [ ] Claim is backed by evidence or a source link
 - [ ] Surface registry updated when needed
 - [ ] Links resolve and anchors still work
 - [ ] Build passes locally
+- [ ] No nested local repos or worktrees were introduced into the repo root
 - [ ] llms files updated when docs map changes
 
 ## Review expectations

README.md

@@ -55,6 +55,10 @@ bun run dev
 bun ./scripts/build-docs.mjs
 ```
 
+> [!NOTE]
+> Keep companion repos and local worktrees outside this repository root.
+> Use sibling directories such as `~/dev/<repo>` so `OpenSIN-documentation/` stays clean during sync, checkout, and review.
+
 ## 📂 Structure
 
 ```text

docs/.vitepress/config.mjs

@@ -5,6 +5,13 @@ export default defineConfig({
   description: 'Guides and concepts for the OpenSIN API.',
   lang: 'en-US',
   ignoreDeadLinks: true,
+  vite: {
+    server: {
+      watch: {
+        ignored: ['**/.git/**', '**/.worktrees/**', '**/worktrees/**', '**/*.wt/**', '**/node_modules/**', '**/.opencode/**', '**/venv/**'],
+      },
+    },
+  },
   head: [
     ['link', { rel: 'icon', href: '/logo.png' }],
     ['link', { rel: 'canonical', href: 'https://docs.opensin.ai/' }],

package.json

@@ -9,6 +9,8 @@
   },
   "packageManager": "bun@latest",
   "scripts": {
+    "predev": "bun ./scripts/worktree-hygiene.mjs",
+    "prebuild": "bun ./scripts/worktree-hygiene.mjs",
     "dev": "vitepress dev docs",
     "build": "bun ./scripts/build-docs.mjs",
     "preview": "vitepress preview docs"

scripts/build-docs.mjs

@@ -1,4 +1,6 @@
 #!/usr/bin/env bun
 import { build } from 'vitepress';
+import { runWorktreeHygiene } from './worktree-hygiene.mjs';
 
+await runWorktreeHygiene();
 await build('docs');

scripts/worktree-hygiene.mjs

@@ -0,0 +1,54 @@
+#!/usr/bin/env bun
+import { readdirSync } from 'node:fs';
+import { join, relative } from 'node:path';
+
+const ROOT = process.cwd();
+const IGNORED = new Set(['node_modules', '.git', 'dist', '.vitepress', 'venv', '.opencode']);
+
+function scan(dir, depth = 0) {
+  if (depth > 3) return [];
+
+  const hits = [];
+  let entries;
+
+  try {
+    entries = readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return hits;
+  }
+
+  for (const entry of entries) {
+    const full = join(dir, entry.name);
+
+    if (entry.name === '.git') {
+      if (dir !== ROOT) hits.push(full);
+      continue;
+    }
+
+    if (IGNORED.has(entry.name)) continue;
+
+    if (entry.isDirectory()) {
+      hits.push(...scan(full, depth + 1));
+    }
+  }
+
+  return hits;
+}
+
+export function runWorktreeHygiene() {
+  const nested = scan(ROOT);
+
+  if (nested.length > 0) {
+    console.error('❌ Worktree/nested .git detected inside repository root:');
+    nested.forEach((path) => console.error(`   - ${relative(ROOT, path)}`));
+    console.error('\n⚠️  Worktrees must reside outside the repository root to prevent recursive scans, secret detector false positives, and VitePress watcher loops.');
+    console.error('👉 Move worktrees to a sibling directory (e.g., ../OpenSIN-worktrees/) or run: git worktree prune');
+    process.exit(1);
+  }
+
+  console.log('✅ Worktree hygiene check passed. No nested .git artifacts found.');
+}
+
+if (import.meta.main) {
+  runWorktreeHygiene();
+}