docs(skills): drop installer details from the git workflows

These skills resolve the layout from the PATH launcher and Git, so how the
checkout was installed never enters the procedure. Describing install
shapes, the installer script, and its variables added detail a reader must
hold and would go stale whenever the installer changes.

Both skills now describe the observable state they resolve. The cases that
mattered survive as properties of that state: the main clone may sit
anywhere on any branch, and a launcher may link straight at a worktree with
no `current`.
This commit is contained in:
Turtle
2026-07-31 22:35:27 +08:00
parent 8d62467823
commit 6e913fe8bb
2 changed files with 3 additions and 3 deletions
+1 -1
View File
@@ -14,7 +14,7 @@ Do not assume a path or branch name. DSH is usually installed from source with a
1. Inspect `command -v dsh` in the user's launch environment before resolving symlinks.
2. Follow the launcher through the full symlink chain to reach the source checkout, then ask Git for everything else. The `dsh` on PATH is a symlink, usually through a stable `current` symlink into the active staging worktree; resolve the chain physically and take the launcher's parent directory as the checkout. Derive the rest from that checkout rather than from any path convention: `git -C <checkout> rev-parse --show-toplevel` confirms the checkout root, and `git -C <checkout> rev-parse --git-common-dir` gives the shared git directory — a linked worktree reports the real clone's, not its own — whose parent is the main clone, the one real clone whose object store every worktree shares. `--git-common-dir` answers relatively for a plain clone, so anchor it against the checkout before use, and resolve it physically: comparing a resolved path against an unresolved one silently misidentifies the clone, since macOS reaches `/var` through a symlink to `/private/var`. `git -C <main clone> worktree list` then enumerates every checkout sharing it.
This one procedure covers every install. [`scripts/install.sh`](../../scripts/install.sh) puts staging worktrees and `current` under a container directory (default `~/.dsh/source`), and a `curl` install also clones into that container while installing from an existing clone adopts that clone where it already lives — but nothing in this workflow depends on which happened, on the container's path, or on the main clone's branch. `DSH_SOURCE` and the installer's other variables exist only while the installer runs; they are never exported, so never read them here. An older install may link PATH straight at a worktree with no `current`, which the same launcher-then-Git procedure resolves unchanged.
This resolves every checkout, so depend on nothing else: not an environment variable, not a container path, not the main clone's location or branch. A checkout whose launcher links straight at it, with no `current` in the chain, resolves the same way.
3. Verify the checkout with Git, then record its branch, tip, status, remotes, worktrees, in-progress operations, and applicable `AGENTS.md` files.
4. Treat the launcher checkout's branch as staging unless the user says otherwise. The installed launcher must resolve to a staging worktree on a staging branch, never the main clone or a task, preparation, review, publication, or detached checkout. Ask if the launcher, checkout, or branch ownership is ambiguous; warn explicitly for a detached HEAD, the main clone, or a non-staging branch.
+2 -2
View File
@@ -9,9 +9,9 @@ Prepare and validate the upgrade in a fresh staging worktree of the main clone,
## Layout
Resolve the layout, never assume it. [`dsh-customize`](../dsh-customize/SKILL.md) owns the procedure: follow the PATH launcher to the staging worktree, then derive the main clone from that checkout with Git. It resolves every install the same way, so this workflow needs no special case for how DSH was installed and never reads the installer's variables, which exist only while the installer runs.
Resolve the layout, never assume it. [`dsh-customize`](../dsh-customize/SKILL.md) owns the procedure: follow the PATH launcher to the staging worktree, then derive the main clone from that checkout with Git. One resolution covers every checkout, so this workflow needs no special case and depends on no environment variable.
The resolved layout is one container directory `<source>` holding each staging checkout as a git worktree `<source>/staging-<timestamp>` on branch `dsh-staging/<timestamp>`, plus the stable symlink `<source>/current` pointing at the active one; the PATH launcher links to `<source>/current/bin/dsh`, so it resolves PATH -> `current` -> staging worktree. The main clone is the one real clone whose object store every worktree shares, and is never a launcher target. It may live inside `<source>` or anywhere else on disk, on any branch, with remotes that may point at a fork — so treat it strictly as the object store and worktree host, and take authoritative upstream from step 1 instead. Cutover repoints `current` alone; the PATH launcher is written once at install and never moves. The main clone's `.git/info/exclude` is inherited by every linked worktree, so one `.agents/merge.lock` entry there excludes the lock in all of them. An older install may link PATH straight at a worktree with no `current`; the same resolution finds it, and cutover then creates `current` and repoints PATH to `current/bin/dsh` as a one-time migration.
The resolved layout is one container directory `<source>` holding each staging checkout as a git worktree `<source>/staging-<timestamp>` on branch `dsh-staging/<timestamp>`, plus the stable symlink `<source>/current` pointing at the active one; the PATH launcher links to `<source>/current/bin/dsh`, so it resolves PATH -> `current` -> staging worktree. The main clone is the one real clone whose object store every worktree shares, and is never a launcher target. It may live inside `<source>` or anywhere else on disk, on any branch, with remotes that may point at a fork — so treat it strictly as the object store and worktree host, and take authoritative upstream from step 1 instead. Cutover repoints `current` alone, so the PATH launcher itself never moves. The main clone's `.git/info/exclude` is inherited by every linked worktree, so one `.agents/merge.lock` entry there excludes the lock in all of them. When the launcher links straight at a worktree with no `current` in the chain, the same resolution finds it, and cutover creates `current` and repoints PATH to `current/bin/dsh` as a one-time migration.
## Names