conductor(track): superpowers review section 13 — using-git-worktrees (brief)

2026-07-05 13:30:31 -04:00
parent aeb1f0bf1c
commit 751e2d51b8
1 changed files with 60 additions and 1 deletions
@@ -794,7 +794,66 @@ The project's master-direct workflow is a deliberate ARCH-DIFF from the skill. T

 ## 13. Using Git Worktrees

-<!-- Section 13 brief (50-150 LOC). Skill: using-git-worktrees. Verdict pending. -->
+## 13. Using Git Worktrees
+
+### 13.1 What the skill prescribes
+
+The `using-git-worktrees` skill ensures isolated workspaces for feature work. Core principle: "Detect existing isolation first. Then use native tools. Then fall back to git. Never fight the harness."
+
+The 5-step Process (Step 0 → Step 4):
+
+- **Step 0: Detect Existing Isolation** — Check `GIT_DIR` vs `GIT_COMMON`; submodule guard via `git rev-parse --show-superproject-working-tree`. If already in a linked worktree, skip to Step 3. If in normal repo or submodule, ask user for consent.
+- **Step 1: Create Isolated Workspace** — Try native tools first (e.g., `EnterWorktree`, `WorktreeCreate`, `--worktree` flag). If no native tool, fall back to manual `git worktree add`. Directory selection priority: declared user preference > existing `.worktrees/` (hidden) or `worktrees/` (alt) > `~/.config/superpowers/worktrees/$project` (legacy global) > default `.worktrees/`.
+- **Step 3: Project Setup** — Auto-detect package manager (npm, pip, poetry, cargo, go mod, etc.) and run install.
+- **Step 4: Verify Clean Baseline** — Run tests to ensure workspace starts clean. If tests fail, report and ask. If pass, report "Worktree ready at <path>; Tests passing (<N> tests, 0 failures); Ready to implement <feature>".
+
+Red Flags: Never create worktree when Step 0 detects existing isolation; never use `git worktree add` when native tool exists (the #1 mistake); never skip Step 1a; never create without verifying ignored (project-local); never skip baseline test verification; never proceed with failing tests.
+
+### 13.2 Mapping to the project's existing pattern
+
+The project doesn't use git worktrees. It works on master directly (per Sections 8 and 12). The tier-2-autonomous-sandbox track (`conductor/archive/tier2_autonomous_sandbox_20260616/`) is the only track that uses worktrees, and it's a sandbox for unattended execution, not a normal workflow.
+
+| Skill rule | Project equivalent | Where |
+|---|---|---|
+| "Step 0: Detect Existing Isolation" | n/a — project doesn't use worktrees | — |
+| "Step 1: Create Isolated Workspace" | The tier-2-autonomous-sandbox track is the only worktree-using track; per `conductor/tier2/opencode.json.fragment` + the sandbox's own setup | `conductor/tier2/opencode.json.fragment` |
+| "Native tools preferred over git worktree add" | The OpenCode harness doesn't have a native worktree tool for this project; tier-2 sandbox uses `git worktree add` directly | `conductor/tier2/opencode.json.fragment` |
+| "Directory priority: declared > existing > global legacy > default" | The tier-2 sandbox uses `C:\Users\Ed\AppData\Local\Temp\opencode\` per `conductor/workflow.md` §"Conductor Token Firewalling" §0 | `conductor/workflow.md` |
+| "Step 3: Project Setup" | The `pyproject.toml` is the Python project config; `uv` is the package manager | `pyproject.toml` |
+| "Step 4: Verify Clean Baseline" | Phase Completion Verification §3 (the project's "verify baseline" is the test suite pass) | `conductor/workflow.md` |
+| "Verify worktree path is ignored (project-local)" | n/a | — |
+| "Sandbox fallback: if worktree creation fails with permission error" | The tier-2 sandbox has explicit permission deny rules (per `conductor/tier2/opencode.json.fragment`) for git push, git checkout, git restore, git reset; the sandbox's "permission error" handling is via the OpenCode harness | `conductor/tier2/opencode.json.fragment` |
+| "Always run Step 0 detection first" | n/a | — |
+
+### 13.3 Where the project already follows the discipline
+
+- **The Phase Completion Verification "Verify Clean Baseline" rule** is the project's equivalent of Step 4. Tests must pass before the phase checkpoint.
+- **The tier-2-autonomous-sandbox track's use of worktrees** is correct: it's a sandbox for unattended execution, not a normal workflow. The skill's Step 0 detection is unnecessary because the tier-2 sandbox explicitly creates its own worktree.
+
+### 13.4 Where the project doesn't follow the discipline
+
+- **The project doesn't use worktrees for normal track execution** (per Sections 8 and 12). This is a deliberate user-driven choice; the skill recommends worktrees but the user has chosen master-direct workflow.
+- **The project doesn't have a "Step 0 detect existing isolation" rule** for normal tracks. This is fine because the project doesn't use worktrees.
+- **The project's master-direct workflow** has been documented as a user choice (per Section 8 ARCH-DIFF).
+
+### 13.5 Recommendations summary
+
+The project's master-direct workflow is an intentional ARCH-DIFF. The skill applies only to the tier-2-autonomous-sandbox track. The deferred rebuild may want to:
+
+- **LOW:** No action needed. The tier-2 sandbox already follows the skill correctly for its sandbox use case.
+
+**Verdict.**
+
+| Field | Value |
+|---|---|
+| **Primary** | `ARCH-DIFF` |
+| **Integration tag** | `INTEGRATED` |
+| **Section size** | brief |
+| **Cross-refs** | nagent_review_20260608 §5 (project's "durable work" thesis); fable_review_20260617 §13 (project's master-direct workflow as "genuinely useful"); intent_dsl_survey_20260612 §6 |
+
+**Rationale.** The project's master-direct workflow is an intentional ARCH-DIFF from the skill's recommended worktree workflow. The skill applies to the tier-2-autonomous-sandbox track (which uses worktrees correctly). The project's normal track execution doesn't use worktrees; this is a deliberate user-driven choice.
+
+**Recommended change.** *(blank — no rebuild action. The master-direct workflow is intentional.)*

 ## 14. Writing Skills