feat(server): let t3.json skip worktree submodule init

[BrinkhaT]

Problem

After #7674, creating a worktree always runs git submodule update --init --recursive. That is the right default when a repo keeps skills or shared tooling in a submodule, but it is expensive for repositories with many submodules that only need a subset in each worktree. There is no project-level way to skip the built-in step.

Change

Add optional initSubmodulesOnWorktreeCreate to t3.json.

• omitted or true: keep today's behavior
• false: skip the automatic submodule checkout in createWorktree

Repos that want a subset can initialize it from a runOnWorktreeCreate action. Set that action's async field to false if the agent should wait until those submodules exist.

The flag is read from the new worktree's t3.json, so thread worktrees, PR worktrees, and the raw RPC all honor it.

Tests

• schema decode and published JSON schema keys
• worktrees still check out submodules by default
• t3.json with false leaves the submodule empty

Model: Grok 4.6 via T3 Code / Grok Build.

Summary by CodeRabbit

• New Features

  • Added the initSubmodulesOnWorktreeCreate project setting to control whether submodules are initialized automatically when creating a worktree.
  • Submodule initialization remains enabled by default; setting the option to false skips the automatic checkout.

• Documentation

  • Documented the new setting and how to initialize submodules through worktree creation actions when automatic initialization is disabled.

[macroscopeapp]

Approvability

Verdict: Not approved

Macroscope's review found this PR not approvable — This PR adds an explicit, tested t3.json option that can suppress recursive submodule initialization during production worktree creation while preserving the existing default. Because it changes shared VCS behavior and the author is new to the touched areas, human review is warranted.

^{You can add or adjust custom eligibility rules. Learn more.}

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Advanced

Run ID: 58b31560-4ce5-4286-a774-136b548f4f76

📥 Commits

Reviewing files that changed from the base of the PR and between 52e4b44 and 93e78e1.

📒 Files selected for processing (7)

• apps/server/src/vcs/GitVcsDriverCore.test.ts
• apps/server/src/vcs/GitVcsDriverCore.ts
• docs/user/project-settings.md
• packages/contracts/src/t3ProjectFile.test.ts
• packages/contracts/src/t3ProjectFile.ts
• packages/shared/src/t3ProjectFile.test.ts
• packages/shared/src/t3ProjectFile.ts

Included review availability: Your plan provides up to 10 included reviews per hour; 9 remain after this review.

---

📝 Walkthrough

Walkthrough

The project file schema now supports initSubmodulesOnWorktreeCreate. Worktree creation parses this setting and skips recursive submodule initialization when it is false. Tests and user documentation cover the new behavior.

Changes

Worktree submodule initialization

Layer / File(s)	Summary
Project setting contract and parsing packages/contracts/src/t3ProjectFile.ts, packages/contracts/src/t3ProjectFile.test.ts, packages/shared/src/t3ProjectFile.ts, packages/shared/src/t3ProjectFile.test.ts	Adds the optional boolean setting and validates its decoding, schema entry, parser output, and parsing documentation.
Worktree creation behavior apps/server/src/vcs/GitVcsDriverCore.ts, apps/server/src/vcs/GitVcsDriverCore.test.ts, docs/user/project-settings.md	Worktree creation reads t3.json and skips recursive submodule checkout when the setting is false. Tests and documentation describe the behavior.

Priority: ⬇️ Low

Estimated code review effort: 3 (Moderate) | ~20 minutes

Change: Feature

Sequence Diagram(s)

sequenceDiagram
  participant GitVcsDriverCore
  participant parseT3ProjectFile
  participant git
  GitVcsDriverCore->>git: Add worktree
  GitVcsDriverCore->>parseT3ProjectFile: Parse t3.json
  parseT3ProjectFile-->>GitVcsDriverCore: Return submodule initialization setting
  GitVcsDriverCore->>git: Run recursive submodule update when enabled

Loading

Suggested reviewers: juliusmarminge

Merge Risk: ⚪ Minimal · up to 93e78

The new opt-out preserves existing submodule initialization by default and has coverage for both default and disabled behavior. No actionable merge-blocking risk remains.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely describes the main change: allowing t3.json to skip worktree submodule initialization.
Description check	✅ Passed	The description explains the problem, the change, the preserved default behavior, the opt-out behavior, the intended workflow, and the tests. It does not use the template headings or include the check…
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 1 functions across 6 files. (1 skipped: 1 …
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create a new PR

---

_{Comment @coderabbitai help to get the list of available commands.}

[juliusmarminge]

Superseded by #12953 (with #12954 / #12955), which landed worktreeSubmodules (recursive / top-level / none) on main — the same skip-submodule-init goal, with top-level and settings UI on top. Closing as leftover hygiene.