diff --git a/conductor/tracks/superpowers_review_20260619/report.md b/conductor/tracks/superpowers_review_20260619/report.md index 2e0955d2..a83ab3d3 100644 --- a/conductor/tracks/superpowers_review_20260619/report.md +++ b/conductor/tracks/superpowers_review_20260619/report.md @@ -794,7 +794,66 @@ The project's master-direct workflow is a deliberate ARCH-DIFF from the skill. T ## 13. Using Git Worktrees - +## 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 ; Tests passing ( tests, 0 failures); Ready to implement ". + +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