@sassywares/skills 0.10.0 → 0.11.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,151 @@
1
+ # Worktrees
2
+
3
+ Parallel work in one repo: each run gets its own checkout, its own branch, and
4
+ its own port, without a second clone and without fighting the checkout somebody
5
+ else is using.
6
+
7
+ Read this when the project has `worktrees.enabled: true`, or when the user asks
8
+ to run two agents in one project.
9
+
10
+ ## Install
11
+
12
+ Setup copies `assets/worktree/*` flat into `.sassywares/worktree/`, makes the
13
+ scripts executable, and wires one `worktree:<script>` alias per script into the
14
+ project's manifest — the same exception `workspace:*` uses. They are tracked: a
15
+ worktree is a checkout of the repo, so every worktree carries the tooling.
16
+
17
+ ```text
18
+ .sassywares/worktree/
19
+ ├── _lib.sh shared helpers; reads `worktrees:`; carries worktree-version
20
+ ├── create add a worktree, claim a port, print the namespace
21
+ ├── list the table; --address / --path for scripting
22
+ ├── stop kill whatever is on that worktree's port
23
+ ├── remove refuse unsafe removals, then delete
24
+ └── prune merged-or-gone candidates; removes only what you approve
25
+ ```
26
+
27
+ Nothing else lives there. No state, no registry, no pid file.
28
+
29
+ `_lib.sh` carries `# worktree-version: N`. Bump `N` when an asset changes;
30
+ `--check` compares the installed copy and reports a stale one. Ask before
31
+ overwriting an existing copy — from the first install it is the project's file.
32
+
33
+ ## Where things live
34
+
35
+ ```text
36
+ ~/.sassywares/worktrees/
37
+ └── <repo>/ <- the worktree home; .repo records which checkout owns it
38
+ ├── .repo absolute path of the main checkout
39
+ ├── ports/ claim directories, one per claimed port
40
+ └── <slug>/ a checkout
41
+ ```
42
+
43
+ `worktrees.dir` sets the parent (default `~/.sassywares/worktrees`). It is the
44
+ one path in the config that may be absolute or start with `~/` — it names
45
+ machine-local state, not something a teammate clones.
46
+
47
+ **Never put checkouts inside `.git` or inside the working tree.** Inside `.git`
48
+ is undocumented and breaks where `.git` is a file (linked worktrees, submodules,
49
+ `--separate-git-dir`). Inside the working tree is destroyed by `git clean -xdf`
50
+ and crawled by every scanner that does not read `.gitignore` (`tsc`, Docker).
51
+
52
+ **Never `rm -rf` the worktree home.** It is full of checkouts with uncommitted
53
+ work; `remove` and `prune` are the only safe exits.
54
+
55
+ ## The namespace
56
+
57
+ `create` derives and prints, for the caller and the hook:
58
+
59
+ | Variable | Example | Use |
60
+ |---|---|---|
61
+ | `WT_PATH` | `~/.sassywares/worktrees/shop/feat-catalog` | where the checkout is |
62
+ | `WT_BRANCH` | `feat/catalog` | the branch, as git names it |
63
+ | `WT_SLUG` | `feat-catalog` | the directory name, port key, registry key |
64
+ | `WT_NAMESPACE` | `shop-feat-catalog` | database schema, compose project, simulator name |
65
+ | `WT_PORT` | `3041` | the private port this checkout owns |
66
+ | `WT_BASE_URL` | `http://localhost:3041` | what to open |
67
+
68
+ Derived, never invented downstream: a hook that needs a database name uses
69
+ `$WT_NAMESPACE` rather than building its own, so two worktrees cannot collide by
70
+ accident.
71
+
72
+ **Ports.** The slug hashes into `worktrees.ports`, then the claim is taken with
73
+ an atomic `mkdir` and probed forward one port at a time on a collision. A claim
74
+ belongs to a slug, so a restarted app returns to the same port, and two slugs
75
+ that hash alike do not fight. `list` probes for liveness and never trusts a
76
+ recorded pid: a killed process leaves nothing to believe.
77
+
78
+ ## Hooks
79
+
80
+ Two points, keyed by head branch like every other hook:
81
+
82
+ ```yaml
83
+ hooks:
84
+ worktree:
85
+ "*":
86
+ after_create: [shop-worktree]
87
+ before_remove: [shop-worktree]
88
+ ```
89
+
90
+ `after_create` runs **after** the checkout exists — that is when a project
91
+ installs dependencies, derives `.env` from `$WT_NAMESPACE`, seeds a database or
92
+ creates a simulator, and copies the session. `before_remove` runs **before** the
93
+ files go, and is where the derived database or device is dropped.
94
+
95
+ A shell script cannot dispatch a skill, so `remove` fails closed: with a hook
96
+ declared and `--hook-ok` missing, it prints `require-hook <name>` and exits `3`.
97
+
98
+ **Never write a hook skill yourself** — the same rule as every other hook. Setup
99
+ records the name; the project writes the body.
100
+
101
+ ## Previewing a worktree
102
+
103
+ `sassy-worktree mode:preview` brings the product up in a checkout and prints
104
+ `how_to_see`, using the dogfood recipe's bring-up steps — everything up to, but
105
+ not including, that section's `Prove it:` step. It leaves the app running, and
106
+ `stop` (or `remove`) reaps it by port.
107
+
108
+ There is no separate preview configuration. How the app comes up is the recipe's
109
+ job, because it is the only place that knowledge is allowed to live.
110
+
111
+ **Sessions and third-party origins.** A worktree gets a fresh, empty
112
+ `.sassywares/session/`. Most providers register one callback URL, so a worktree
113
+ usually cannot log in on its own; the recipe's *Working in a second checkout*
114
+ section says how this project solves that, and the `after_create` hook does it —
115
+ copying or linking the main checkout's session is the common answer. A cookie is
116
+ host-scoped and crosses ports freely; a `localStorage` session is origin-scoped,
117
+ port included, and has to be injected per origin. That difference is worth
118
+ writing down once in the recipe rather than rediscovering it.
119
+
120
+ ## Refusals
121
+
122
+ `remove` refuses, and `prune` skips rows it cannot prove safe:
123
+
124
+ | Condition | Why |
125
+ |---|---|
126
+ | It is the main checkout | the repo itself |
127
+ | Dirty tree | uncommitted work |
128
+ | Commits on no remote | nothing to recover from |
129
+ | Something listening on its port | stop the app first |
130
+ | A `before_remove` hook not yet run | the project has cleanup to do |
131
+
132
+ `--force` skips the dirty and unpushed checks and nothing else. It is never
133
+ implied.
134
+
135
+ ## Concurrency rules
136
+
137
+ - **One worktree per run.** `references/branching.md` decides; a run already on
138
+ a non-base branch reuses it, so a second `sassy-work` in the same checkout does
139
+ not nest another worktree.
140
+ - **Never operate on another worktree.** A delegation brief carries the absolute
141
+ path of the checkout it may touch; `MAIN` is for reading config and listing.
142
+ - **Never `git stash`.** It is repository-global: a stash taken in one worktree
143
+ appears in all of them. A worktree already gives you what stash was for.
144
+ - **Never `git checkout` a branch in two places.** Git refuses it — that refusal
145
+ is a feature, and `create` reports it as such.
146
+ - **Do not copy `node_modules`.** Hardlink copies share inodes, so a rewrite
147
+ through one checkout corrupts the other. Let the package manager's store do
148
+ the deduplicating.
149
+ - **`worktrees.enabled` needs `commit.branch: new`.** Under `current` a run
150
+ commits where it stands and never cuts a branch, so no run would ever create a
151
+ worktree; `--check` notes the combination.
@@ -72,6 +72,7 @@ is_suite_skill() {
72
72
  }
73
73
  ASSET_SNAPSHOT="$SKILL_DIR/assets/snapshot"
74
74
  ASSET_WORKSPACE="$SKILL_DIR/assets/workspace"
75
+ ASSET_WORKTREE="$SKILL_DIR/assets/worktree"
75
76
 
76
77
  # The nearest config wins, walking up. Report where it is if one exists.
77
78
  CONFIG=""
@@ -257,6 +258,7 @@ hook_points() {
257
258
  case "$1" in
258
259
  pr) printf '%s' "before_create after_create before_merge after_merge" ;;
259
260
  push) printf '%s' "after_push" ;;
261
+ worktree) printf '%s' "after_create before_remove" ;;
260
262
  esac
261
263
  }
262
264
 
@@ -410,6 +412,7 @@ if (( CHECK )); then
410
412
  commit.branch) ;;
411
413
  pr.babysit|pr.merge|pr.delete_branch) ;;
412
414
  dogfood.enabled|dogfood.recipe|dogfood.reports|dogfood.timeout) ;;
415
+ worktrees.enabled|worktrees.dir|worktrees.ports) ;;
413
416
  hooks.*) ;; # shape checked with the hooks
414
417
  *) bad "unknown key '$key' — it is ignored, so the run uses the default" ;;
415
418
  esac
@@ -561,7 +564,7 @@ if (( CHECK )); then
561
564
  if [[ -n "$(yflat "hooks${US}pr${US}before_create")" ]]; then
562
565
  bad "hooks.pr.<point> is now nested by head branch — write hooks.pr.\"*\".<point>"
563
566
  fi
564
- for kind in pr push; do
567
+ for kind in pr push worktree; do
565
568
  while IFS= read -r pat; do
566
569
  [[ -n "$pat" ]] || continue
567
570
  case "$pat" in
@@ -591,8 +594,8 @@ if (( CHECK )); then
591
594
  [[ -n "$depth" ]] || continue
592
595
  kind="${hpath#hooks$US}"; kind="${kind%%$US*}"
593
596
  case "$kind" in
594
- pr|push) ;;
595
- *) bad "hooks kind '$kind' is not one of pr|push"; continue ;;
597
+ pr|push|worktree) ;;
598
+ *) bad "hooks kind '$kind' is not one of pr|push|worktree"; continue ;;
596
599
  esac
597
600
  if [[ "$depth" != "4" ]]; then
598
601
  bad "hooks entry '${hpath//$US/.}' is not head -> point -> list"
@@ -612,7 +615,7 @@ if (( CHECK )); then
612
615
  if [[ "$TOPOLOGY" == "repo" ]]; then
613
616
  note " base for '$HEAD_ARG': $(base_for_head "$HEAD_ARG")"
614
617
  fi
615
- for kind in pr push; do
618
+ for kind in pr push worktree; do
616
619
  for point in $(hook_points "$kind"); do
617
620
  resolved="$(hooks_for_head_point "$HEAD_ARG" "$point" "$kind")"
618
621
  note " head '$HEAD_ARG' → $point: $( [[ -n "$resolved" ]] && printf '%s' "$resolved" || printf 'none' )"
@@ -691,6 +694,114 @@ if (( CHECK )); then
691
694
  esac
692
695
  fi
693
696
 
697
+ # Worktrees: a switch and three mechanical settings. Creating, claiming, and
698
+ # refusing all belong to the scripts, so this validates only what a run reads.
699
+ wt_on="$(block_value worktrees enabled || true)"
700
+ wt_dir="$(block_value worktrees dir || true)"
701
+ wt_ports="$(block_value worktrees ports || true)"
702
+ case "$wt_on" in
703
+ "") ;;
704
+ true|false) note " worktrees.enabled: $wt_on" ;;
705
+ *) bad "worktrees.enabled '$wt_on' must be true|false" ;;
706
+ esac
707
+ if [[ -n "$wt_ports" ]]; then
708
+ case "$wt_ports" in
709
+ *-*) wt_lo="${wt_ports%%-*}"; wt_hi="${wt_ports##*-}" ;;
710
+ *) wt_lo=""; wt_hi=""; bad "worktrees.ports '$wt_ports' is not <from>-<to>" ;;
711
+ esac
712
+ if [[ -n "$wt_lo" ]]; then
713
+ case "$wt_lo$wt_hi" in
714
+ *[!0-9]*) bad "worktrees.ports '$wt_ports' is not numeric" ;;
715
+ *) if (( wt_lo < 1 || wt_hi > 65535 || wt_lo > wt_hi )); then
716
+ bad "worktrees.ports '$wt_ports' is not a usable port range"
717
+ else
718
+ note " worktrees.ports: $wt_ports"
719
+ fi ;;
720
+ esac
721
+ fi
722
+ fi
723
+
724
+ if [[ "$wt_on" == "true" ]]; then
725
+ if [[ "$TOPOLOGY" != "repo" ]]; then
726
+ bad "worktrees.enabled needs a repo — this folder is '$TOPOLOGY', and a checkout needs git"
727
+ else
728
+ if [[ "$(yflat "commit${US}branch" 2>/dev/null || true)" == "current" ]]; then
729
+ note " worktrees.enabled with commit.branch: current — a run never cuts a branch, so no run creates one"
730
+ fi
731
+
732
+ wt_lib="$ROOT/.sassywares/worktree/_lib.sh"
733
+ if [[ -f "$wt_lib" ]]; then
734
+ installed_wt="$(sed -n 's/^# worktree-version: //p' "$wt_lib" | head -n 1)"
735
+ asset_wt="$(sed -n 's/^# worktree-version: //p' "$ASSET_WORKTREE/_lib.sh" | head -n 1)"
736
+ if [[ -z "$installed_wt" ]]; then
737
+ bad "installed .sassywares/worktree/_lib.sh has no worktree-version line"
738
+ elif [[ -n "$asset_wt" && "$installed_wt" != "$asset_wt" ]]; then
739
+ bad "installed worktree tooling is v${installed_wt}, this skill ships v${asset_wt} — re-run setup"
740
+ else
741
+ note " worktree tooling v${installed_wt}"
742
+ fi
743
+ for helper in create list stop remove prune; do
744
+ [[ -x "$ROOT/.sassywares/worktree/$helper" ]] \
745
+ || bad "missing or not executable: .sassywares/worktree/$helper"
746
+ done
747
+ else
748
+ bad "worktrees.enabled but .sassywares/worktree/_lib.sh is missing — re-run setup"
749
+ fi
750
+
751
+ # A checkout must live outside the working tree — inside it, `git clean
752
+ # -xdf` deletes uncommitted work and every scanner that ignores .gitignore
753
+ # crawls a second copy of the source. And a worktree parked on a configured
754
+ # base is a run that will commit onto a shared branch unobserved.
755
+ root_real="$(cd "$ROOT" && pwd -P)"
756
+ BASE_VALUES="$(yaml_flat "$CONFIG" \
757
+ | awk -F'\t' -v us="$US" '{n=split($1,a,us); if (n==3 && a[1]=="git" && a[2]=="base_map") print $2}' \
758
+ | tr '\n' ' ')"
759
+ wt_paths=()
760
+ while IFS=$'\t' read -r wpath wbranch; do
761
+ [[ -n "$wpath" ]] || continue
762
+ wt_paths+=("$wpath")
763
+ [[ "$wpath" == "$root_real" ]] && continue # the main checkout
764
+ case "$wpath" in
765
+ "$root_real"/*) bad "worktree '$wpath' is inside the working tree — move worktrees.dir outside it" ;;
766
+ esac
767
+ case " $BASE_VALUES " in
768
+ *" $wbranch "*) bad "a worktree holds '$wbranch', which base_map names as a base" ;;
769
+ esac
770
+ done < <(git -C "$ROOT" worktree list --porcelain 2>/dev/null \
771
+ | awk '/^worktree /{p=$2} /^branch /{b=$2; sub(/^refs\/heads\//,"",b); print p "\t" b; p=""} /^detached/{print p "\t(detached)"; p=""}')
772
+
773
+ # Orphan port claims: the worktree is gone but its port is still taken, so
774
+ # a later checkout is pushed off it for no reason.
775
+ wt_homef=""
776
+ d="${wt_dir:-$HOME/.sassywares/worktrees}"
777
+ case "$d" in
778
+ "~") d="$HOME" ;;
779
+ "~/"*) d="$HOME/${d#\~/}" ;;
780
+ /*) ;;
781
+ *) d="$ROOT/$d" ;;
782
+ esac
783
+ cand="$d/$(basename "$ROOT")"
784
+ if [[ -f "$cand/.repo" && "$(cat "$cand/.repo" 2>/dev/null)" != "$root_real" ]]; then
785
+ cand="$d/$(basename "$ROOT")-$(printf '%s' "$root_real" | shasum -a 256 | cut -c1-6)"
786
+ fi
787
+ [[ -d "$cand" ]] && wt_homef="$cand"
788
+ if [[ -n "$wt_homef" && -d "$wt_homef/ports" ]]; then
789
+ for claim in "$wt_homef"/ports/*; do
790
+ [[ -d "$claim" ]] || continue
791
+ owner="$(cat "$claim/owner" 2>/dev/null || true)"
792
+ [[ -n "$owner" ]] || continue
793
+ found=0
794
+ if (( ${#wt_paths[@]} )); then
795
+ for p in "${wt_paths[@]}"; do
796
+ [[ "$p" == *"/$owner" ]] && found=1
797
+ done
798
+ fi
799
+ (( found )) || bad "port $(basename "$claim") is claimed by '$owner', which has no worktree"
800
+ done
801
+ fi
802
+ fi
803
+ fi
804
+
694
805
  # Dogfood is a pointer and a switch, never commands: the recipe holds the
695
806
  # procedure and its `Prove it:` step is the verdict. Everything below is
696
807
  # structural. A check run never runs the product — a validator that boots an
@@ -736,6 +847,16 @@ if (( CHECK )); then
736
847
  fi
737
848
  fi
738
849
 
850
+ # A committed session is a credential leak, not merely a heavy history. Only
851
+ # checked once the folder exists, so a project that never uses one is silent.
852
+ if [[ "$TOPOLOGY" == "repo" && -d "$ROOT/.sassywares/session" ]]; then
853
+ if git -C "$ROOT" check-ignore -q -- ".sassywares/session/probe" 2>/dev/null; then
854
+ note " .sassywares/session is gitignored"
855
+ else
856
+ bad ".sassywares/session is not gitignored — a session artifact must never be committed"
857
+ fi
858
+ fi
859
+
739
860
  if [[ -n "$dg_recipe" ]]; then
740
861
  if [[ ! -f "$ROOT/$dg_recipe" ]]; then
741
862
  if [[ "$dg_enabled" == "true" ]]; then
@@ -1162,6 +1283,19 @@ cat <<'EOF'
1162
1283
  EOF
1163
1284
  cat <<'EOF'
1164
1285
 
1286
+ # --- Worktrees ------------------------------------------------------------
1287
+ # Parallel work in one repo: a checkout per branch, each with its own derived
1288
+ # namespace and port, so two runs never fight over one working tree. enabled:
1289
+ # true lets a run create one instead of working here — and needs
1290
+ # commit.branch: new, because `current` never cuts a branch. The scripts in
1291
+ # .sassywares/worktree/ own the mechanics; nothing else reads these values.
1292
+ worktrees:
1293
+ EOF
1294
+ kv enabled false 34 '# true = a run may work in its own checkout'
1295
+ kv dir '~/.sassywares/worktrees' 34 '# parent of the per-repo folder; ~ is allowed'
1296
+ kv ports 3000-3099 34 '# the range a checkout claims a port from'
1297
+ cat <<'EOF'
1298
+
1165
1299
  # --- Dogfood --------------------------------------------------------------
1166
1300
  # Agent QA: a stored procedure that proves a change works in the running
1167
1301
  # product. This block only points at it — commands live in the recipe, because
@@ -0,0 +1,87 @@
1
+ ---
2
+ name: sassy-worktree
3
+ description: >-
4
+ Run more than one agent, or more than one line of work, in the same repo: a
5
+ worktree per branch, each with its own derived namespace and port, created and
6
+ torn down safely. `mode:preview` brings a checkout up so you can look at it
7
+ without setting it up by hand. Use when asked for parallel work, a second
8
+ checkout, or to see what a worktree looks like.
9
+ argument-hint: "[slug] [mode:create|list|preview|remove|prune] [section:<name>]"
10
+ ---
11
+
12
+ # Sassy Worktree
13
+
14
+ **Outcome:** a checkout per branch that a run or a human can use without touching the main one — created, addressed, previewed, and removed without losing work — or a table saying what exists and what is safe to delete.
15
+
16
+ **Config.** Resolve `.sassywares/config.yaml` (nearest, walking up) per the `sassy-setup` skill's `references/config.md`. `worktrees.enabled` decides whether any of this runs; `dir` and `ports` are read by the scripts, not by you. Precedence: explicit token > session instruction > config > skill default. Read `references/worktree.md` in the `sassy-setup` skill before the first mode.
17
+
18
+ **The scripts do the git.** `.sassywares/worktree/{create,list,stop,remove,prune}` are installed by `sassy-setup` and own the mechanics: `git worktree`, the port claim, the refusals. This skill never runs `git worktree` itself, never invents a port, and never deletes a directory.
19
+
20
+ **Harness.** Loading another skill, dispatching an agent, and any command you hand the user follow the `sassy-setup` skill's `references/harness.md`. Read it once per run, before the first of those.
21
+
22
+ ## Modes
23
+
24
+ | Mode | What it does |
25
+ |------|--------------|
26
+ | `list` (default) | The table: branch, worktree, address, liveness, last dogfood verdict |
27
+ | `create` | Add a worktree for the run's branch, claim its port, dispatch `after_create` |
28
+ | `preview` | Bring that checkout up and print how to see it; leave it running. `stop` reaps it |
29
+ | `remove` | Dispatch `before_remove`, then delete after the script's refusals pass |
30
+ | `prune` | Show merged-or-gone worktrees that are safe to delete, then remove what you approve |
31
+
32
+ `list` is the default because it is the only mode that changes nothing.
33
+
34
+ ## `create`
35
+
36
+ 1. **Resolve the branch and its start point first**, through the `sassy-setup` skill's `references/branching.md`, exactly as `sassy-work` does. A run that reaches here has already decided; the branch is not created twice. When a human asks for one by hand with no branch named, ask for the branch name — never derive one.
37
+ 2. **Run `.sassywares/worktree/create <branch> --from <start-point>`** with the resolved start point. It is idempotent: an existing worktree for that branch is reported, a branch held by the main checkout is refused, and a port is claimed either way. On `--env` it prints the `WT_*` block alone.
38
+ 3. **Dispatch the declared hooks.** The script prints one line per `hooks.worktree.after_create` entry; it cannot dispatch a skill, so you do. One `worker` each, in declared order: *load the project skill at `.agents/skills/<name>/SKILL.md` and follow it*, briefed with the `WT_*` block and the fact that the checkout now exists. A missing skill or a `blocked` result stops here — the checkout is real but unprepared, and saying so is the report.
39
+ 4. **Report** the path, branch, namespace, port, address, and the hooks that ran or that none are declared. If the caller is a run, tell it to work in `WT_PATH` from now on.
40
+
41
+ ## `list`
42
+
43
+ Run `.sassywares/worktree/list` and present it as it prints — branch, worktree, address, live, last verdict. `--address <slug>` and `--path <slug>` print one value for scripting. Never summarise the table away: the address is the point.
44
+
45
+ ## `preview`
46
+
47
+ 1. **Resolve the target and the section.** `preview <slug>` uses that checkout; with none, ask which. `section:<name>` names a dogfood recipe section; with none, use the first.
48
+ 2. **Read the recipe** at `dogfood.recipe`. Two things stop the run, and both are reported rather than worked around: no recipe (the project has no stored procedure — say to run `sassy-dogfood mode:discover`), or the section has no `Prove it:` step (nothing marks where bringing-up ends).
49
+ 3. **Preflight the session.** If the recipe's *Working in a second checkout* or *Set up once* names a session artifact and `.sassywares/session/` in **that checkout** is empty, that is `class: env`: report it with the line that fixes it and stop. Never open a logged-out app and call it a preview — the human will read the login screen as a broken build.
50
+ 4. **Run the bring-up.** In `WT_PATH`: the recipe's *Set up once* when the checkout is cold (no `.env`, no installed deps), then the section's steps in order **up to but not including** its `Prove it:` step. Judge each step by its `Expect`. A failure stops the preview and is reported with the step id and its output tail — a preview that half-started is not a preview.
51
+ 5. **Leave it running and report how to see it.** Print the address from `list --address`, plus the recipe's `**Preview:**` line when it has one (a simulator name, a desktop app, a URL). Verify it answers before you call it up: the address is a promise.
52
+ 6. **To stop it,** run `.sassywares/worktree/stop <slug>` — by port, never by a recorded pid.
53
+
54
+ Preview never judges the work, never writes a report, never commits, and never returns a verdict. If the user wants to know whether it *works*, that is `sassy-dogfood mode:run`.
55
+
56
+ ## `remove`
57
+
58
+ 1. **Dispatch `before_remove` first**, one `worker` per declared entry, briefed with the `WT_*` block and that the checkout is about to go. Its job is the project's cleanup: drop the derived database, shut the simulator.
59
+ 2. **Run `.sassywares/worktree/remove <slug> --hook-ok`.** Without `--hook-ok` it exits `3` by design when a hook is declared — that exit is the handshake, not an error to route around.
60
+ 3. **Report a refusal verbatim and stop.** Dirty tree, unpushed commits, a live preview, the main checkout: each is a real reason, and `--force` is the user's call, never yours. On success report the released port and the removed path.
61
+
62
+ ## `prune`
63
+
64
+ 1. Run `.sassywares/worktree/prune` with no flag and show the table.
65
+ 2. Ask before removing. `--yes` removes only rows marked `removable`: merged into their upstream or whose upstream is gone, clean, fully pushed, not running, and no `before_remove` hook it would skip. Rows with a hook are reported so the user can run `remove <slug>` instead and get the cleanup.
66
+ 3. Report the counts — removed, left, and why each skipped row was skipped.
67
+
68
+ ## Hard rules
69
+
70
+ | Rule | Requirement |
71
+ |------|-------------|
72
+ | The scripts do the git | Never run `git worktree`, never invent a port, never `rm -rf` a checkout. `.sassywares/worktree/*` owns all of it. |
73
+ | One worktree per run | The branch decision belongs to `references/branching.md`. Never create a second worktree for a run already on its branch. |
74
+ | Names come from the script | `WT_NAMESPACE` and `WT_PORT` are derived once. Never build a database name, a compose project, or a device name by hand. |
75
+ | Hooks are dispatched, not skipped | A declared `after_create` or `before_remove` runs. `remove` exits `3` rather than skipping it, and that is deliberate. |
76
+ | Never force on your behalf | `--force` skips the dirty and unpushed checks. Only the user's explicit instruction passes it. |
77
+ | Preview is a promise | Report an address only when something answers on it. A half-started app is a failure with a step id, not a preview. |
78
+ | No verdicts | This skill never says whether the work is correct. That is `sassy-dogfood`'s job, with a report. |
79
+ | No state of its own | Liveness is probed at read time. There is no registry, no pid file, and nothing to go stale. |
80
+ | Never production | A preview serves the local or staging app. A recipe step pointing at production is refused and reported. |
81
+ | The main checkout is read-only here | Read config from it, list from it, never work in it on a run's behalf. |
82
+
83
+ ## What worktree is not
84
+
85
+ Not a second clone: the checkouts share one object store and one branch lock, so two worktrees can never hold the same branch — which is the property that makes this safe and a `git clone` per agent unsafe.
86
+
87
+ Not a dogfooding skill. It brings a product up so a human can look; `sassy-dogfood` proves a change works and returns a verdict. When the two meet, they meet at the recipe.