diff --git a/.gitignore b/.gitignore index 16c72f7..73f3706 100644 --- a/.gitignore +++ b/.gitignore @@ -86,4 +86,4 @@ Marketing/.DS_Store # Local AI assistant configs .claude/ -CLAUDE.md +CLAUDE.local.md diff --git a/AGENTS.md b/AGENTS.md index 451660d..fe796a3 100644 --- a/AGENTS.md +++ b/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//`. +- 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/ -b main +# or for an existing branch: +git worktree add ../LexiconForge.worktrees/ +``` + +Cleanup after PR merge +```bash +git worktree remove ../LexiconForge.worktrees/ +git branch -d +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 diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..b11258c --- /dev/null +++ b/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//`. + +### Quickstart + +```bash +mkdir -p ../LexiconForge.worktrees +git worktree add ../LexiconForge.worktrees/ -b main +``` + +### Cleanup after merge + +```bash +git worktree remove ../LexiconForge.worktrees/ +git branch -d +git worktree prune +``` + diff --git a/docs/WORKLOG.md b/docs/WORKLOG.md index 813121c..ae982a5 100644 --- a/docs/WORKLOG.md +++ b/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.