docs(agents): require git worktrees

.gitignore

@@ -86,4 +86,4 @@ Marketing/.DS_Store
 
 # Local AI assistant configs
 .claude/
-CLAUDE.md
+CLAUDE.local.md

AGENTS.md

@@ -38,6 +38,34 @@ PRE‑FLIGHT_CHECKLIST (before ANY code changes)
 
 ---
 
+# WORKTREE_POLICY (Default)
+
+Goal: avoid stash hell and keep the main checkout clean.
+
+- Default to **one worktree per branch** for any non-trivial task or whenever you need to context-switch.
+- Keep the root repo checkout on `main` and clean; do not develop on `main`.
+- Prefer worktrees **outside** the repo to avoid untracked noise: `../LexiconForge.worktrees/<branch-name>/`.
+- Avoid `git stash` unless it’s an emergency; if you stash, name it and log `stash@{n}` + reason in `docs/WORKLOG.md`.
+
+Quickstart
+```bash
+mkdir -p ../LexiconForge.worktrees
+git worktree add ../LexiconForge.worktrees/<branch-name> -b <branch-name> main
+# or for an existing branch:
+git worktree add ../LexiconForge.worktrees/<branch-name> <branch-name>
+```
+
+Cleanup after PR merge
+```bash
+git worktree remove ../LexiconForge.worktrees/<branch-name>
+git branch -d <branch-name>
+git worktree prune
+```
+
+Notes
+- One branch can only be checked out in one worktree at a time (Git enforces this).
+- Node projects duplicate `node_modules` per worktree; prune old worktrees regularly.
+
 # HYPOTHESIS‑DRIVEN_PROTOCOL  
 
 PHASE 1 — Hypothesis Formation

CLAUDE.md

@@ -0,0 +1,25 @@
+# Claude Code Instructions (LexiconForge)
+
+Source of truth: `AGENTS.md`.
+
+## Worktrees (Required)
+
+- Keep the main checkout clean and on `main`.
+- Use one worktree per PR branch (avoid `git stash`).
+- Prefer worktrees outside the repo: `../LexiconForge.worktrees/<branch-name>/`.
+
+### Quickstart
+
+```bash
+mkdir -p ../LexiconForge.worktrees
+git worktree add ../LexiconForge.worktrees/<branch-name> -b <branch-name> main
+```
+
+### Cleanup after merge
+
+```bash
+git worktree remove ../LexiconForge.worktrees/<branch-name>
+git branch -d <branch-name>
+git worktree prune
+```
+

docs/WORKLOG.md

@@ -1150,6 +1150,11 @@ Next: After running with reduced logs, gather traces for 'Chapter not found' and
 - Details: Bumped `vitest`/`@vitest/*`, `vite`, `happy-dom`, and `@google/genai` (plus updated the browser importmap); adjusted OpenAI mocks in tests to use a constructible class under Vitest 4.
 - Tests: `npm audit`; `npx tsc --noEmit`; `npm test -- --run`
 
+2025-12-22 03:08 UTC - Agent workflow: require git worktrees (reduce stash churn)
+- Files: AGENTS.md; CLAUDE.md; .gitignore; docs/WORKLOG.md
+- Why: Avoid stash conflicts/context loss when multiple PRs/agents work in parallel; keep `main` checkout clean.
+- Details: Added a simple worktree policy + command snippets; introduced tracked `CLAUDE.md` and stopped ignoring it (ignore `CLAUDE.local.md` instead).
+- Tests: N/A (docs/workflow only)
 2025-12-22 03:27 UTC - Contributor docs: onboarding + decomposition plans
 - Files: CONTRIBUTING.md; docs/ONBOARDING.md; docs/plans/{EPUB-SERVICE-DECOMPOSITION.md,IMAGE-SLICE-DECOMPOSITION.md,NAVIGATION-SERVICE-DECOMPOSITION.md}; docs/WORKLOG.md
 - Why: Make first-time contributors productive quickly and capture actionable decomposition plans for known monoliths.