worktree-workflow

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Worktree Workflow

Worktree 工作流

Layer: Practice

Current release-driven profileではWorktrunkをGit worktreeの標準操作frontendとして使用する。WSL2/LinuxまたはLinux hostでWorktrunkが利用可能なら、日常のworktree作成・切替・一覧・review checkout・cleanupは原則

wt

経由で行う。

Worktrunk自体はConstitutionではない。採用理由はworkspace lifecycle / recoverability / process-port ergonomicsであり、native agent workspace等が同等以上のguaranteeを提供する場合はADR-0017のrefinement contractに従って置換できる。

単にagentがnative

git worktree

に慣れていることはdeviation evidenceにならない。native WindowsをこのSkillの必須targetにはしない。

このSkillは主にauthoring workspace lifecycleを扱う。ADR-0020のverification-only executorへworktree作成を機械的に要求しない。Windows native等でproject/tooling constraintによりworktreeが使えない検証は

sandbox-runtime

quality-gate

のverification contractへrouteする。

Layer: Practice

在当前 release-driven profile 中，将 Worktrunk 作为 Git worktree 标准操作的 frontend 使用。如果在 WSL2/Linux 或 Linux host 上可以使用 Worktrunk，原则上日常的 worktree 创建、切换、列出、review checkout 与 cleanup 都通过

wt

完成。

Worktrunk 本身不是 Constitution。采用它的理由在于 workspace lifecycle、recoverability 以及 process-port ergonomics；如果 native Agent workspace 等方案能提供同等或更高的 guarantee，则可依照 ADR-0017 的 refinement contract 替换它。

仅因为 Agent 熟悉 native

git worktree

，不能构成 deviation evidence。native Windows 不属于本 Skill 的必需 target。

本 Skill 主要处理 authoring workspace lifecycle。不要求 ADR-0020 的 verification-only executor 机械地创建 worktree。在 Windows native 等环境中，如果受 project/tooling constraint 所限而无法使用 worktree 进行验证，则应路由至

sandbox-runtime

quality-gate

的 verification contract。

Current practice guarantees

Worktrunkはworkspace lifecycle toolであり、execution isolation boundaryではない。
branch/ref/GitHub Issue/PRがcanonical stateであり、worktree pathやWorktrunk local stateをSoTにしない。
ticket branchはIssue番号のみ、release branchは
```
release-<major>-<minor>-<patch>
```
を維持する。
```
wt merge main
```
等でGitHub PR lifecycle / protected main / explicit release authorization boundaryを迂回しない。ticket PRのautonomous landingもGitHub delivery contract経由で行う。
project-shared Worktrunk hookは
```
.config/wt.toml
```
へcommitする。
worktree path等のmachine preferenceはuser configであり、project truthにしない。
WSLでは高頻度build/watch用worktreeをLinux filesystemへ置き、
```
/mnt/c
```
を標準にしない。

Worktrunk 是 workspace lifecycle 工具，不是 execution isolation boundary。
branch/ref/GitHub Issue/PR 才是 canonical state；不将 worktree path 或 Worktrunk local state 作为 SoT。
ticket branch 仅使用 Issue 编号；release branch 保持
```
release-<major>-<minor>-<patch>
```
格式。
不通过
```
wt merge main
```
等方式绕过 GitHub PR lifecycle、protected main 或 explicit release authorization boundary。ticket PR 的 autonomous landing 也必须通过 GitHub delivery contract 完成。
project-shared Worktrunk hook 提交至
```
.config/wt.toml
```
。
worktree path 等 machine preference 属于 user config，不作为 project truth。
在 WSL 中，用于高频 build/watch 的 worktree 应放在 Linux filesystem 上，不以
```
/mnt/c
```
为标准。

Prerequisites

最初に

wt --version

で利用可否を確認する。未導入ならrepositoryのreproducible toolchainに含められるかを確認し、安全にprovision可能なら導入する。導入不能・非対応・権限不足の場合だけnative

git worktree

へfallbackし、恒常的な制約ならproject documentationへ理由を残す。

Cargoで導入する例:

bash

cargo install worktrunk
wt config shell install

shell integrationは

wt switch

でcurrent shell directoryを切り替えるために必要。

導入後:

bash

wt --version
wt config show

で利用可能性とconfig locationを確認する。

首先使用

wt --version

确认其可用性。如果尚未安装，检查是否可以将其纳入 repository 的 reproducible toolchain；如果能够安全 provision，则进行安装。仅在无法安装、不受支持或权限不足时，才回退到 native

git worktree

；如果这是持续性约束，应在 project documentation 中记录原因。

通过 Cargo 安装的示例：

bash

cargo install worktrunk
wt config shell install

shell integration 对于通过

wt switch

切换当前 shell directory 是必需的。

安装后，通过以下命令确认可用性与 config location：

bash

wt --version
wt config show

Standard operations

現在のrelease branchへ移動:

bash

wt switch release-0-2-0

Issue #123用ticket branch/worktreeを作成:

bash

wt switch --create 123 --base=release-0-2-0

wt switch --create <name>

は

--base

を指定しないとdefault branch（通常

main

）をbaseにするため、release branchやpredecessor branchから派生させたい場合は必ず

--base

を明示する。

current HEADから派生:
```
wt switch --create <name> --base=@
```

指定release branchから派生:

wt switch --create <name> --base=release-x-y-z

stacked ticketでimmediate predecessor branchから派生:

wt switch --create <dependent-issue> --base=<predecessor-issue>

default branchからの派生はtarget release trunkへ直接stackできないticketを作るため、

github-delivery

policy違反になる。作成元はcurrent expected baseでなければならない。stacked ticketではimmediate predecessor snapshot/branchとの関係を

github-delivery

parallel-orchestration

policyに従って決める。

worktree一覧:

bash

wt list
wt list --full

PR review用checkout:

bash

wt switch pr:123

PR checkoutはreview workspaceを分離するための操作であり、review対象SHAとvalidation evidenceは別途pinする。

branchが不要になった後のcleanup:

bash

wt remove <branch>

削除前にPR / release landing state、未commit変更、必要artifactを確認する。

切换到当前 release branch：

bash

wt switch release-0-2-0

为 Issue #123 创建 ticket branch/worktree：

bash

wt switch --create 123 --base=release-0-2-0

如果执行

wt switch --create <name>

时未指定

--base

，则会以 default branch（通常为

main

）作为 base。因此，如果需要从 release branch 或 predecessor branch 派生，必须显式指定

--base

。

从 current HEAD 派生：
```
wt switch --create <name> --base=@
```

从指定 release branch 派生：

wt switch --create <name> --base=release-x-y-z

在 stacked ticket 中从 immediate predecessor branch 派生：
```
wt switch --create <dependent-issue> --base=<predecessor-issue>
```

从 default branch 派生会创建无法直接 stack 到目标 release trunk 的 ticket，因此违反

github-delivery

policy。创建来源必须是 current expected base。对于 stacked ticket，应依照

github-delivery

parallel-orchestration

policy，确定其与 immediate predecessor snapshot/branch 的关系。

列出 worktree：

bash

wt list
wt list --full

用于 PR review 的 checkout：

bash

wt switch pr:123

PR checkout 是隔离 review workspace 的操作；review 对象 SHA 与 validation evidence 需要另行 pin。

branch 不再需要后的 cleanup：

bash

wt remove <branch>

删除前检查 PR / release landing state、uncommitted changes 与必要的 artifacts。

Project configuration

repository-specific hookが必要なら:

bash

wt config create --project

で

.config/wt.toml

を作成し、実際のproject stackへ合わせて編集・commitする。

universalなdev commandを決め打ちしない。initializerはpackage scripts、framework docs/config、existing startup commandを調査して、port override方法を特定する。

Worktrunk専用のdev server例（Orca/plain gitでは展開されない）:

toml

undefined

如果需要 repository-specific hook：

bash

wt config create --project

通过该命令创建

.config/wt.toml

，再根据实际 project stack 对其进行编辑并 commit。

不要预先确定 universal dev command。initializer 应调查 package scripts、framework docs/config 与 existing startup command，以确定 port override 方法。

Worktrunk 专属 dev server 示例（Orca/plain git 下不会展开）：

toml

undefined

.config/wt.toml

[post-start] server = "wt step tether -- <project-specific command using {{ branch | hash_port }}>"

[list] url = "http://localhost:{{ branch | hash_port }}"


例のplaceholderをそのままcommitしてはいけない。Vite / Next.js / backend CLI / env-based server等、実際のcommand semanticsへ変換する。

[post-start] server = "wt step tether -- <project-specific command using {{ branch | hash_port }}>"

[list] url = "http://localhost:{{ branch | hash_port }}"


不得直接将示例中的 placeholder commit。应根据实际 command semantics，将其转换为适用于 Vite / Next.js / backend CLI / env-based server 等环境的命令。

Frontend independence

worktreeを作るfrontendはWorktrunk以外（Orca、plain git等）も使われる。frontendごとにsetupが違うと、同じbranchでも作り方によって状態がずれる。そのため、作成・削除時の処理はfrontendに書かず、repository-controlledな入口（例：

mise run worktree:setup

mise run worktree:teardown

）に置く。frontendはその入口を呼ぶだけにする。

toml

undefined

创建 worktree 的 frontend 除 Worktrunk 外也会使用（Orca、plain git 等）。如果各 frontend 的 setup 不同，即使 branch 相同，状态也会因创建方式不同而出现偏差。因此，创建和删除时的处理不应写在 frontend 中，而应放在 repository-controlled 的入口（例如：

mise run worktree:setup

mise run worktree:teardown

）。frontend 只负责调用该入口。

toml

undefined

.config/wt.toml

[pre-start] setup = "mise run worktree:setup"

[pre-remove] teardown = "mise run worktree:teardown"


- portなどworktreeごとの値は、frontendのtemplate（`hash_port` 等）ではなく入口の中でbranch名から決める。
- 入口は何度実行しても同じ状態になるようにする。どのfrontendから、何回呼ばれても壊れないためである。
- `.worktreeinclude` はliteralなpathだけで書く。globはOrcaが無視する。
- 全frontendで使える入口がなければ、plain gitで作ったworktreeで手動実行できる形にする。

参照実装はproject-initの `scripts/worktree/`、`mise.toml`、`.config/wt.toml`、`orca.yaml` にある。projectへ写してから、project固有のsetupを入口に足す。Orcaを併用する手順は `orca-frontend` Skillを参照する。

[pre-start] setup = "mise run worktree:setup"

[pre-remove] teardown = "mise run worktree:teardown"


- port 等 worktree 专属值应由入口根据 branch 名决定，而不是使用 frontend 的 template（如 `hash_port`）。
- 无论执行多少次，入口都应产生相同状态，从而确保它不会因 frontend 或调用次数不同而发生故障。
- `.worktreeinclude` 只能写 literal path。Orca 会忽略 glob。
- 如果不存在可供所有 frontend 使用的入口，应确保通过 plain git 创建的 worktree 也能手动执行。

参考实现位于 project-init 的 `scripts/worktree/`、`mise.toml`、`.config/wt.toml`、`orca.yaml`。复制到 project 后，再将 project-specific setup 加入入口。并用 Orca 的步骤请参阅 `orca-frontend` Skill。

Rust / Cargo build output and cache

Rust/Cargo projectでは、

target/

肥大化をworktree lifecycle上の明示的なresource concernとして扱う。ただし容量削減のためにcorrectness-sensitiveなmutable build outputを共有してはいけない。詳細なdecisionはADR-0024に従う。

在 Rust/Cargo project 中，应将

target/

膨胀视为 worktree lifecycle 中明确的 resource concern。不过，不能为了减少容量而共享对 correctness 敏感的 mutable build output。详细 decision 遵循 ADR-0024。

Default boundary

concurrentにbuildされ得るworktree間では次を共有しない。

```
target-dir
```
/
```
CARGO_TARGET_DIR
```
Cargo
```
build.build-dir
```
incremental compilation state
```
target/
```
へのsymlinkや同一external build directory

Cargoのtarget directory lockingはparallel buildを直列化し得るうえ、divergent Git worktreeが同じbuild directoryを共有した場合のfingerprint/artifact correctness issueがcurrent Cargoで報告されている。したがって「全worktreeを1個のtargetへ向ける」を標準optimizationにしない。

Cargo 1.91+の

build.build-dir

をexternal locationへ移す場合も、workspace pathごとに一意なdirectoryを使い、そのdirectoryのcleanup ownershipを定義する。異なるmutable worktreeへ同じbuild directoryを割り当てない。

共有候補は次に限定する。

Cargo registry / git dependency download cache
read-only toolchain cache
bounded compiler cache such as
```
sccache
```

sccache

を採用する場合は

build.rustc-wrapper

または

RUSTC_WRAPPER

で接続する。ただし2026-09-27時点のsccache v0.17.0では、Rust hash keyへ

SCCACHE_BASEDIRS

basedirs

を適用するissue #2652が未解決である。Rustのparallel checkout / Git worktreeで

basedirs

だけによりcross-worktree hitが成立すると仮定しない。

--remap-path-prefix

はcompiler outputへ埋め込まれるpathを安定化できるが、cache-key normalizationの代替ではない。cross-worktree Rust reuseを有効化する場合は、使用するsccache version / rustc-Cargo configuration / path flagsを記録し、複数worktree間のhit/missを実測する。未検証ならfuture-facing optimizationとして扱う。absolute machine pathはproject truthにせずuser/runtime configへ置き、local cache sizeはhost capacityに応じてboundedにする。local storageを使う場合、同じ

SCCACHE_DIR

へ複数の独立sccache serverを競合させず、同一hostでは単一serverを共有するかserverごとにstorageを分離する。repository-required toolとして採用する場合は既存mise policyに従ってversion/provisioningを再現可能にする。

对于可能被 concurrent build 的 worktree 之间，不共享以下内容：

```
target-dir
```
/
```
CARGO_TARGET_DIR
```
Cargo
```
build.build-dir
```
incremental compilation state
指向
```
target/
```
的 symlink 或同一个 external build directory

Cargo 的 target directory locking 可能将 parallel build 串行化；此外，current Cargo 已报告 divergent Git worktree 共享同一 build directory 时的 fingerprint/artifact correctness issue。因此，不将“让所有 worktree 指向同一个 target”作为标准优化。

即使将 Cargo 1.91+ 的

build.build-dir

移到 external location，也必须为每个 workspace path 使用唯一 directory，并定义该 directory 的 cleanup ownership。不得为不同 mutable worktree 分配同一个 build directory。

共享候选仅限以下内容：

Cargo registry / git dependency download cache
read-only toolchain cache
bounded compiler cache such as
```
sccache
```

采用

sccache

时，应通过

build.rustc-wrapper

或

RUSTC_WRAPPER

连接。不过，截至 2026-09-27 的 sccache v0.17.0 中，将

SCCACHE_BASEDIRS

basedirs

应用于 Rust hash key 的 issue #2652 尚未解决。在 Rust parallel checkout / Git worktree 中，不要仅凭

basedirs

就假设能够实现 cross-worktree hit。

--remap-path-prefix

可以稳定嵌入 compiler output 的 path，但不能替代 cache-key normalization。如果要启用 cross-worktree Rust reuse，应记录所使用的 sccache version / rustc-Cargo configuration / path flags，并实测多个 worktree 之间的 hit/miss。如果尚未验证，则应将其视为面向未来的优化。

absolute machine path 不应成为 project truth，而应放入 user/runtime config；local cache size 则应根据 host capacity 保持 bounded。使用 local storage 时，不要让多个独立 sccache server 争用同一个

SCCACHE_DIR

；在同一 host 上，应共享单一 server，或按 server 分离 storage。如果将其作为 repository-required tool 采用，则应依照现有 mise policy，使 version/provisioning 可复现。

Worktree bootstrap

Rust

target/

をsymlinkしたり、単一directoryとして共有してはいけない。一方、Worktrunkの

wt step copy-ignored

がfilesystemのreflinkを使える場合は、

--require-include

を必須とし、repository-controlled

.worktreeinclude

で承認済みseed pathだけをallowlistした場合に限り、各worktreeに独立pathを保ったcopy-on-write seedとして利用してよい。Rust target seedでは

target/

を基本allowlistとし、

.env

、credential、token、socket、DB、その他mutable runtime stateを含めない。

WorktrunkはAPFS / btrfs / XFS / ReFS等ではreflinkを使用できる。reflink対応が実測で確認できたhostでは、compatibleなbase worktreeから

target/

をseedすることでinitial disk増加を抑えつつcold startを短縮できる。

ext4 / NTFS等ではfull copyになるため巨大な

target/

をコピーしない。Worktrunkのsummaryでreflink利用を確認できないhostではproject config等で:

toml

[step.copy-ignored]
exclude = ["target/"]

を標準候補とする。

wt step copy-ignored

は

--require-include

なしで実行せず、

.worktreeinclude

はrepository-controlled allowlistとしてreviewする。

target/

を含めるのもreflink capabilityを確認したhost/projectだけにする。

CoW seedはmutable-directory sharingではないが、seed artifact自体をvalidation evidenceにしない。新worktreeでは通常どおりCargoのfingerprint/rebuildとrequired validationを実行する。

Rust

target/

不得通过 symlink 连接，也不得作为单一 directory 共享。另一方面，如果 Worktrunk 的

wt step copy-ignored

能够使用 filesystem reflink，则必须带

--require-include

，并且仅在 repository-controlled 的

.worktreeinclude

将已批准的 seed path 加入 allowlist 后，才可用它为各 worktree 建立保持独立 path 的 copy-on-write seed。Rust target seed 以

target/

为基本 allowlist，且不得包含

.env

、credential、token、socket、DB 或其他 mutable runtime state。

Worktrunk 可以在 APFS / btrfs / XFS / ReFS 等文件系统上使用 reflink。在实测确认 host 支持 reflink 时，可以从 compatible base worktree 以

target/

作为 seed，从而减少初始磁盘增量并缩短 cold start 时间。

ext4 / NTFS 等文件系统会执行 full copy，因此不要复制庞大的

target/

。如果无法从 Worktrunk summary 确认 reflink 使用情况，应在 project config 等位置采用以下配置作为标准候选：

toml

[step.copy-ignored]
exclude = ["target/"]

不得在没有

--require-include

的情况下运行

wt step copy-ignored

，并且应将

.worktreeinclude

作为 repository-controlled allowlist 进行 review。只有在已确认 reflink capability 的 host/project 中，才能包含

target/

。

CoW seed 并非 mutable-directory sharing，但 seed artifact 本身也不能作为 validation evidence。在新 worktree 中，仍应照常执行 Cargo fingerprint/rebuild 与 required validation。

Incremental compilation

incremental compilationは一律に無効化しない。

long-lived interactive checkout: Cargo dev defaultのincremental buildを標準候補とする
short-lived / disposable agent worktree: reuse期間が短くdisk amplificationが大きい場合、
```
CARGO_INCREMENTAL=0
```
を優先候補とする
project-wide
```
[profile.dev] incremental = false
```
はclean build / representative rebuild / disk footprintを比較してから採用する

sccacheはincrementally compiled Rust crateをcacheできない。short-lived agent worktreeでcross-worktree sccache reuseを狙う場合は

CARGO_INCREMENTAL=0

を明示することを標準候補とする。long-lived interactive checkoutではedit/rebuild latencyとの比較で決め、「incrementalを保持すること」自体を目的化しない。

不应一律禁用 incremental compilation。

long-lived interactive checkout：将 Cargo dev 默认的 incremental build 作为标准候选
short-lived / disposable Agent worktree：当 reuse 时间较短且 disk amplification 较大时，优先考虑
```
CARGO_INCREMENTAL=0
```
project-wide
```
[profile.dev] incremental = false
```
：先比较 clean build / representative rebuild / disk footprint 后再采用

sccache 无法缓存 incrementally compiled Rust crate。若目标是在 short-lived Agent worktree 中实现 cross-worktree sccache reuse，应将显式设置

CARGO_INCREMENTAL=0

作为标准候选。对于 long-lived interactive checkout，则应通过比较 edit/rebuild latency 来决定，并且不应把“保留 incremental”本身当作目的。

Reclamation

cargo clean

をroutine build/test stepへ入れない。disk pressureやstale artifact recoveryでは狭いcleanupを先に選ぶ。

bash

cargo clean --dry-run -v
cargo clean --doc
cargo clean --release
cargo clean --profile <name>
cargo clean --target <triple>
cargo clean -p <package>

full

cargo clean

はcache corruption、toolchain/profile regime change、active worktreeの強いdisk pressure、externalized per-worktree build directoryのretirement等、rebuild costよりreclamation benefitが大きい場合に限定する。

通常のworktree-local

target/

はworktree directoryと一緒に削除されるため、

wt remove

直前にfull cleanを二重実行しない。external build directoryを採用したprojectだけは、worktree removal時にそのworktree固有directoryを安全にreclaimするhook/taskを用意する。

Cargo global cache auto-GCはregistry/git等のglobal cache用であり、current Cargoのtarget build artifact lifecycleの代替として扱わない。

不要把

cargo clean

放入 routine build/test step。在 disk pressure 或 stale artifact recovery 场景下，优先选择范围更窄的 cleanup。

bash

cargo clean --dry-run -v
cargo clean --doc
cargo clean --release
cargo clean --profile <name>
cargo clean --target <triple>
cargo clean -p <package>

仅在 cache corruption、toolchain/profile regime change、active worktree 承受强 disk pressure，或 externalized per-worktree build directory 需要退役等情况下，且 reclamation benefit 大于 rebuild cost 时，才执行 full

cargo clean

。

普通 worktree-local

target/

会随 worktree directory 一起删除，因此不要在

wt remove

前紧接着重复执行 full clean。仅采用 external build directory 的 project，应准备在移除 worktree 时安全回收该 worktree 专属 directory 的 hook/task。

Cargo global cache auto-GC 用于 registry/git 等 global cache，不应视为 current Cargo target build artifact lifecycle 的替代方案。

Reduce what gets built

target footprintが継続的に問題になるprojectでは、cleanupだけでなくartifact production自体を調べる。

```
cargo tree -e features
```
で実際に有効なfeatureとenable元を調べる
```
cargo tree -d
```
でduplicate dependency versionを調べる
```
cargo build --timings
```
で高cost compile unitを調べる
virtual workspaceを含めappropriate Cargo resolverを確認する
unused default featuresがproject evidenceで確認できたdirect dependencyだけ
```
default-features = false
```
+ explicit featuresを検討する
project MSRVがstring debug levelをsupportし、通常開発でfull debugger variable informationを必要としないなら、Cargo公式build-performance guidanceの次のshapeを優先候補として計測する

toml

[profile.dev]
debug = "line-tables-only"

[profile.dev.package."*"]
debug = false

[profile.debugging]
inherits = "dev"
debug = true

通常devではworkspace memberをbacktraceに必要なline infoへ抑え、dependency debug infoを生成しない。full debugger sessionは

--profile debugging

へopt-inする。

dependency default featureやlibrary feature surfaceはpublic behaviorへ影響し得るため、disk optimizationだけを理由に一括変更しない。

recursive cleaner等のthird-party toolはhost convenienceとして使ってよいが、project correctnessの必須依存にしない。unmaintained toolをcurrent defaultへ固定しない。

如果 target footprint 持续成为问题，不仅要 cleanup，还应检查 artifact production 本身。

使用
```
cargo tree -e features
```
检查实际启用的 feature 及其启用来源
使用
```
cargo tree -d
```
检查重复的 dependency version
使用
```
cargo build --timings
```
检查编译成本较高的 compile unit
确认适合当前项目的 Cargo resolver，包括 virtual workspace
仅对 project evidence 确认未使用的 direct dependency，考虑使用
```
default-features = false
```
+ explicit features
如果 project MSRV 支持 string debug level，且通常开发不需要完整的 debugger variable information，应优先采用并测量 Cargo 官方 build-performance guidance 中的以下配置形态：

toml

[profile.dev]
debug = "line-tables-only"

[profile.dev.package."*"]
debug = false

[profile.debugging]
inherits = "dev"
debug = true

在普通 dev 中，将 workspace member 限制为 backtrace 所需的 line information，并不生成 dependency debug information。完整 debugger session 则通过

--profile debugging

opt in。

dependency default feature 与 library feature surface 可能影响 public behavior，因此不要仅以 disk optimization 为由批量修改。

recursive cleaner 等 third-party tool 可以作为 host convenience 使用，但不得成为 project correctness 的必需依赖。不要把 unmaintained tool 固定为 current default。

Port allocation

Worktrunk専用の

{{ branch | hash_port }}

はbranch名からportを決める。Orca/plain gitと併用する場合は使わず、共通setup入口でportを決める。

ただしhash-based allocationは絶対的なuniqueness guaranteeではない。dev server / runtimeはbind failureを明示的に検出し、必要ならproject-specificなport reservationまたはcollision-resolutionを追加する。既に別processが占有しているportを「自分のbranch用」と仮定して継続してはいけない。

適用境界:

hostへ直接bindするprocess: dev commandのportへ適用
container/sandbox: host-published portへ適用し、container内部portは通常固定でよい
preview URL: 同じport templateから構築できる
DB等の別service: 別namespaceを使う。Worktrunk専用なら
```
('db-' ~ branch) | hash_port
```
、複数frontendなら共通入口で決める

portが一意でもprocess/database/filesystem/credential isolationが成立したとは扱わない。

Worktrunk 专属的

{{ branch | hash_port }}

根据 branch 名决定 port。与 Orca/plain git 配合使用时不要使用它，而应由公共 setup 入口决定 port。

不过，hash-based allocation 并不提供绝对 uniqueness guarantee。dev server / runtime 必须明确检测 bind failure，必要时增加 project-specific 的 port reservation 或 collision resolution。某个 port 已被其他 process 占用时，不得继续假定它是“当前 branch 专用”的。

适用边界：

直接 bind 到 host 的 process：将规则应用于 dev command 的 port
container/sandbox：应用于 host-published port；container 内部 port 通常可以固定
preview URL：可基于同一个 port template 构建
DB 等其他 service：使用独立 namespace。如果仅限 Worktrunk，可使用
```
('db-' ~ branch) | hash_port
```
；如果存在多个 frontend，则由公共入口决定

即使 port 唯一，也不表示 process/database/filesystem/credential isolation 已成立。

Process lifecycle

long-running dev server/watch processをWorktrunk hookから起動する場合は、適切なら:

bash

wt step tether -- <command>

を使用する。

tethered processはworktree lifecycleへ結び付け、worktree removal後のorphan processやstale port ownershipを減らす。

これはprocess cleanup mechanismであり、sandbox security boundaryではない。

如果从 Worktrunk hook 启动 long-running dev server/watch process，适宜时应使用：

bash

wt step tether -- <command>

tethered process 与 worktree lifecycle 绑定，从而减少 worktree removal 后的 orphan process 和 stale port ownership。

这只是 process cleanup mechanism，不是 sandbox security boundary。

Mutable services and state

同一hostへ複数worktreeをmaterializeする場合、次を共有しない設計にする:

writable DB/schema
Redis namespace / queue
container name
Unix socket
app-local mutable state
generated runtime state
credentials with broader authority than the worker requires

Worktrunkの

sanitize_db

hash_port

等はdeterministic identifierとして利用できるが、実際のservice isolationは

sandbox-runtime

policyに従う。

如果在同一 host 上 materialize 多个 worktree，应采用不共享以下内容的设计：

writable DB/schema
Redis namespace / queue
container name
Unix socket
app-local mutable state
generated runtime state
authority 大于 worker 所需范围的 credentials

Worktrunk 的

sanitize_db

hash_port

等可以作为 deterministic identifier 使用，但实际 service isolation 仍遵循

sandbox-runtime

policy。

Delivery boundary

Worktrunk commandはGitHub deliveryのergonomic frontendに限定する。

許可される典型操作:

text

wt switch release-x-y-z
-> wt switch --create <issue-number> --base=release-x-y-z
-> implementation / commit / publish
-> immediate PR creation/state
-> review / validation
-> ticket-class: autonomous GitHub landing / release-class: explicitly authorized GitHub landing
-> wt remove <issue-number>

wt merge

のlocal integration convenienceは、project-initのticket PR lifecycle / release PR / protected main / explicit release authorization boundaryを置き換えない。

Worktrunk command 仅作为 GitHub delivery 的 ergonomic frontend。

允许的典型操作：

text

wt switch release-x-y-z
-> wt switch --create <issue-number> --base=release-x-y-z
-> implementation / commit / publish
-> immediate PR creation/state
-> review / validation
-> ticket-class: autonomous GitHub landing / release-class: explicitly authorized GitHub landing
-> wt remove <issue-number>

wt merge

提供的 local integration convenience，不会取代 project-init 中的 ticket PR lifecycle / release PR / protected main / explicit release authorization boundary。

Fallback and recovery

Authoring

Worktrunkが利用できないmutable authoring workerではnative

git worktree

へ縮退してよい。ただしbranch naming、mutable ownership、runtime state safety、PR state lifecycle等のapplicable semanticsは維持する。

worktree自体を作れないauthoring environmentでは、同じshared checkoutへ複数workerを並行配置しない。isolated clone / sandbox / serialized ownership等、同等以上のmutable ownership guaranteeを選ぶ。

在无法使用 Worktrunk 的 mutable authoring worker 中，可以退化到 native

git worktree

。但仍须维持 branch naming、mutable ownership、runtime state safety、PR state lifecycle 等适用语义。

如果 authoring environment 本身无法创建 worktree，则不要把多个 worker 并行放置到同一个 shared checkout 中。应选择 isolated clone / sandbox / serialized ownership 等具备同等或更高 mutable ownership guarantee 的方案。

Verification-only

verification-only executionはworktree fallback chainの対象ではない。immutable candidate artifactをcleanにmaterializeできれば、package / installed build / clean checkout / disposable clone / serialized singleton checkout等を利用できる。

singleton checkoutを使う場合はdirty stateを暗黙に上書きせず、exclusive ownershipとbefore/after state auditを行う。validation中にsource authoringへ移行した場合はmutable worker policyへpromotionする。

fresh environmentではGit refs、Issue/PR metadata、committed

.config/wt.toml

、project docsからworkflowを再構成できなければならない。user-level Worktrunk configだけに必要情報を残さない。

verification-only execution 不属于 worktree fallback chain 的适用范围。只要能够干净地 materialize immutable candidate artifact，就可以使用 package / installed build / clean checkout / disposable clone / serialized singleton checkout 等方式。

使用 singleton checkout 时，不得隐式覆盖 dirty state，并须执行 exclusive ownership 与 before/after state audit。如果在 validation 期间转入 source authoring，则应提升为 mutable worker policy。

在 fresh environment 中，必须能够根据 Git refs、Issue/PR metadata、已 commit 的

.config/wt.toml

和 project docs 重建 workflow。不得把必要信息仅留在 user-level Worktrunk config 中。

Refinement / deviation

Worktrunkから外れる場合は、少なくとも次を確認する。

canonical task/source identityがlocal pathに依存しない
concurrent workspaceのmutable-state safetyを悪化させない
current expected baseからmaterializeできる
review/recoveryがtool-local hidden stateだけに依存しない
dev process / port / mutable service lifecycleについて必要なguaranteeを維持する

同等以上ならalternativeを許容する。Worktrunk command shapeそのものをorganizational correctnessとして扱わない。

如果脱离 Worktrunk，至少检查以下事项：

canonical task/source identity 不依赖 local path
不降低 concurrent workspace 的 mutable-state safety
能够从 current expected base materialize
review/recovery 不只依赖 tool-local hidden state
对 dev process / port / mutable service lifecycle 维持必要的 guarantee

如果 alternative 能提供同等或更高保证，则允许采用。不要把 Worktrunk command 的具体形式本身视为 organizational correctness。

Remove / re-evaluate

agent/runtimeがnativeに同等以上のworkspace lifecycleを提供する
Worktrunk固有hookがproject stackと不整合になる
host worktreeを使わないruntime modelへ移行する
comparative evalでWorktrunk-specific instructionの追加価値が消える

Agent/runtime 原生提供同等或更高 workspace lifecycle
Worktrunk 专属 hook 与 project stack 不一致
迁移到不使用 host worktree 的 runtime model
comparative eval 表明 Worktrunk-specific instruction 不再带来额外价值