docs: require a feature worktree for the Direct route

[bborbe]

Problem

CLAUDE.md § Choosing a Flow routes markdown/config/yaml changes to Direct ("edit by hand, no dark-factory") but never says where that hand edit goes.

Observed 2026-08-20: I read that line, took it as authorization, and cut a branch directly in the shared ~/Documents/workspaces/vault-cli checkout. Another agent was active in that same tree on fix/session-close-tag-line-links — its branch switch moved HEAD out from under me and discarded my uncommitted edits. Recovery cost a patch/revert/re-create cycle.

This repo reliably has concurrent writers: the maintainer bot, dark-factory, and sibling Claude sessions. Four worktrees existed during that session.

Change

One paragraph under the Direct branch: Direct still means a feature worktree, with the --no-track invocation from [[Git Development Guide]] § Worktrees.

--no-track is included deliberately — omitting it makes the new branch track origin/master, so push/pull target master. Hit that too in the same session.

Docs only.

[ben-s-pull-request-reviewer]

I've reviewed the PR. Here's my consolidated report:

---

PR Review: docs: require a feature worktree for the Direct route

Verdict: APPROVE

Changes Reviewed

Single file changed: CLAUDE.md (+6 lines)

Manual Review (Documentation)

The PR adds a critical safety note to the "Direct" workflow decision tree (item 1, answering "No" to the CI pipeline question). The added text:

• Explains the "why": Documents the real-world incident (2026-08-20) where concurrent writers caused a docs branch to lose local changes
• Provides actionable guidance: Gives the exact git worktree command sequence to follow
• Fits the document style: Matches the existing format (bold callout, code block, explanatory note)

Step 4 Status

• Step 4a (ast-grep funnel): Skipped — ast-grep-runner.sh not available in allowlist
• Step 4c-sel (selector mode): selector-mode-guide.md not accessible — proceeding with manual review
• Step 4 skipped entirely: This is a docs-only PR; no Go/Python/JS source files changed

Must Fix (Critical)

None.

Should Fix (Important)

None.

Nice to Have (Optional)

None.

---

{
"verdict": "approve",
"summary": "Docs-only PR adds a safety note requiring feature worktrees even for the Direct (non-pipeline) route. The change is accurate, well-written, and documents a real incident with actionable git workflow guidance. No issues found.",
"comments": [],
"concerns_addressed": []
}