safehouse-worktrees

安全屋：Git 工作树

概述

Git 工作树会创建彼此隔离的操作基地，同时共享同一个仓库。你可以同时在多个分支上工作，而不会影响主工作区。

核心原则： 系统化的目录选择 + 安全验证 = 可靠隔离。

开始时声明：“正在为隔离操作设置安全屋。”

目录选择流程

按以下优先顺序执行：

1. 检查现有安全屋

# Check in priority order
ls -d .worktrees 2>/dev/null     # Preferred (hidden)
ls -d worktrees 2>/dev/null      # Alternative

**如果找到：**使用该目录。如果两个目录都存在，则优先使用 .worktrees/。

2. 检查项目配置

grep -i "worktree.*director" AGENTS.md 2>/dev/null

**如果指定了首选项：**直接使用，无需询问。

3. 询问 Don

如果没有目录，也没有配置首选项：

No safehouse directory found. Where should I set up?

1. .worktrees/ (project-local, hidden)
2. ~/.config/gangsta/worktrees/<project-name>/ (global location)

Which would you prefer?

安全验证

对于项目本地目录（.worktrees 或 worktrees）

创建安全屋前，必须验证目录已被 Git 忽略：

# Check if directory is ignored (respects local, global, and system gitignore)
git check-ignore -q .worktrees 2>/dev/null || git check-ignore -q worktrees 2>/dev/null

如果未被忽略：

1. 在 .gitignore 中添加相应条目
2. 立即提交更改
3. 继续创建安全屋

**为何至关重要：**防止意外将安全屋内容提交到仓库。

对于全局目录（~/.config/gangsta/worktrees）

无需验证 .gitignore——该目录完全位于项目之外。

创建步骤

1. 检测项目名称

project=$(basename "$(git rev-parse --show-toplevel)")

2. 创建安全屋

# Determine full path
case $LOCATION in
  .worktrees|worktrees)
    path="$LOCATION/$BRANCH_NAME"
    ;;
  ~/.config/gangsta/worktrees/*)
    path="~/.config/gangsta/worktrees/$project/$BRANCH_NAME"
    ;;
esac

# Create worktree with new branch
git worktree add "$path" -b "$BRANCH_NAME"
cd "$path"

3. 运行项目设置

**供应链提示：**包管理器安装会获取不受信任的第三方代码。如果存在锁文件，优先使用受锁文件约束的安装方式（例如使用 npm ci 而非 npm install、使用带哈希校验的 pip install 等），以降低供应链风险。

自动检测并运行相应的设置流程：

# Node.js
if [ -f package.json ]; then npm install; fi

# Rust
if [ -f Cargo.toml ]; then cargo build; fi

# Python
if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
if [ -f pyproject.toml ]; then poetry install; fi

# Go
if [ -f go.mod ]; then go mod download; fi

4. 验证干净基线

运行测试，确保安全屋从干净状态开始：

# Use project-appropriate command
npm test / cargo test / pytest / go test ./...

**如果测试失败：**报告失败情况，并询问 Don 是继续还是进行调查。

**如果测试通过：**报告已就绪。

5. 报告位置

Safehouse ready at <full-path>
Tests passing (<N> tests, 0 failures)
Ready for operations.

快速参考

情况	操作
.worktrees/ 存在	使用该目录（验证已被忽略）
worktrees/ 存在	使用该目录（验证已被忽略）
两者都存在	使用 .worktrees/
两者都不存在	检查 AGENTS.md → 询问 Don
目录未被忽略	添加到 .gitignore + 提交
基线测试失败	报告失败情况 + 询问 Don
没有 package.json/Cargo.toml	跳过依赖安装

常见错误

跳过忽略状态验证

• **问题：**安全屋内容会被跟踪，污染 Git 状态
• **修复：**创建项目本地安全屋前，始终使用 git check-ignore

臆断目录位置

• **问题：**造成不一致，违反项目约定
• **修复：**遵循优先顺序：现有目录 > 配置 > 询问

测试失败仍继续

• **问题：**无法区分新问题和既存问题
• **修复：**报告失败情况，并取得 Don 的明确许可

硬编码设置命令

• **问题：**无法适配使用不同工具的项目
• **修复：**根据项目文件自动检测

危险信号

绝不：

• 未验证目录已被忽略就创建安全屋（项目本地）
• 跳过基线测试验证
• 未询问 Don 就在测试失败时继续
• 在目录位置不明确时自行假设

始终：

• 遵循目录优先顺序：现有目录 > 配置 > 询问
• 验证项目本地目录已被忽略
• 自动检测并运行项目设置
• 验证干净的测试基线

集成

由以下内容调用：

• 资源开发——实现工作需要隔离时
• 任何需要隔离工作区的技能

配合使用：

• gangsta:exit-strategy——操作完成后清理安全屋

Omerta 合规性

• 可用性原则：已报告安全屋位置并设置检查点
• 真实性原则：基线测试结果来自实际输出，而非口头声明