Back to Details

orcakit

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

orcakit

orcakit

Orca shows one workspace per git worktree, with a card carrying the linked issue, a status, and any terminals running in it. Worktrees themselves come from plain 
git worktree
— gitkit's convention, issuekit's 
start
, or your own hands — and Orca discovers them on its own.
What nothing owns is the drift between the two. A worktree named 
issue-42-add-sso-login
sits in the sidebar with no issue attached, so its card says nothing. An issue closes and its PR merges, but the workspace stays forever, and three weeks later the sidebar is mostly finished work. orcakit owns exactly that reconciliation: Orca's view of your worktrees, made to match the tracker.
Orca 会为每个git工作树显示一个工作区，对应的卡片上会展示关联的issue、状态以及在其中运行的终端。工作树本身来自原生的
git worktree
命令——可能是遵循gitkit的约定、通过issuekit的
start
命令创建，或是您手动创建的——Orca会自动发现这些工作树。
但有一个问题无人处理：两者之间的差异漂移。名为
issue-42-add-sso-login
的工作树在侧边栏中没有关联任何issue，因此它的卡片上没有任何信息。某个issue已关闭且对应的PR已合并，但工作区仍保留在列表中，三周后侧栏里几乎全是已完成的工作。orcakit正是负责解决这种不一致：让Orca对工作树的展示与跟踪系统保持一致。

The line orcakit does not cross

orcakit的边界

Git is the source of truth for a worktree. orcakit never runs 
orca worktree create
to do real work and never invents a path — creating a worktree is native 
git worktree
under gitkit's convention, so a headless Linux box with no Orca on it runs identical commands. orcakit works one layer up, on things Orca alone knows:
  • metadata — the linked issue, the workspace status, the comment, the display name;
  • Orca-side resources git can't express — live terminals bound to a workspace, and a repo's archive/setup hooks.
Removing a worktree with git is enough: Orca notices within seconds and drops the entry by itself. The single exception is a workspace Orca created — see Mode: 
clean
, which documents why and confines it there.
orcakit never touches the tracker. It reads issues and PRs to judge state; it never closes an issue, moves a label, or edits a PR. When it finds a merged PR whose issue is still open, that's tracker drift and it says so, routing to issuekit 
close
rather than reaching around it.
Git是工作树的唯一可信源。orcakit绝不会执行
orca worktree create
来创建实际工作树，也不会凭空生成路径——创建工作树是遵循gitkit约定的原生
git worktree
操作，因此即使是没有安装Orca的无头Linux服务器，也能运行完全相同的命令。orcakit在更高一层工作，仅处理Orca独有的内容：
  • 元数据——关联的issue、工作区状态、备注、显示名称；
  • Git无法表达的Orca端资源——绑定到工作区的活跃终端，以及仓库的归档/设置钩子。
使用Git移除工作树就足够了：Orca会在几秒内检测到并自动删除对应的条目。唯一的例外是Orca创建的工作区——详情见模式：
clean
，其中说明了原因并限定了操作范围。
orcakit绝不会修改跟踪系统。它仅读取issue和PR的状态来判断工作区状态；绝不会关闭issue、移动标签或编辑PR。当它发现PR已合并但issue仍处于打开状态时，这属于跟踪系统的漂移问题，会提示用户使用issuekit的
close
命令来处理，而非直接干预。

When this fires

触发场景

  • list
     — "what's in my Orca workspaces", "which workspaces are stale", "show me my orca sidebar as a table". Read-only.
  • link
     — "link my worktrees to their issues", "my workspace cards are blank", "Orca doesn't know what #42's workspace is for".
  • clean
     — "clean up my orca workspaces", "remove the workspaces whose issues merged", "my sidebar is full of finished work".
  • align
     — "where should Orca put new worktrees", "make Orca use my worktree root", "stop Orca creating worktrees in its own folder".
If no mode is clear, ask. 
list
is free and 
clean
deletes directories; never guess between them.
Not this skill: creating a worktree (gitkit), closing an issue or tearing down after a merge (issuekit 
close
), driving Orca terminals, browser, or agents (that's the 
orca
CLI directly, or an Orca-provided skill if one is installed). orcakit is workspace hygiene, not workspace operation.
  • list
    ——“我的Orca工作区里有什么”、“哪些工作区已失效”、“以表格形式展示我的Orca侧边栏”。只读模式。
  • link
    ——“将我的工作树关联到对应的issue”、“我的工作区卡片是空的”、“Orca不知道#42工作区是做什么的”。
  • clean
    ——“清理我的Orca工作区”、“移除已合并issue对应的工作区”、“我的侧边栏全是已完成的工作”。
  • align
    ——“Orca应该把新工作树放在哪里”、“让Orca使用我的工作树根目录”、“别让Orca在自己的文件夹里创建工作树”。
如果无法明确模式，请询问用户。
list
是无风险操作，而
clean
会删除目录；切勿自行猜测。
不属于本工具的场景：创建工作树（gitkit负责）、关闭issue或在合并后清理（issuekit的
close
命令）、操作Orca终端、浏览器或代理（直接使用
orca
CLI，或已安装的Orca提供的技能）。orcakit负责的是工作区维护，而非工作区操作。

Preflight (every mode)

预检查（所有模式通用）

sh
orca status --json      # app running? runtime reachable?
  • orca
    not installed     → this machine has no Orca, so there is nothing to reconcile. Say exactly that and stop. Do not fall back to anything: worktrees are already fine without Orca, and nothing else in the workflow depends on this skill.
  • Runtime not reachable → 
    orca open
    starts the app and waits. Ask before launching a desktop app on someone's machine.
  • gh
    missing or unauthenticated     → 
    list
    still works but every verdict degrades to "unknown tracker state", and 
    clean
    cannot run at all, because its whole safety rests on knowing a PR merged. Say which and stop rather than guessing.
  • A rejected 
    orca
    flag or selector     → the CLI moves fast; check 
    orca <command> --help
    before concluding the operation is unsupported. The goal (the link, the status, the removal) is the contract — the exact flag spelling isn't.
Orca must also be configured to surface externally-created worktrees, or it won't see anything gitkit made:
sh
orca repo list --json    # each repo carries externalWorktreeVisibility
If a repo reads 
"externalWorktreeVisibility": "hide"
, its gitkit worktrees are invisible to every mode here. There is no CLI flag for this — it's a per-repo setting in the Orca UI. Report the repo by name and let the user flip it; don't pretend the empty result is an empty worktree root.
sh
orca status --json      # 应用是否在运行？运行时是否可达？
  • 未安装
    orca
    → 本机没有Orca，无需进行一致性处理。直接告知用户并终止操作。不要回退到其他操作：没有Orca时工作树本身已经正常，工作流中的其他环节也不依赖本工具。
  • 运行时不可达→ 使用
    orca open
    启动应用并等待。在用户的机器上启动桌面应用前请先询问。
  • 缺少
    gh
    或未认证    → 
    list
    仍可运行，但所有判断都会降级为“跟踪系统状态未知”，且
    clean
    完全无法运行，因为它的安全性完全依赖于确认PR已合并。告知用户具体情况并终止操作，切勿猜测。
  • orca
    的参数或选择器被拒绝    → CLI更新较快；在判定操作不支持前，请先查看
    orca <command> --help
    。目标（关联、状态更新、移除）是核心要求——具体参数的拼写并非关键。
还需确保Orca已配置为显示外部创建的工作树，否则它无法识别gitkit创建的工作树：
sh
orca repo list --json    # 每个仓库都包含externalWorktreeVisibility配置
如果某个仓库的配置为
"externalWorktreeVisibility": "hide"
，那么它的gitkit工作树对所有模式都不可见。此配置没有CLI参数——它是Orca UI中的每个仓库单独设置的。告知用户对应的仓库名称，让用户手动修改；不要将空结果当作空工作树根目录。

What Orca knows about a workspace

Orca对工作区的认知

sh
orca worktree list --json
orca worktree show --worktree "branch:$BRANCH" --json
Each record carries 
path
, 
branch
, 
linkedIssue
, 
linkedPR
, 
workspaceStatus
, 
isArchived
, 
isMainWorktree
, and 
lastActivityAt
. Selectors are 
branch:<name>
, 
path:<abs-path>
, 
issue:<number>
, and 
active
/
current
— prefer 
branch:
, for the same reason gitkit looks worktrees up by branch: a path is a guess, a branch is an identity.
Discovery is eventually consistent. A worktree created seconds ago may resolve via 
worktree show
before it appears in 
worktree list
; a removed one lingers briefly. Re-read rather than concluding from one stale listing.
sh
orca worktree list --json
orca worktree show --worktree "branch:$BRANCH" --json
每条记录包含
path
、
branch
、
linkedIssue
、
linkedPR
、
workspaceStatus
、
isArchived
、
isMainWorktree
和
lastActivityAt
。选择器包括
branch:<name>
、
path:<abs-path>
、
issue:<number>
以及
active
/
current
——优先使用
branch:
，原因与gitkit通过分支查找工作树相同：路径是猜测，分支是身份标识。
发现机制是最终一致性的。几秒前创建的工作树可能先通过
worktree show
找到，之后才出现在
worktree list
中；已移除的工作树也会短暂保留。请重新读取结果，不要仅凭一次过时的列表就下结论。

Two kinds of workspace

两类工作区

Everything below turns on this distinction:
kindwhere it liveswho created ithow it goes away
git-nativeunder 
$WORKTREE_ROOT
(default 
~/worktrees/<repo>/<branch>
)		gitkit / issuekit 
start
/ a human, with 
git worktree add
git removes it; Orca drops the entry on its own
Orca-nativeunder Orca's worktree base path (default 
~/orca/workspaces/<repo>/<name>
)
orca worktree create
orca worktree rm
, so hooks and terminals are handled
Classify by path prefix. That's a heuristic, not a fact Orca records — so it is a reason to confirm before deleting, never a thing to act on silently. 
align
 exists to collapse the two locations into one and retire the guesswork.
以下所有操作都基于此区分：
类型存储位置创建者移除方式
Git原生
$WORKTREE_ROOT
下（默认
~/worktrees/<repo>/<branch>
）		gitkit / issuekit 
start
命令 / 手动使用
git worktree add
Git移除；Orca会自动删除对应的条目
Orca原生Orca的工作树基础路径下（默认
~/orca/workspaces/<repo>/<name>
）
orca worktree create
命令
orca worktree rm
，会处理钩子和终端
通过路径前缀进行分类。这是一种启发式判断，并非Orca记录的事实——因此这是删除前确认的理由，而非静默操作的依据。
align
模式的作用是将两个位置合并为一个，消除这种猜测。

Mode: 
list

模式：
list

Read-only. Changes nothing, asks nothing, and is the right first move whenever the state is unclear.
Take every workspace where 
isMainWorktree
is false, and join it against the tracker:
sh
orca worktree list --json
gh pr list --head "$BRANCH" --state all --json number,state,url,mergedAt
gh issue view "$N" --json number,state,title,labels     # $N parsed from an issue-<n>-<slug> branch
git -C "$WT" status --porcelain                          # dirty?
git -C "$WT" log --oneline "@{upstream}..HEAD"           # unpushed?
Render one table — workspace, branch, issue, PR, Orca status, git state — and give each row a verdict:
verdictmeansfix
active
open issue or open PR, work in flightnothing
unlinked
branch names an issue, 
linkedIssue
is null
link
stale status
Orca says 
in-progress
, the PR is merged or in review
link
reapable
PR merged, issue closed, tree clean
clean
tracker drift
PR merged, issue still openissuekit 
close <n>
— not orcakit's to fix
dirty
uncommitted or unpushed work, whatever the tracker saysa human, before anything else
unknown
no issue in the branch name and no PRleave it; say so
Close by naming which mode clears which rows, and put 
dirty
first if any exist — that's the row where work gets lost.
只读模式。不修改任何内容，不询问任何问题，当状态不明确时，这是正确的第一步操作。
获取所有
isMainWorktree
为false的工作区，并与跟踪系统关联：
sh
orca worktree list --json
gh pr list --head "$BRANCH" --state all --json number,state,url,mergedAt
gh issue view "$N" --json number,state,title,labels     # $N从issue-<n>-<slug>分支中解析
git -C "$WT" status --porcelain                          # 是否有未提交内容？
git -C "$WT" log --oneline "@{upstream}..HEAD"           # 是否有未推送提交？
生成一个表格——包含工作区、分支、issue、PR、Orca状态、Git状态——并为每一行给出判定：
判定结果含义修复方式
active
issue或PR处于打开状态，工作正在进行无需操作
unlinked
分支名称包含issue编号，但
linkedIssue
为空
link
stale status
Orca显示为
in-progress
，但PR已合并或处于审核中
link
reapable
PR已合并，issue已关闭，工作树干净
clean
tracker drift
PR已合并，但issue仍打开使用issuekit的
close <n>
命令——不属于orcakit的处理范围
dirty
存在未提交或未推送的工作，无论跟踪系统状态如何由用户手动处理，优先于其他操作
unknown
分支名称不包含issue编号，也没有对应的PR保留，告知用户即可
最后说明哪些模式可以清理哪些行，如果存在
dirty
行则优先列出——这是可能导致工作丢失的行。

Mode: 
link

模式：
link

Attach the metadata Orca cannot infer, so a workspace card actually says what it's for.
For each git-native workspace whose branch matches 
issue-<n>-<slug>
and whose 
linkedIssue
is null:
sh
orca worktree set --worktree "branch:$BRANCH" --issue "$N" --json
And bring 
workspaceStatus
in line with the tracker. Orca's vocabulary is 
todo
, 
in-progress
, 
in-review
, 
done
, 
archived
; map it from the real state, not from the label alone:
tracker state
workspaceStatus
issue open, no PR, no commits on the branch
todo
issue open, no PR, work committed
in-progress
PR open
in-review
PR merged
done
issue closed and PR merged
done
(and it's a 
clean
 candidate)
sh
orca worktree set --worktree "branch:$BRANCH" --workspace-status in-review --json
Rules:
  • Preview every planned 
    set
    as one table, then take one OK for the batch.     Nothing is destroyed here, but it rewrites the user's sidebar — that deserves a look, not a surprise.
  • Never overwrite a 
    linkedIssue
    that's already set     to something different. A human or 
    orca worktree create --issue
    put it there deliberately; report the disagreement and leave it.
  • Never overwrite a hand-written 
    comment
    .     Set one only when it's empty.
  • Leave the main worktree alone. It isn't feature work and a status on it means nothing.
  • A branch that names no issue simply gets skipped. Say how many, don't invent links from slugs.
添加Orca无法自动推断的元数据，让工作区卡片真正展示其用途。
对于每个分支匹配
issue-<n>-<slug>
且
linkedIssue
为空的Git原生工作区：
sh
orca worktree set --worktree "branch:$BRANCH" --issue "$N" --json
并让
workspaceStatus
与跟踪系统保持一致。Orca的状态词汇包括
todo
、
in-progress
、
in-review
、
done
、
archived
；需根据实际状态映射，而非仅根据标签：
跟踪系统状态
workspaceStatus
issue打开，无PR，分支无提交
todo
issue打开，无PR，已有提交
in-progress
PR打开
in-review
PR已合并
done
issue已关闭且PR已合并
done
（属于
clean
的候选对象）
sh
orca worktree set --worktree "branch:$BRANCH" --workspace-status in-review --json
规则：
  • 将所有计划执行的
    set
    操作预览为一个表格，然后获取用户的一次性确认    。此操作不会销毁任何内容，但会修改用户的侧边栏——这值得用户查看，而非突然变更。
  • 切勿覆盖已设置的
    linkedIssue
    。该值是用户或
    orca worktree create --issue
    命令特意设置的；报告不一致情况并保留原设置。
  • 切勿覆盖手动编写的
    comment
    。仅当
    comment
    为空时才设置。
  • 不要修改主工作区。它不属于特性开发，设置状态没有意义。
  • 不包含issue编号的分支直接跳过。告知用户跳过的数量，不要从分支名称中凭空生成关联。

Hand off

操作收尾

Write every hand-off in this skill in the procedural register: one instruction per sentence, active voice, present tense, no metaphor.
What changed — how many workspaces gained an issue link, how many had their status corrected, how many were skipped and why.
Where it landed — in Orca's sidebar; nothing on disk moved and no git state changed.
Next — if 
link
marked anything 
done
, that set is exactly 
clean
's input, so crown that. Otherwise stop: linked cards are the end state, not a step toward one.
本工具中的所有收尾说明都采用过程式表述：每句一个指令，主动语态，现在时态，无隐喻。
变更内容——有多少工作区新增了issue关联，多少工作区修正了状态，多少被跳过及原因。
结果位置——变更体现在Orca的侧边栏中；磁盘上的内容未移动，Git状态也未改变。
下一步——如果
link
标记了某些工作区为
done
，这些工作区正是
clean
的处理对象，因此推荐执行该模式。否则终止操作：关联完成的卡片就是最终状态，无需进一步操作。

Mode: 
clean

模式：
clean

Reclaim the workspaces whose work already landed. Every removal is irreversible, so the shape is fixed: gather, qualify, preview everything at once, take one confirm, then remove.
回收已完成工作对应的工作区。所有移除操作都是不可逆的，因此流程固定为：收集、验证、一次性预览所有候选对象、获取确认、然后移除。

1. Qualify

1. 验证候选对象

A workspace is a candidate only when its work is provably merged and the tracker already agrees:
sh
gh pr list --head "$BRANCH" --state merged --json number,url,mergedAt
gh issue view "$N" --json state                       # must be CLOSED
  • Primary qualifier — a merged PR for the branch, and either no issue in the branch name or an issue that is already closed.
  • Secondary, shown as its own group — no PR ever existed, but the branch is fully merged into the base (
    git branch --merged "origin/$BASE"
    ; base resolved gitkit's way, never hard-coded 
    main
    ). Real for direct pushes, weaker evidence, so it gets its own section in the preview and is never bundled in with the primary rows.
A merged PR with an open issue is not a candidate. That's tracker drift; list it and route to issuekit 
close <n>
, which closes the issue, unblocks its dependents, and tears the worktree down — doing the job properly instead of deleting the evidence behind the tracker's back.
只有当工作已明确合并且跟踪系统已确认时，工作区才是候选对象：
sh
gh pr list --head "$BRANCH" --state merged --json number,url,mergedAt
gh issue view "$N" --json state                       # 必须为CLOSED
  • 主要验证条件——分支对应的PR已合并，且分支名称中无issue编号，或对应的issue已关闭。
  • 次要验证条件（单独分组展示）——从未创建过PR，但分支已完全合并到基准分支（
    git branch --merged "origin/$BASE"
    ；基准分支按照gitkit的方式解析，绝不硬编码为
    main
    ）。适用于直接推送的场景，证据强度较弱，因此在预览中单独分组，绝不与主要候选对象混在一起。
PR已合并但issue仍打开的工作区不是候选对象。这属于跟踪系统漂移；列出此类工作区并引导用户使用issuekit的
close <n>
命令，该命令会关闭issue、解除依赖、并清理工作树——以正确的方式完成任务，而非在跟踪系统背后删除证据。

2. Disqualify

2. 排除非候选对象

These are hard skips. Each appears in the preview under skipped, with its reason, so nothing vanishes from the report silently:
  • uncommitted changes or untracked files — 
    git status --porcelain
    is non-empty;
  • unpushed commits, or a branch with no upstream at all;
  • the main worktree, always;
  • the worktree you're currently inside — never delete the floor you're standing on;
  • live Orca terminals — 
    orca terminal list --worktree "branch:$BRANCH" --json
    . Offer 
    orca terminal stop --worktree "branch:$BRANCH"
    as a separate, explicitly confirmed step; never stop someone's running process as a side effect of tidying.
A merged PR does not imply an empty worktree. Scratch files, a stashed experiment, a follow-up commit that never got pushed — none of those are in the PR, and all of them live there.
以下情况直接跳过。每种情况都会在预览中列在已跳过部分并说明原因，确保没有内容从报告中静默消失：
  • 存在未提交变更或未跟踪文件——
    git status --porcelain
    非空；
  • 存在未推送提交，或分支没有上游分支；
  • 主工作区，始终跳过；
  • 当前所在的工作区——绝不要删除自己正在使用的工作区；
  • Orca活跃终端——
    orca terminal list --worktree "branch:$BRANCH" --json
    。提供
    orca terminal stop --worktree "branch:$BRANCH"
    作为单独的、需明确确认的步骤；切勿在清理时顺带终止用户正在运行的进程。
PR已合并不代表工作树为空。临时文件、暂存的实验内容、从未推送的后续提交——这些都不在PR中，但都存储在工作树里。

3. Preview and confirm

3. 预览与确认

One table, all candidates, each with the evidence that qualified it (PR number, merge date, issue state) and its kind (git-native or Orca-native). Skips listed below it with reasons. Then a single question, naming the count:
Remove 6 workspaces (4 git-native, 2 Orca-native)? 3 more were skipped — see above.
One OK covers the batch. If the user wants a subset, take the subset; don't re-prompt row by row.
生成一个表格，包含所有候选对象，每个对象都附带验证证据（PR编号、合并日期、issue状态）及其类型（Git原生或Orca原生）。已跳过的对象列在表格下方并说明原因。然后提出一个包含数量的问题：
是否移除6个工作区（4个Git原生，2个Orca原生）？另有3个工作区被跳过——详见上文。
一次确认即可处理所有候选对象。如果用户希望处理子集，则处理该子集；无需逐行重新提示。

4. Remove, by kind

4. 按类型移除

git-native → hand it to gitkit's teardown, which looks the worktree up by branch and removes it with native git:
sh
git -C "$REPO" worktree remove "$WT"
git -C "$REPO" branch -d "$BRANCH"     # -d, never -D
Then stop. Do not also call 
orca worktree rm
— Orca drops a discovered entry by itself, and a second removal on a path that's already gone just produces a confusing error. If gitkit isn't installed, the two commands above are the whole of it.
Orca-native → Orca owns it, so Orca removes it:
sh
orca worktree rm --worktree "path:$WT" --run-hooks --json
This is the one place orcakit runs a vendor command that also performs the git removal, and the reason is specific: Orca created this checkout, has an archive hook and terminal sessions bound to it, and its 
rm
sequences all three. Removing it with git first orphans Orca's metadata and skips the hook. The exception is confined to workspaces Orca created — it never extends to a gitkit worktree.
Never 
--force
. Every removal here is already gated on a clean tree and a merged PR; if git refuses anyway, that refusal is information. Report it and move to the next row.
Git原生→ 交给gitkit的清理流程，它会通过分支查找工作树并使用原生Git命令移除：
sh
git -C "$REPO" worktree remove "$WT"
git -C "$REPO" branch -d "$BRANCH"     # 使用-d，绝不要用-D
然后终止操作。不要同时调用
orca worktree rm
——Orca会自动删除已发现的条目，对已不存在的路径执行二次移除只会产生混淆性错误。如果未安装gitkit，上述两条命令就是完整的清理流程。
Orca原生→ 由Orca创建，因此由Orca移除：
sh
orca worktree rm --worktree "path:$WT" --run-hooks --json
这是orcakit唯一执行的厂商命令，同时会完成Git移除操作，原因很明确：Orca创建了这个检出，有绑定到它的归档钩子和终端会话，
rm
命令会按顺序处理这三者。如果先用Git移除，会导致Orca的元数据成为孤儿，并跳过钩子。此例外仅适用于Orca创建的工作区——绝不扩展到gitkit工作树。
切勿使用
--force
。此处的所有移除操作都已通过干净工作树和已合并PR的验证；如果Git仍拒绝，那这个拒绝是有意义的信息。报告该情况并处理下一行。

5. Hand off

5. 操作收尾

What changed — how many workspaces removed, by kind, and how many skipped. Name the skipped ones with reasons; a dirty worktree that survived is the single most important line in the report and goes first.
Where it landed — the paths that are gone and the branches deleted with them. Note that Orca's sidebar catches up within a few seconds, so an entry still visible right now isn't a failure.
Next — crown one:
  • anything skipped as dirty → that outranks everything. Name the path and tell the user to go look; unlanded work in a stale worktree is what actually gets lost.
  • tracker drift found → issuekit 
    close <n>
    on those issues, otherwise 
    gh issue close <n>
    plus a manual teardown.
  • nothing left to clean → say so plainly and stop. The right next move is somewhere else entirely — statuskit to re-orient if it's installed, otherwise nothing at all. Sidebar hygiene is not a loop worth repeating.
变更内容——移除了多少工作区，按类型统计，以及多少被跳过。列出被跳过的工作区及原因；未被清理的脏工作树是报告中最重要的内容，优先列出。
结果位置——已删除的路径和对应的分支。注意Orca的侧边栏会在几秒内更新，因此刚操作完仍可见的条目并非失败。
下一步——优先推荐：
  • 因脏工作树被跳过→ 这是最优先的事项。告知用户路径并让用户查看；失效工作树中未合并的工作才是真正可能丢失的内容。
  • 发现跟踪系统漂移→ 对这些issue使用issuekit的
    close <n>
    命令，否则使用
    gh issue close <n>
    命令并手动清理。
  • 无剩余内容可清理→ 直接告知用户并终止操作。合适的下一步操作完全在其他地方——如果已安装statuskit则使用它重新定位，否则无需操作。工作区维护不需要重复执行。

Mode: 
align

模式：
align

Stop Orca creating worktrees somewhere gitkit will never look. Orca's default is 
~/orca/workspaces/<repo>/<name>
; gitkit's convention is 
$WORKTREE_ROOT/<repo>/<branch>
(
~/worktrees
unless the environment says otherwise). Two roots means every sweep has to classify by path forever.
sh
orca project setups --json                                  # find the setup id for the repo
orca project setup-update --setup "$SETUP_ID" \
  --worktree-base-path "$WORKTREE_ROOT/$(basename "$REPO")" --json
Verify rather than assume. The setups listing does not echo the base path back, and whether Orca appends the repo name to it is not documented anywhere. So confirm it empirically, once per repo, with a throwaway:
sh
orca worktree create --repo "path:$REPO" --name orcakit-align-check --no-parent --json
避免Orca在gitkit永远不会查看的位置创建工作树。Orca的默认路径是
~/orca/workspaces/<repo>/<name>
；gitkit的约定路径是
$WORKTREE_ROOT/<repo>/<branch>
（默认
~/worktrees
，除非环境变量另有设置）。两个根目录意味着每次扫描都必须通过路径分类。
sh
orca project setups --json                                  # 找到仓库对应的setup id
orca project setup-update --setup "$SETUP_ID" \
  --worktree-base-path "$WORKTREE_ROOT/$(basename "$REPO")" --json
验证而非假设。设置列表不会回显基础路径，且Orca是否会在基础路径后追加仓库名称也没有文档说明。因此需针对每个仓库通过临时工作区进行经验验证：
sh
orca worktree create --repo "path:$REPO" --name orcakit-align-check --no-parent --json

read the path it reports:

读取它返回的路径：

.../worktrees/<repo>/orcakit-align-check → correct

.../worktrees/<repo>/orcakit-align-check → 正确

.../worktrees/<repo>/<repo>/orcakit-… → doubled; re-set the base to "$WORKTREE_ROOT"

.../worktrees/<repo>/<repo>/orcakit-… → 重复；将基础路径重新设置为"$WORKTREE_ROOT"

orca worktree rm --worktree "name:orcakit-align-check" --json

This is the one `orca worktree create` in the skill, and it exists only to read back a path — confirm it with the user, and remove the throwaway in the same breath. If the check is declined or can't run, say the base path was set **but not verified**; do not report a convergence you didn't observe.

**Existing worktrees are untouched.** Ones already under `~/orca/workspaces` keep working exactly as they are; git stores absolute paths, and moving them by hand needs `git worktree repair`. `align` only changes where the *next* one goes. Say that out loud, because "aligned" reads like "migrated" and it isn't.
orca worktree rm --worktree "name:orcakit-align-check" --json

这是本工具中唯一使用`orca worktree create`的场景，仅用于读取路径——请与用户确认，并立即删除临时工作区。如果用户拒绝验证或无法执行验证，请告知用户基础路径已设置**但未验证**；不要报告未实际观察到的一致性。

**现有工作区不受影响**。已在`~/orca/workspaces`下的工作区会继续正常工作；Git存储的是绝对路径，手动移动需要`git worktree repair`。`align`仅改变**下一个**工作树的创建位置。请明确告知用户这一点，因为“对齐”容易被误解为“迁移”，但实际并非如此。

Hand off

操作收尾

What changed — which repos had their base path set, and whether the throwaway check confirmed the resulting path.
Where it landed — the new base path per repo, and a reminder that existing workspaces stayed where they were.
Next — with one root in play, 
list
 is worth a run to see the whole set in one table. If nothing else is pending, stop; this is a one-time-per-repo setting, not a routine.
变更内容——哪些仓库的基础路径已设置，以及临时工作区验证是否确认了最终路径。
结果位置——每个仓库的新基础路径，以及现有工作区仍保留在原位置的提醒。
下一步——使用单一根目录后，值得运行一次
list
以表格形式查看所有工作区。如果没有其他待处理事项，则终止操作；这是每个仓库仅需设置一次的配置，而非日常操作。

Notes

注意事项

  • orcakit is machine-local and always optional. No Orca on the box means no-op, and nothing else in the workflow may depend on it. gitkit, issuekit, and the rest never call it — they'd break on every machine without the app. It's a janitor you run, not a link in a chain.
  • Worktree facts belong to gitkit. The default path convention appears here only as a declared portability fallback for machines without gitkit; everything else — branch naming, base-ref resolution, teardown rules — lives there, and any other copy of a gitkit fact here is the bug.
  • Tracker facts belong to issuekit. orcakit reads issue and PR state to judge a workspace; it writes none of it.
  • Destructive steps preview and confirm; read-only ones run straight through. 
    list
    never asks. 
    link
    previews a batch. 
    clean
    previews a batch and takes one OK. 
    align
    confirms before it creates its throwaway.
  • No shell available? Then you can't reach the 
    orca
    CLI or 
    gh
    . Reason from what the user gives you and print the exact commands as a codeblock for them to run — never report a workspace linked or removed that you could not perform.
  • orcakit是本地工具，且始终可选。本机没有Orca则无操作，工作流中的其他环节不得依赖它。gitkit、issuekit及其他工具绝不会调用它——否则在没有Orca的机器上会崩溃。它是您主动运行的清理工具，而非工作流中的必要环节。
  • 工作树相关规则属于gitkit。此处仅将默认路径约定作为无gitkit机器的可移植回退方案；其他所有内容——分支命名、基准分支解析、清理规则——都由gitkit负责，此处出现的任何gitkit规则副本都是错误。
  • 跟踪系统相关规则属于issuekit。orcakit仅读取issue和PR状态来判断工作区状态；绝不写入任何内容。
  • 破坏性操作需预览并确认；只读操作可直接运行。
    list
    从不询问。
    link
    预览批量操作。
    clean
    预览批量操作并获取一次确认。
    align
    在创建临时工作区前确认。
  • 无Shell可用？→ 无法访问
    orca
    CLI或
    gh
    。根据用户提供的信息推理，并将确切命令以代码块形式打印供用户自行运行——绝不要报告未实际执行的工作区关联或移除操作。