feat(dispatch-worktree-automation): I-phase Sub-wave A — WorktreeCreate hook + paired-negative test (Candidate D2)

[artyhoo]

Summary

I-phase Sub-wave A of the dispatch-worktree-automation umbrella — implements PR #271 verdict Candidate D2 (ADAPT tfriedel/claude-worktree-hooks precedent). Adds a WorktreeCreate command hook that fires on claude -w <name>, replaces default git behaviour with project-specific setup (worktree under .claude/worktrees/<name>/, branch worktree-<name>, base ref origin/HEAD, node_modules symlinks). Companion paired-negative test asserts the CC command-hook contract verified live this PR via claude --print --worktree probe --settings '{...inline hook...}'. Closes PR #271 §8 ATTN 4 («WorktreeCreate stdin schema NOT published» → schema now empirically verified as {.session_id, .transcript_path, .cwd, .hook_event_name, .name}).

Changes

• NEW .claude/hooks/worktree-setup.sh (107 LOC) — WorktreeCreate command hook. Behaviour: parse .name from stdin via jq; resolve project root via CLAUDE_PROJECT_DIR env (fallback chain: stdin .cwd → git rev-parse --show-toplevel); resolve base ref via origin/HEAD → origin/main → main → HEAD; create worktree at $PROJECT_DIR/.claude/worktrees/<name>/ on branch worktree-<name>; symlink node_modules + packages/core/node_modules from primary checkout; print absolute path on stdout (ONLY thing on stdout per CC contract); idempotent on re-invoke (existing dir → reuse); exit 1 with stderr diagnostic on missing .name / unresolvable root / git worktree add failure (CAN BLOCK creation per CC contract).
• NEW packages/core/hooks/worktree-setup.test.ts (237 LOC, 10 tests, all green) — 7 positive scenarios (path, both symlinks, branch name, idempotency, single-line stdout, env precedence) + 3 paired-negative (missing .name, empty .name, unresolvable project root). Per-test temporary git repo via mktemp + git init; no real-repo mutation; mirrors inject-matching-rule.test.ts pattern + describe.skipIf(!JQ) graceful jq fallback.
• MAINTAINER-APPLIED install diff for .claude/settings.json — see §Install below. Deny-listed for agent edit per feedback_settings_json_agent_uncommittable memory → delivered as HEREDOC.

Prior-art consult

• Capability commit carries Prior-art: trailer — cites SSOT feat(skill-drift): multi-channel drift detection from D-AuditC-5 #65 (Superpowers using-git-worktrees ADOPT — native-primitive mandate that this hook operationalises) + tfriedel/claude-worktree-hooks (ADAPT precedent per PR research(dispatch-worktree-automation): R-phase — ADOPT claude -w + ADAPT WorktreeCreate hook #271 §3 Candidate D2; we customise project-setup step from npm-install to symlinks per meta-kickoff.template.md §4a workspace-optimisation pattern).
• PR research(dispatch-worktree-automation): R-phase — ADOPT claude -w + ADAPT WorktreeCreate hook #271 §6 verdict ADOPT (Candidate E claude -w) + ADAPT (Candidate D2 WorktreeCreate hook) drives this Sub-wave; no new SSOT capability area surfaced beyond what PR research(dispatch-worktree-automation): R-phase — ADOPT claude -w + ADAPT WorktreeCreate hook #271 §8 enumerates (3 new entries proposed there are deferred to a follow-up I-phase batch — out of Sub-wave A scope).
• DeepWiki query on tfriedel/claude-worktree-hooks returned «Repository not found» (not indexed); fell back to two phrasings of WebFetch (verbatim README + GitHub page) per T13 mandate — both confirm .name jq field + path-only stdout. Documented in commit body + §Active T-traps below.
• context7 not applicable (this is a runtime mechanism + paired-negative test, not a library-API change). The 6-layer BFR sweep for this candidate already ran in PR research(dispatch-worktree-automation): R-phase — ADOPT claude -w + ADAPT WorktreeCreate hook #271 §2; no re-execution in Sub-wave A.

Test plan

• npx vitest run packages/core/hooks/worktree-setup.test.ts → 10/10 green (positive 7, paired-negative 3)
• npm run typecheck --workspaces --if-present → clean across @rules-as-tests/core, @rules-as-tests/meta-factory, @rules-as-tests/preset-next-15-canonical
• npx vitest run packages/core/principles/{02-paired-negative-test,12-ai-laziness-traps,15-skill-paired-negative}.test.ts packages/core/hooks/check-hook-marker.test.ts → 21 passed / 4 skipped, no regression
• Pre-push hook ran 21 hook test files (153 tests, 4 skipped) — green push proves no regression in scope
• Smoke-test against synthetic tmp git repo before writing the vitest test — verified path / symlink / idempotent / missing-name failure paths empirically
• Live stdin-schema probe — invoked claude --print --worktree wtc-schema-probe --settings '{"hooks":{"WorktreeCreate":[{"hooks":[{"type":"command","command":"bash /tmp/probe-wtc.sh"}]}]}}' "exit"; captured stdin payload: {"session_id":"...","transcript_path":"...","cwd":"/Users/art/code/rules-as-tests-aif","hook_event_name":"WorktreeCreate","name":"wtc-schema-probe"} → .name field is the primary identifier; probe artefacts cleaned via git worktree remove --force + git branch -D (surgical, per T17 — preserve-before-destructive)
• MAINTAINER: apply .claude/settings.json HEREDOC patch (§Install below), then run claude -w probe-after-install from a fresh terminal tab to verify hook fires and worktree appears at .claude/worktrees/probe-after-install/. Expected: 1 command + paste replaces the existing ~7-step manual STEP 0 paste-block. Verification: git worktree list shows new entry; symlinks present (ls -la .claude/worktrees/probe-after-install/node_modules)
• MAINTAINER: after settings.json applied + first dispatch verified, cleanup probe via git worktree remove .claude/worktrees/probe-after-install --force && git branch -D worktree-probe-after-install

Pre-existing staging failures unrelated to this PR (verified by stash + re-run on pristine staging): pre-push.test.ts:55-65 (memory project_warn_only_flip_and_ci_backstop — CI filter masks), check-doc-authority.test.ts boundary cases (3 failures on staging before this PR).

§Install (maintainer-applied — agent-uncommittable per feedback_settings_json_agent_uncommittable)

Apply this patch from the repo root to add the WorktreeCreate event entry alongside the existing UserPromptSubmit / PreToolUse / PostToolUse / Stop hook groups:

python3 <<'PY'
import json, pathlib
p = pathlib.Path('.claude/settings.json')
data = json.loads(p.read_text())
hooks = data.setdefault('hooks', {})
entry = {
    "hooks": [
        {
            "type": "command",
            "command": "bash \"$CLAUDE_PROJECT_DIR/.claude/hooks/worktree-setup.sh\""
        }
    ]
}
existing = hooks.get('WorktreeCreate', [])
if not any(g.get('hooks', [{}])[0].get('command') == entry['hooks'][0]['command'] for g in existing):
    existing.append(entry)
hooks['WorktreeCreate'] = existing
p.write_text(json.dumps(data, indent=2) + '\n')
print('settings.json patched.')
PY

The patched fragment (what the maintainer can also paste manually instead of running the script):

"WorktreeCreate": [
  {
    "hooks": [
      {
        "type": "command",
        "command": "bash \"$CLAUDE_PROJECT_DIR/.claude/hooks/worktree-setup.sh\""
      }
    ]
  }
]

§1.7 Forward-check applied

Sweep across active .claude/rules/ for disciplines that bear on this hook + test:

• build-first-reuse-default.md §1 — verdict ADAPT for tfriedel/claude-worktree-hooks per PR research(dispatch-worktree-automation): R-phase — ADOPT claude -w + ADAPT WorktreeCreate hook #271 §3 Candidate D2: same problem class (WorktreeCreate hook for project setup), divergent mechanism (symlinks vs npm-install) rationalised via meta-kickoff.template.md §4a workspace-optimisation precedent (file:line evidence: hook comment lines 21-24).
• dual-implementation-discipline.md §3 — hook carries # @cc-only-rationale: marker (file:line .claude/hooks/worktree-setup.sh:26-27): WorktreeCreate hook event is CC-only; no portable equivalent fires at worktree-creation moment.
• no-paid-llm-in-ci.md §1 — pure deterministic bash hook + vitest assertion; zero API-billed call in runtime or CI (file:line .claude/rules/no-paid-llm-in-ci.md:14).
• phase-research-coverage.md §1.11 — stdin schema verified by direct live probe (claude --print --worktree probe --settings '{...}') rather than training-data assumption; evidence in §Test plan above + commit body §Summary (file:line .claude/rules/phase-research-coverage.md:79).
• phase-research-coverage.md §1.12 — PR body leads with the verdict (ships hook + test + install diff per Candidate D2) + 4-point rationale in §Summary + falsifier in §Falsifier below; not option-dump (file:line .claude/rules/phase-research-coverage.md:92).
• ai-laziness-traps.md §3 — active T-traps enumerated in §Active T-traps below: 8 canonical (T3, T7, T11, T13, T15, T17, T19, T20) + 3 domain-specific (T-DWA-IP-A/B/C) per kickoff-author obligation (file:line .claude/rules/ai-laziness-traps.md:14); blanket-reference avoided.
• parallel-subwave-isolation.md §1 — work executed in worktree .claude/worktrees/iphase-hook/ on branch worktree-iphase-hook; primary checkout (/Users/art/code/rules-as-tests-aif) untouched; no shared-workdir parallel violation (file:line .claude/rules/parallel-subwave-isolation.md:14).
• reviewer-discipline.md §2 — open items from PR research(dispatch-worktree-automation): R-phase — ADOPT claude -w + ADAPT WorktreeCreate hook #271 §8 (ATTN 1+2: worktree path + branch name convention) DECIDED upstream per dispatch args («CC default per ATTN 1+2 DECIDED — no rename needed»); no new DECISION-NEEDED surfaced in this Sub-wave (file:line .claude/rules/reviewer-discipline.md:17).

§1.7 Backward-check applied

Sweep of existing artefacts under this PR's recommendation scope:

• .claude/settings.json (line 60 "hooks":) — hook event registry; receives new WorktreeCreate entry via maintainer-applied HEREDOC (§Install). Not touched by agent (deny-list at lines 56-57). Will register the hook post-apply.
• .claude/hooks/inject-matching-rule.sh — precedent for bash hook structure (set -uo pipefail, jq stdin parsing, # @cc-only-rationale: marker, # spec: cross-ref). New hook mirrors the layout (file:line .claude/hooks/worktree-setup.sh:1-30 vs precedent .claude/hooks/inject-matching-rule.sh:1-16).
• packages/core/hooks/inject-matching-rule.test.ts — precedent for vitest hook test (execFileSync('bash', [HOOK]), describe.skipIf(!JQ), runHook helper). New test mirrors structure (file:line packages/core/hooks/worktree-setup.test.ts:35-72) and adds paired-negative scenarios per principles/02-paired-negative-test.test.ts discipline.
• .gitignore — does NOT yet ignore .claude/worktrees/ (PR research(dispatch-worktree-automation): R-phase — ADOPT claude -w + ADAPT WorktreeCreate hook #271 §2.6 confirmed). Out of Sub-wave A scope — separate I-phase edit target (PR research(dispatch-worktree-automation): R-phase — ADOPT claude -w + ADAPT WorktreeCreate hook #271 §8 item 7). Hook works without this .gitignore line; only consequence is git status showing worktree contents as untracked in primary checkout until follow-up lands. Will raise as follow-up batch.
• .claude/skills/meta-orchestrator/SKILL.md:324 + templates/meta-kickoff.template.md §4 + §4a + references/placeholders.md:24 — orchestrator template still emits manual git worktree add paste-blocks. Out of Sub-wave A scope — separate I-phase edit targets (PR research(dispatch-worktree-automation): R-phase — ADOPT claude -w + ADAPT WorktreeCreate hook #271 §8 items 1, 3, 4, 5). Sequencing per §8 item 4: «delete §4a IF AND ONLY IF D2 hook lands first» — this PR satisfies the precondition; template migration is the next follow-up batch.
• .claude/rules/parallel-subwave-isolation.md §1 — mandatory worktree setup block still references manual git worktree add. Out of Sub-wave A scope — separate I-phase edit target (PR research(dispatch-worktree-automation): R-phase — ADOPT claude -w + ADAPT WorktreeCreate hook #271 §8 item 6). Rule will gain claude -w as preferred channel + manual as fallback in a follow-up touch (forward-going per dual-implementation-discipline.md §9 «forward-going annotation»).
• docs/meta-factory/prior-art-evaluations.md — 3 new SSOT entries proposed in PR research(dispatch-worktree-automation): R-phase — ADOPT claude -w + ADAPT WorktreeCreate hook #271 §8 item 8 (claude -w ADOPT, WorktreeCreate event ADOPT, tfriedel/claude-worktree-hooks ADAPT) NOT included here. Commit-body Prior-art: trailer cites existing SSOT feat(skill-drift): multi-channel drift detection from D-AuditC-5 #65 as the load-bearing precedent for this commit (Superpowers using-git-worktrees — already in the register). SSOT-add follow-up batches separately.
• PR research(meta-orchestrator): SKILL.md §5 row 3 vs worker-dispatch anti-pattern drift #265 (closed unmerged) — sibling drift R-phase superseded operationally by PR research(dispatch-worktree-automation): R-phase — ADOPT claude -w + ADAPT WorktreeCreate hook #271 verdict. No re-open needed.

No artefact silently superseded. Follow-up scope explicitly listed (.gitignore item 7, SKILL.md / template / placeholders items 1+3+4+5, parallel-subwave-isolation.md item 6, prior-art-evaluations.md item 8 — each is a separate atomic batch per umbrella sequencing).

§Active T-traps (per ai-laziness-traps.md §3 — enumerate + extend, not blanket-reference)

Inherited canonical from PR #271 §6:

• T3 (file:line per claim) — every behaviour claim cites either the hook source line, the test source line, or the live-probe stdout. ✓
• T7 (run adversarial counter-prompt) — paired-negative tests execute the actual counter-prompts «what if .name missing? what if root unresolvable?» — confirmed exit non-zero with empty stdout, not asserted. ✓
• T11 (BFR §3 6-layer) — inherited from PR research(dispatch-worktree-automation): R-phase — ADOPT claude -w + ADAPT WorktreeCreate hook #271 §2.4 6-layer execution; no new candidate introduced. ✓
• T13 (verify ADOPTED items have upstream evidence) — tfriedel/claude-worktree-hooks DeepWiki returned «not indexed»; fell back to two phrasings WebFetch (GitHub repo page + raw README.md). Both confirm .name jq field + path-only stdout. Pattern adapted (not blind-copied): we customise project-setup step (symlinks vs npm-install) per workspace-optimisation pattern — rationale in hook comments lines 21-24. ✓
• T15 (self-application) — hook applies to its own future use: once installed, the next sub-wave dispatch in this umbrella (.gitignore follow-up batch, SKILL.md migration batch, etc.) will go through this hook. Recursive self-application live. ✓
• T17 (preserve before destructive) — probe artefacts (worktree /tmp/wtc-probe-87483, branch wtc-probe-87483) cleaned via git worktree remove --force + git branch -D, surgical only — never bulk-recursive delete. Hook tests use Node rmSync for tmpdir cleanup (not Bash → git-safety hook bypass safe by design). ✓
• T19 (own cold-QA before handoff) — bash smoke-tested hook end-to-end against synthetic tmp git repo BEFORE writing the vitest test; vitest + typecheck + principle re-run before commit. ✓
• T20 (verdict backed by evidence) — every behaviour claim in the hook is asserted in the test; live-probe payload is the evidence for the .name field choice. ✓

Domain-specific I-phase traps:

• T-DWA-IP-A «Field name assumed from precedent without live verification» — counter: live claude --print --worktree probe --settings '{...inline hook...}' ran 2026-05-29 confirming the {.session_id, .transcript_path, .cwd, .hook_event_name, .name} payload shape. Closes PR research(dispatch-worktree-automation): R-phase — ADOPT claude -w + ADAPT WorktreeCreate hook #271 §8 ATTN 4. ✓
• T-DWA-IP-B «Symlinks claimed without filesystem assertion» — counter: test invokes readlinkSync on both symlink paths (cases «symlinks node_modules» + «symlinks packages/core/node_modules»), asserting both target (not just file presence). Test repo commits packages/core/.keep so git worktree add checks out the directory (production layout reproduction). ✓
• T-DWA-IP-C «Settings.json self-edit shortcut» — counter: deny-list blocks Edit/Write(.claude/settings.json) at settings.json lines 56-57; PR body §Install delivers HEREDOC Python recipe for maintainer-applied install per feedback_settings_json_agent_uncommittable memory. No agent commit on the settings file. ✓

§Falsifier

Wrong if:

(a) .name stdin field renamed by Anthropic in a future CC release → hook exits 1 with diagnostic missing .name in WorktreeCreate stdin payload; CC reports creation failure; maintainer notices first dispatch attempt failing → re-run probe, update field name. Re-probe procedure documented in §Test plan above.

(b) origin/HEAD resolution fails on a fresh clone before first git fetch → BASE_REF fallback chain catches via origin/main → main → HEAD; worktree still created. Verified by test «valid stdin → creates worktree» on a fresh tmp repo with only local main branch.

(c) Primary checkout has no node_modules (fresh clone before install) → symlink step silently skipped ([[ -e "$PROJECT_DIR/node_modules" ]] guard); worktree still created with bare structure; first npm invocation in worktree triggers fresh install (acceptable degraded path, matches tfriedel original behaviour).

(d) WorktreeCreate hook contract changes from «print path on stdout» to a JSON output → hook continues to print path; would need migration. Mitigation: monitor code.claude.com/docs/en/hooks for contract change; the dual-channel discipline marker (# @dual-pair: if a portable agent equivalent ever exists) is currently not applicable per dual-implementation-discipline.md §3 (CC-only event).

(e) CC silently ignores hook output and uses default behaviour despite hook installation → defeats Sub-wave A intent. Maintainer post-install smoke-test (§Test plan checkbox) catches this; falls back to manual STEP 0 paste-blocks while CC contract issue is filed upstream.

Prior-art: prior-art-evaluations.md#65 (Superpowers using-git-worktrees ADOPT — native-primitive mandate operationalised by this hook).