T-RQU1-worktree-scope-guard-downstream-setup

Status: planning/proposed · Impact: medium · Complexity: small

Goal

The worktree-scope-guard pre-commit hook (T-1CL4-worktree-scope-guard-pre-commit) protects the main checkout from cross-worktree edits, but today its activation (brew install lefthook + lefthook install + the lefthook.yml entry) lives only in this repo. Downstream projects that adopt the SDLC plugin run the same /sdlc:task-work flow with the same worktree-collision risk, but get none of the guard. Closing the gap makes the guard a plugin-level guarantee rather than a per-project hand-roll.

Today

The guard ships as plugin/scripts/worktree_scope_guard.ts plus a companion plugin/conventions/worktree-scope-guard.md. Activation in this repo is wired by lefthook.yml at the project root:

pre-commit:
  commands:
    worktree-scope-guard:
      run: bun run plugin/scripts/worktree_scope_guard.ts

/sdlc:setup (plugin/skills/setup/SKILL.md + plugin/skills/setup/setup_planning.ts) currently seeds docs/planning/<type>/ directories and the canonical .gitignore un-ignore block for .claude/, but does NOT touch lefthook.yml or check for lefthook’s presence. A fresh downstream project that adopts the plugin therefore has the script available under plugin/scripts/ (vendored or referenced) but no hook wiring and no install hint — the protection is silently absent. PR #78 surfaced this via review.

Proposed

/sdlc:setup becomes responsible for ensuring the worktree-scope-guard pre-commit hook is wired in every downstream project:

1. If lefthook.yml is absent, create it with just the worktree-scope-guard pre-commit block (sibling pre-commit hooks from sister tasks like T-A5H1-lefthook-project-check-pre-commit merge in non-destructively when they land).
2. If lefthook.yml exists and the block is missing, patch it in idempotently, leaving other hooks intact.
3. Report lefthook binary presence with an install hint (brew install lefthook on macOS, equivalent for other platforms) and the per-checkout lefthook install step. Do NOT auto-install the binary.
4. Document the guard’s contract and the setup behavior in plugin/skills/setup/SKILL.md and refer to it from plugin/conventions/worktree-scope-guard.md.

Approach

1. Extend plugin/skills/setup/setup_planning.ts with a --with-worktree-scope-guard step (on by default). Reuse the block-detection pattern already shipped for the .gitignore un-ignore work (T-AWEM-sdlc-setup-seeds-hooks-gitignore-unignore): read lefthook.yml, look for a fenced # --- worktree-scope-guard --- marker, insert/patch the block.
2. Plumb the new write path through --dry-run so the existing flag’s semantics (“no writes anywhere”) still hold.
3. Update plugin/skills/setup/SKILL.md and docs/skills/setup.md (flowchart) to mention the new step. The skill-doc-drift hook will flag drift if missed.
4. Add a paragraph to plugin/conventions/worktree-scope-guard.md pointing at /sdlc:setup as the canonical activation path for downstream consumers; demote the manual brew install / lefthook install recipe in lefthook.yml to a “if you’re wiring this by hand” footnote.
5. Cover with a fixture-based test under plugin/skills/setup/tests/: fresh project (no lefthook.yml), project with lefthook.yml but no guard block, project with guard block fully populated (no-op).

Files to touch

Location	Kind	Change
plugin/skills/setup/setup_planning.ts	modify	add lefthook-block
plugin/skills/setup/SKILL.md	new	document the new side-effect.
docs/skills/setup.md	modify	flowchart refresh.
plugin/conventions/worktree-scope-guard.md	modify	point at
lefthook.yml (this repo’s)	modify	demote the manual-install
plugin/skills/setup/tests/	modify	fixtures for the three cases.

Acceptance criteria

• AC-1: /sdlc:setup on a project with no lefthook.yml creates one containing the worktree-scope-guard pre-commit block.
• AC-2: /sdlc:setup on a project whose lefthook.yml lacks the guard block inserts it and leaves all other hooks byte-identical.
• AC-3: /sdlc:setup --dry-run reports what would change in lefthook.yml but does not write.
• AC-4: /sdlc:setup reports lefthook binary presence with a platform-appropriate install hint when missing; exits 0 either way (the hook wiring is still written so the guard activates once the operator installs lefthook).

Out of scope

• Auto-installing the lefthook binary. The skill nudges; the operator runs brew install lefthook.
• Merging multiple project-level pre-commit hooks into a single canonical block — that’s T-A5H1-lefthook-project-check-pre-commit’s remit and they should land independently.

Dependencies

• none

Discovery context

Spawned by PR #78 review comment from @sksizer asking whether the worktree-scope-guard hook should apply to downstream consumers, and suggesting the setup skill (or a sibling deterministic script) own its activation. The hook protects against a generic /sdlc:task-work failure mode, so it belongs at the plugin level, not per-project.

---

← Back to Tasks