@sassywares/skills 0.10.0 → 0.11.1

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,104 @@
1
+ #!/usr/bin/env bash
2
+ # Add a worktree for one branch and claim its port.
3
+ #
4
+ # Idempotent: a branch already in a worktree of ours is reported, not recreated,
5
+ # and nobody else's checkout holding it is a stop rather than a clobber.
6
+ #
7
+ # Usage: .sassywares/worktree/create <branch> [--from <start-point>] [--env]
8
+ # .sassywares/worktree/create --version
9
+ set -euo pipefail
10
+
11
+ SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
12
+ # shellcheck source=./_lib.sh
13
+ source "$SCRIPT_DIR/_lib.sh"
14
+
15
+ usage() {
16
+ cat <<'EOF'
17
+ Usage: .sassywares/worktree/create <branch> [--from <start-point>] [--env]
18
+
19
+ Create (or report) the worktree for <branch>, claim its port, and print the
20
+ namespace a run inherits: WT_PATH, WT_BRANCH, WT_SLUG, WT_NAMESPACE, WT_PORT,
21
+ WT_BASE_URL.
22
+
23
+ --from <ref> where a new branch is cut from (default HEAD). A caller that has
24
+ already resolved the base passes it; this script never guesses.
25
+ --env print only `WT_*=<value>` lines, for eval.
26
+ EOF
27
+ }
28
+
29
+ branch=""
30
+ from="HEAD"
31
+ env_only=0
32
+ while [ $# -gt 0 ]; do
33
+ case "$1" in
34
+ -h|--help) usage; exit 0 ;;
35
+ --version) printf '%s\n' "$WT_VERSION"; exit 0 ;;
36
+ --env) env_only=1 ;;
37
+ --from) shift; from="${1:-}"; [ -n "$from" ] || die "--from needs a start point" ;;
38
+ --from=*) from="${1#*=}" ;;
39
+ -*) die "unknown flag: $1 (try --help)" ;;
40
+ *) [ -z "$branch" ] || die "one branch at a time"; branch="$1" ;;
41
+ esac
42
+ shift
43
+ done
44
+ [ -n "$branch" ] || { usage >&2; exit 2; }
45
+
46
+ need_git
47
+ wt_enabled || die "worktrees are off here — set worktrees.enabled: true in .sassywares/config.yaml"
48
+
49
+ slug="$(wt_slug "$branch")"
50
+ path="$(wt_path "$slug")"
51
+
52
+ report() { # $1 path, $2 branch
53
+ local port addr ns
54
+ ns="$(wt_namespace "$slug")"
55
+ port="$(wt_claim "$slug")"
56
+ addr="http://localhost:$port"
57
+ if [ "$env_only" -eq 1 ]; then
58
+ printf 'WT_PATH=%s\nWT_BRANCH=%s\nWT_SLUG=%s\nWT_NAMESPACE=%s\nWT_PORT=%s\nWT_BASE_URL=%s\n' \
59
+ "$1" "$2" "$slug" "$ns" "$port" "$addr"
60
+ return 0
61
+ fi
62
+ ok worktree "$1"
63
+ ok branch "$2"
64
+ ok namespace "$ns"
65
+ ok port "$port"
66
+ ok address "$addr"
67
+ local hooks n
68
+ hooks="$(wt_hook after_create "$2")"
69
+ if [ -z "$hooks" ]; then
70
+ ok hook "hooks.worktree.after_create — none declared"
71
+ else
72
+ while IFS= read -r n; do
73
+ [ -n "$n" ] || continue
74
+ ok hook "after_create → $n (dispatch it, with WT_* above)"
75
+ done <<<"$hooks"
76
+ fi
77
+ }
78
+
79
+ # Already in a worktree of ours: report and stop. This is the second call in a
80
+ # resumed run, and it must not fail.
81
+ existing="$(wt_find "$branch" || true)"
82
+ if [ -n "$existing" ]; then
83
+ epath="${existing%%$'\t'*}"
84
+ if wt_is_main "$epath"; then
85
+ die "'$branch' is checked out in the main checkout — leave it, or switch the main checkout first"
86
+ fi
87
+ report "$epath" "$branch"
88
+ exit 0
89
+ fi
90
+
91
+ if [ -e "$path" ]; then
92
+ die "'$path' exists but no worktree is registered for '$branch' — inspect it, then prune"
93
+ fi
94
+
95
+ (umask 077; mkdir -p "$(wt_home)/ports")
96
+ printf '%s\n' "$MAIN" > "$(wt_home)/.repo"
97
+
98
+ if git show-ref --verify --quiet "refs/heads/$branch"; then
99
+ git worktree add --quiet "$path" "$branch"
100
+ else
101
+ git worktree add --quiet -b "$branch" "$path" "$from"
102
+ fi
103
+
104
+ report "$path" "$branch"
@@ -0,0 +1,78 @@
1
+ #!/usr/bin/env bash
2
+ # Show every worktree of this repo: branch, path, address, whether anything is
3
+ # listening there, and the last dogfood verdict.
4
+ #
5
+ # Liveness is probed, never read from a pid file — a killed preview leaves no
6
+ # stale entry to believe.
7
+ #
8
+ # Usage: .sassywares/worktree/list [--address <slug>] [--path <slug>] [--version]
9
+ set -euo pipefail
10
+
11
+ SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
12
+ # shellcheck source=./_lib.sh
13
+ source "$SCRIPT_DIR/_lib.sh"
14
+
15
+ usage() {
16
+ cat <<'EOF'
17
+ Usage: .sassywares/worktree/list [--address <slug>] [--path <slug>]
18
+
19
+ Print every worktree with its address and last verdict.
20
+
21
+ --address <slug> print only the base URL of one worktree
22
+ --path <slug> print only the path of one worktree (for cd "$(...)")
23
+ EOF
24
+ }
25
+
26
+ want="" kind=""
27
+ while [ $# -gt 0 ]; do
28
+ case "$1" in
29
+ -h|--help) usage; exit 0 ;;
30
+ --version) printf '%s\n' "$WT_VERSION"; exit 0 ;;
31
+ --address|--path) kind="${1#--}"; shift; want="${1:-}"; [ -n "$want" ] || die "$kind needs a slug" ;;
32
+ -*) die "unknown flag: $1 (try --help)" ;;
33
+ *) die "unexpected argument: $1 (try --help)" ;;
34
+ esac
35
+ shift
36
+ done
37
+
38
+ need_git
39
+
40
+ one() { # $1 path, $2 branch
41
+ local p="$1" b="$2" slug port
42
+ slug="$(wt_slug "$b")"
43
+ if wt_is_main "$p"; then
44
+ die "the main checkout has no derived port — it uses whatever the app defaults to"
45
+ fi
46
+ case "$kind" in
47
+ path) printf '%s\n' "$p" ;;
48
+ address)
49
+ port="$(wt_port_for "$slug")"
50
+ printf 'http://localhost:%s\n' "$port"
51
+ ;;
52
+ esac
53
+ }
54
+
55
+ if [ -n "$kind" ]; then
56
+ rec="$(wt_require "$want")"
57
+ one "${rec%%$'\t'*}" "${rec##*$'\t'}"
58
+ exit 0
59
+ fi
60
+
61
+ printf ' %-34s %-50s %-22s %-5s %s\n' "BRANCH" "WORKTREE" "ADDRESS" "LIVE" "LAST RUN"
62
+ count=0
63
+ while IFS=$'\t' read -r p b; do
64
+ [ -n "$p" ] || continue
65
+ count=$(( count + 1 ))
66
+ slug="$(wt_slug "$b")"
67
+ shown="${p/#$HOME/~}"
68
+ if wt_is_main "$p"; then
69
+ printf ' %-34s %-50s %-22s %-5s %s\n' "$b (main checkout)" "$shown" "—" "—" "—"
70
+ continue
71
+ fi
72
+ port="$(wt_port_for "$slug")"
73
+ if tcp_up "$port"; then live="up"; else live="down"; fi
74
+ last="$(wt_verdict "$p")"
75
+ printf ' %-34s %-50s %-22s %-5s %s\n' "$b" "$shown" "http://localhost:$port" "$live" "${last:-—}"
76
+ done < <(wt_all)
77
+
78
+ [ "$count" -gt 0 ] || log " no checkouts found — is this a git repository?"
@@ -0,0 +1,84 @@
1
+ #!/usr/bin/env bash
2
+ # List worktrees whose work is already safely on a remote, and remove the ones
3
+ # you approve. This is the mode that keeps the worktree home from becoming tens
4
+ # of gigabytes.
5
+ #
6
+ # Only merged-or-gone branches that are clean, fully pushed, and not running are
7
+ # ever candidates. Nothing is removed without --yes.
8
+ #
9
+ # Usage: .sassywares/worktree/prune [--yes] [--version]
10
+ set -euo pipefail
11
+
12
+ SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
13
+ # shellcheck source=./_lib.sh
14
+ source "$SCRIPT_DIR/_lib.sh"
15
+
16
+ usage() {
17
+ cat <<'EOF'
18
+ Usage: .sassywares/worktree/prune [--yes]
19
+
20
+ Show every worktree that is merged into its upstream (or whose upstream is gone)
21
+ and safe to remove, then — with --yes — remove those and release their ports.
22
+ EOF
23
+ }
24
+
25
+ yes=0
26
+ while [ $# -gt 0 ]; do
27
+ case "$1" in
28
+ -h|--help) usage; exit 0 ;;
29
+ --version) printf '%s\n' "$WT_VERSION"; exit 0 ;;
30
+ --yes) yes=1 ;;
31
+ -*) die "unknown flag: $1 (try --help)" ;;
32
+ *) die "unexpected argument: $1 (try --help)" ;;
33
+ esac
34
+ shift
35
+ done
36
+
37
+ need_git
38
+
39
+ printf ' %-32s %-9s %-6s %-9s %s\n' "BRANCH" "UPSTREAM" "DIRTY" "UNPUSHED" "ACTION"
40
+ n_candidates=0
41
+ n_removed=0
42
+ while IFS=$'\t' read -r p b; do
43
+ [ -n "$p" ] || continue
44
+ wt_is_main "$p" && continue
45
+ slug="$(wt_slug "$b")"
46
+ state="$(wt_upstream_state "$p")"
47
+ if wt_dirty "$p"; then dirty="yes"; else dirty="no"; fi
48
+ unpushed="$(wt_unpushed "$p")"
49
+ port="$(wt_port_for "$slug")"
50
+ if tcp_up "$port"; then live="yes"; else live="no"; fi
51
+
52
+ action=""
53
+ if [ "$state" = "unmerged" ]; then
54
+ action="skipped — unmerged"
55
+ elif [ "$dirty" = "yes" ]; then
56
+ action="skipped — dirty"
57
+ elif [ "$unpushed" != "0" ]; then
58
+ action="skipped — $unpushed unpushed"
59
+ elif [ "$live" = "yes" ]; then
60
+ action="skipped — running on :$port"
61
+ else
62
+ action="removable"
63
+ n_candidates=$(( n_candidates + 1 ))
64
+ fi
65
+
66
+ printf ' %-32s %-9s %-6s %-9s %s\n' "$b" "$state" "$dirty" "$unpushed" "$action"
67
+
68
+ if [ "$yes" -eq 1 ] && [ "$action" = "removable" ]; then
69
+ hooks="$(wt_hook before_remove "$b")"
70
+ if [ -n "$hooks" ]; then
71
+ warn skipped "$b has a before_remove hook — run remove <$slug> so it runs"
72
+ continue
73
+ fi
74
+ git worktree remove "$p" && wt_release "$port" "$slug" && n_removed=$(( n_removed + 1 ))
75
+ fi
76
+ done < <(wt_all)
77
+
78
+ if [ "$yes" -eq 1 ]; then
79
+ ok pruned "$n_removed removed, $(( n_candidates - n_removed )) left"
80
+ elif [ "$n_candidates" -gt 0 ]; then
81
+ hint "re-run with --yes to remove the $n_candidates removable worktree(s)"
82
+ else
83
+ ok pruned "nothing to remove"
84
+ fi
@@ -0,0 +1,85 @@
1
+ #!/usr/bin/env bash
2
+ # Remove a worktree, after proving nothing would be lost.
3
+ #
4
+ # Refuses: the main checkout, a dirty tree, commits that are on no remote, and a
5
+ # preview that is still running. A declared `hooks.worktree.before_remove` runs
6
+ # first — the script cannot dispatch a skill, so it fails closed until the caller
7
+ # says the hook has been dispatched.
8
+ #
9
+ # Usage: .sassywares/worktree/remove <slug|branch> [--hook-ok] [--force]
10
+ # .sassywares/worktree/remove --version
11
+ set -euo pipefail
12
+
13
+ SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
14
+ # shellcheck source=./_lib.sh
15
+ source "$SCRIPT_DIR/_lib.sh"
16
+
17
+ usage() {
18
+ cat <<'EOF'
19
+ Usage: .sassywares/worktree/remove <slug|branch> [--hook-ok] [--force]
20
+
21
+ --hook-ok the project's hooks.worktree.before_remove has already been
22
+ dispatched — required when one is declared (exit 3 otherwise)
23
+ --force skip the dirty-tree and unpushed-commit refusals. Never skips the
24
+ main checkout, the preview check, or the hook handshake.
25
+ EOF
26
+ }
27
+
28
+ target=""
29
+ hook_ok=0
30
+ force=0
31
+ while [ $# -gt 0 ]; do
32
+ case "$1" in
33
+ -h|--help) usage; exit 0 ;;
34
+ --version) printf '%s\n' "$WT_VERSION"; exit 0 ;;
35
+ --hook-ok) hook_ok=1 ;;
36
+ --force) force=1 ;;
37
+ -*) die "unknown flag: $1 (try --help)" ;;
38
+ *) [ -z "$target" ] || die "one worktree at a time"; target="$1" ;;
39
+ esac
40
+ shift
41
+ done
42
+ [ -n "$target" ] || { usage >&2; exit 2; }
43
+
44
+ need_git
45
+ rec="$(wt_require "$target")"
46
+ path="${rec%%$'\t'*}"
47
+ branch="${rec##*$'\t'}"
48
+ slug="$(wt_slug "$branch")"
49
+
50
+ wt_is_main "$path" && die "that is the main checkout — it cannot be removed"
51
+
52
+ hooks="$(wt_hook before_remove "$branch")"
53
+ if [ -n "$hooks" ] && [ "$hook_ok" -eq 0 ]; then
54
+ while IFS= read -r n; do
55
+ [ -n "$n" ] || continue
56
+ log "require-hook $n"
57
+ done <<<"$hooks"
58
+ printf ' %-9s %s\n' "→" "dispatch it, then re-run with --hook-ok" >&2
59
+ exit 3
60
+ fi
61
+
62
+ port="$(wt_port_for "$slug")"
63
+ if tcp_up "$port"; then
64
+ die "something is still listening on :$port — stop <$slug> first"
65
+ fi
66
+
67
+ if [ "$force" -eq 0 ]; then
68
+ wt_dirty "$path" && die "not clean — $(git -C "$path" status --porcelain | wc -l | tr -d ' ') path(s) modified. Commit, discard, or --force."
69
+ n="$(wt_unpushed "$path")"
70
+ case "$n" in
71
+ 0) ;;
72
+ unknown) die "cannot tell whether this branch is pushed — inspect it, or --force" ;;
73
+ *) die "$n commit(s) on '$branch' are on no remote — push, or --force" ;;
74
+ esac
75
+ fi
76
+
77
+ if [ "$force" -eq 1 ]; then
78
+ git worktree remove --force "$path"
79
+ else
80
+ git worktree remove "$path"
81
+ fi
82
+ wt_release "$port" "$slug"
83
+
84
+ ok released ":$port"
85
+ ok removed "$path"
@@ -0,0 +1,61 @@
1
+ #!/usr/bin/env bash
2
+ # Stop whatever is listening on a worktree's port.
3
+ #
4
+ # By port, not by pid file: a preview that already died leaves nothing to
5
+ # believe, and a port that answers is the only proof that something is running.
6
+ #
7
+ # Usage: .sassywares/worktree/stop <slug|branch> [--version]
8
+ set -euo pipefail
9
+
10
+ SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
11
+ # shellcheck source=./_lib.sh
12
+ source "$SCRIPT_DIR/_lib.sh"
13
+
14
+ usage() {
15
+ cat <<'EOF'
16
+ Usage: .sassywares/worktree/stop <slug|branch>
17
+
18
+ Kill the processes listening on that worktree's port. Nothing listening is a
19
+ success with a note, so stopping twice is safe.
20
+ EOF
21
+ }
22
+
23
+ case "${1:-}" in
24
+ -h|--help) usage; exit 0 ;;
25
+ --version) printf '%s\n' "$WT_VERSION"; exit 0 ;;
26
+ "") usage >&2; exit 2 ;;
27
+ esac
28
+
29
+ need_git
30
+ rec="$(wt_require "$1")"
31
+ path="${rec%%$'\t'*}"
32
+ branch="${rec##*$'\t'}"
33
+ slug="$(wt_slug "$branch")"
34
+
35
+ wt_is_main "$path" && die "the main checkout has no derived port to stop"
36
+ port="$(wt_port_for "$slug")"
37
+
38
+ if ! tcp_up "$port"; then
39
+ ok status "nothing listening on :$port"
40
+ exit 0
41
+ fi
42
+
43
+ command -v lsof >/dev/null 2>&1 || die "lsof not found — stop the process on :$port yourself"
44
+
45
+ pids="$(lsof -ti "tcp:$port" 2>/dev/null | tr '\n' ' ' || true)"
46
+ [ -n "$pids" ] || die "something answers on :$port but lsof cannot name it — is it yours?"
47
+
48
+ n="$(printf '%s' "$pids" | wc -w | tr -d ' ')"
49
+ kill -TERM $pids 2>/dev/null || true
50
+ for _ in 1 2 3 4 5; do
51
+ sleep 1
52
+ tcp_up "$port" || break
53
+ done
54
+ if tcp_up "$port"; then
55
+ kill -KILL $pids 2>/dev/null || true
56
+ sleep 1
57
+ tcp_up "$port" && die ":$port still answers after SIGKILL (pids: $pids)"
58
+ ok stopped "$n process(es) on :$port (SIGKILL)"
59
+ else
60
+ ok stopped "$n process(es) on :$port"
61
+ fi
@@ -77,16 +77,30 @@ config. This applies to every token these skills forward, not just `branch`.
77
77
  "release" is not a neutral name.
78
78
  5. If the name already exists: reuse it when it descends from `start-point`;
79
79
  stop and ask when it has diverged.
80
- 6. `git checkout -b <name> <start-point>`. Uncommitted work comes along — say so
81
- in the gate summary if the tree was dirty.
82
- 7. Report the branch, the start point, and `pr-base`.
80
+ 6. **Create the branch — in a worktree when the project asked for one.**
81
+ With `worktrees.enabled: true` (per `worktree.md`), run the `sassy-worktree`
82
+ skill's `create` for this run instead of checking out in place: it cuts the
83
+ branch and the checkout together, so the branch can never be held twice, and
84
+ it prints the `WT_*` namespace the run inherits. Two things follow, and both
85
+ are the orchestrator's to carry:
86
+ - **Every step from here on works in `WT_PATH`,** and every delegated brief
87
+ names that absolute path. The main checkout is read-only for the rest of the
88
+ run — config, listing, nothing else.
89
+ - **A dirty tree does not come along,** unlike a checkout: the worktree starts
90
+ clean from `start-point`. Say in the gate summary that uncommitted work stays
91
+ behind, because that is a change in what a run means.
92
+ Otherwise `git checkout -b <name> <start-point>` here, and uncommitted work
93
+ comes along — say so in the gate summary if the tree was dirty.
94
+ 7. Report the branch, the start point, `pr-base`, and the checkout it landed in.
83
95
 
84
96
  ### `reuse`
85
97
 
86
- Report `head` and carry on. Do **not** re-cut because `commit.branch` is `new`:
98
+ Report `head` and the checkout you are in, and carry on. Do **not** re-cut because
99
+ `commit.branch` is `new`:
87
100
  a second phase, a resumed run, or a handed-off session is already standing on
88
101
  the branch the first one cut. That is the whole reason this is inferred rather
89
- than forced.
102
+ than forced. It is also what keeps a run inside its own worktree: it finds itself
103
+ on a non-base branch and reuses it rather than nesting another checkout.
90
104
 
91
105
  ### `commit-here`
92
106
 
@@ -79,6 +79,14 @@ hooks:
79
79
  push:
80
80
  "*":
81
81
  after_push: [] # commit.branch: current only
82
+ # worktree: # worktrees only; keyed by the checkout's branch
83
+ # "*":
84
+ # after_create: [] # derive .env, seed, copy the session
85
+ # before_remove: [] # drop the database, shut the device
86
+ worktrees:
87
+ enabled: false # true = a run may work in its own checkout
88
+ dir: ~/.sassywares/worktrees # parent of the per-repo folder; ~ is allowed here
89
+ ports: 3000-3099 # the range a checkout claims a port from
82
90
  dogfood:
83
91
  enabled: false # true = sassy-plan writes Mode: Auto QA rows
84
92
  recipe: .sassywares/dogfood/recipe.md # the procedure
@@ -109,6 +117,9 @@ dogfood:
109
117
  | `dogfood.recipe` | `.sassywares/dogfood/recipe.md` | The stored procedure `sassy-dogfood` executes. Its `Prove it:` step is the verdict |
110
118
  | `dogfood.reports` | `.sassywares/dogfood/reports` | Where a run writes its summary, step logs, and artifacts. Must be gitignored |
111
119
  | `dogfood.timeout` | `900` | Wall-clock for one run. A timeout is a failure, never a hang |
120
+ | `worktrees.enabled` | `false` | `true` lets a run work in its own checkout instead of this one. Needs `commit.branch: new` |
121
+ | `worktrees.dir` | `~/.sassywares/worktrees` | Parent of the per-repo worktree folder. The one path here that may be absolute or `~/` |
122
+ | `worktrees.ports` | `3000-3099` | The range a checkout claims its private port from |
112
123
 
113
124
  Paths are relative to the config's own directory, never to the cwd.
114
125
 
@@ -302,6 +313,13 @@ targets. `hooks.pr.staging` means *PRs whose source is staging*.
302
313
  | `before_merge` | `sassy-babysit` | the PR looks ready **and** this run will merge it |
303
314
  | `after_merge` | `sassy-babysit` | this run observed the PR merged |
304
315
  | `hooks.push.after_push` | `sassy-ship` | right after a successful push under `commit.branch: current` |
316
+ | `hooks.worktree.after_create` | `sassy-worktree` | just after a checkout exists, before anyone works in it |
317
+ | `hooks.worktree.before_remove` | `sassy-worktree` | before the checkout is deleted — drop its database, shut its device |
318
+
319
+ `hooks.worktree` has the same shape and resolution as the other two kinds, keyed
320
+ by the head branch the checkout holds. It needs `worktrees.enabled`; a shell
321
+ script cannot dispatch a skill, so `worktree:remove` fails closed (exit `3`,
322
+ `require-hook <name>`) until the caller has run it.
305
323
 
306
324
  `hooks.push` has the same shape and resolution as `hooks.pr`, but its key is the
307
325
  pushed head branch and its only point is `after_push`. It runs only under
@@ -376,6 +394,34 @@ partial failures explicitly. Never collapse it into one status.
376
394
  fan-out means one `sassy-babysit` run per PR; merging a fan-out needs an explicit
377
395
  per-PR say-so, because one switch would merge N PRs nobody re-read.
378
396
 
397
+ ## Worktrees
398
+
399
+ Parallel work in one repo: a checkout per branch, each with its own derived
400
+ namespace and port, so two runs never fight over a working tree.
401
+
402
+ ```yaml
403
+ worktrees:
404
+ enabled: true
405
+ dir: ~/.sassywares/worktrees
406
+ ports: 3000-3099
407
+ ```
408
+
409
+ Three keys, no commands. The scripts in `.sassywares/worktree/` own the
410
+ mechanics and `sassy-worktree` orchestrates them. `dir` is the one path in this
411
+ file that may be absolute or start with `~/` — it names machine-local state, not
412
+ something a teammate clones.
413
+
414
+ **Two conditions.**
415
+
416
+ - `enabled: true` needs `commit.branch: new`. Under `current` a run commits where
417
+ it stands and never cuts a branch, so nothing would ever create a worktree;
418
+ `--check` says so rather than leaving a switch that does nothing.
419
+ - It needs the `repo` topology. A `workspace` root and a `none` folder have no
420
+ git to cut a checkout from.
421
+
422
+ The namespace, the port claim, the two hooks, and every refusal are in
423
+ [`worktree.md`](worktree.md).
424
+
379
425
  ## Dogfood
380
426
 
381
427
  Agent QA: a stored procedure that proves a change works in the running product,
@@ -422,9 +468,15 @@ report layout, the verdict classes, and the lint are in
422
468
  - `git.repo` is `workspace`, `none`, or one existing remote name.
423
469
  - `git.remote` is required when `git.repo: workspace`; forbidden otherwise.
424
470
  `git.mirror_branch` and `repos` are workspace-only too.
425
- - `hooks` is allowed only with the four keys under `hooks.pr` and `after_push`
426
- under `hooks.push`, each a list of skill names that resolve to
427
- `.agents/skills/<name>/SKILL.md`.
471
+ - `hooks` is allowed only with the four points under `hooks.pr`, `after_push`
472
+ under `hooks.push`, and `after_create`/`before_remove` under `hooks.worktree`,
473
+ each a list of skill names that resolve to `.agents/skills/<name>/SKILL.md`.
474
+ - `worktrees.enabled` is `true` or `false`; `worktrees.ports` is `<from>-<to>`
475
+ inside 1–65535 with `<from>` no greater than `<to>`. A checkout must resolve
476
+ outside the working tree, must not hold a branch `base_map` names as a base,
477
+ and must not leave a port claimed by a worktree that no longer exists. An
478
+ `enabled: true` with no tooling installed, or with the wrong tooling version,
479
+ is drift.
428
480
  - `commit.branch` is `current` or `new`; `pr.*` are `true` or `false`. Write
429
481
  booleans as `true`/`false`, never `on`/`off` — bare `on`/`off` are YAML 1.1
430
482
  booleans and parse inconsistently.
@@ -444,7 +496,10 @@ a `drift:` line, exiting non-zero. When the suite is installed in project
444
496
  scope it also verifies the vendored pin offline: every `.agents/skills/<name>` folder whose name is a suite skill (a name in the suite's roster, `assets/roster` in sassy-setup, not merely `sassy-`-prefixed) is hashed with the `skills` CLI's own
445
497
  definition and compared to `computedHash` in `skills-lock.json`, the lock is
446
498
  checked against the installed set in both directions, and git-tracked state of
447
- the lock is reported. A stale, hand-edited, or half-installed suite is drift
448
- even when the config itself matches the tree. A user-scope install
449
- (`~/.agents/skills/`) has no pin to verify; the check notes it, and a suite
450
- found in neither scope is noted, not drift.
499
+ the lock is reported. Both lock eras count: the definition named by the lock's
500
+ `version` is tried first and the other second, so a pin written by an older
501
+ `skills` CLI reads as a match (with a note) rather than as drift — the
502
+ `skills` CLI changed its folder hash and still reads both. A stale, hand-edited,
503
+ or half-installed suite is drift even when the config itself matches the tree. A
504
+ user-scope install (`~/.agents/skills/`) has no pin to verify; the check notes
505
+ it, and a suite found in neither scope is noted, not drift.
@@ -48,13 +48,14 @@ promise that a check exists: an unfinished recipe degrades to Manual rows
48
48
  ```text
49
49
  .sassywares/
50
50
  ├── config.yaml
51
+ ├── .gitignore /session/ and /dogfood/reports/ — setup-owned
52
+ ├── session/ cookie jar, storage state, token — shared, never committed
51
53
  └── dogfood/
52
54
  ├── recipe.md the procedure — committed, reviewed like code
53
- ├── .gitignore one line: /reports/
54
55
  └── reports/ run output — never committed
55
56
  ```
56
57
 
57
- The `/reports/` line is setup-owned. `--check` reports it missing as drift,
58
+ The two ignore lines are setup-owned. `--check` reports it missing as drift,
58
59
  because a project that "helpfully" removes it commits screenshots by accident.
59
60
 
60
61
  ## Recipe format
@@ -69,6 +70,8 @@ copy `.env.example` → `.env` and fill `DOGFOOD_USER`, `DOGFOOD_PASS`.
69
70
 
70
71
  **Reset:** `bun run db:reset`; `rm -rf .sassywares/dogfood/reports/*`
71
72
 
73
+ **Preview:** `bun dev --port $PORT`, then open `$BASE_URL`
74
+
72
75
  ## catalog — a search returns matching products
73
76
 
74
77
  1. **Do** `bun run db:seed -- --fixtures catalog-small`
@@ -102,6 +105,11 @@ why the recipe outlives whatever tool the agent happens to have this quarter.
102
105
  it set up state and assert along the way; the prove step is the machine-readable
103
106
  answer. A section without one has no verdict.
104
107
 
108
+ **One `**Preview:**` line**, optional: how a human sees this checkout running. A
109
+ URL, a simulator name, a desktop app — whatever `sassy-worktree mode:preview`
110
+ should print once the app is up. Without one, the address is `$WT_BASE_URL`. It
111
+ is prose, like every other line here: no tool, no schema.
112
+
105
113
  **Rules.**
106
114
 
107
115
  - Ordered, numbered, **append-only**: add steps at the end of their section;
@@ -117,6 +125,31 @@ answer. A section without one has no verdict.
117
125
  - **No tool names.** Never "use Playwright" or "use the Chrome MCP". Say what to
118
126
  do and what to see, and let the run discover how.
119
127
 
128
+ ## Sessions, and a second checkout
129
+
130
+ Authentication is the one thing that cannot be standardized: a cookie jar, a
131
+ storage-state file, a bearer token, a client certificate, a device-code flow —
132
+ each project is different, and the mechanism is *discovered* rather than
133
+ configured. Two things follow, and they are all this file says about it:
134
+
135
+ - **Session material lives in `.sassywares/session/`**, gitignored with the same
136
+ setup-owned file as the reports. The suite never inspects what is in there. A
137
+ step that needs a credential names an env var or points at that directory and
138
+ never carries a value.
139
+ - **The procedure says how it is obtained and used** — in *Set up once*, in
140
+ `**Preview:**`, or in a plain section of its own. `mode:discover` writes it
141
+ once, after finding out what actually works, and `mode:run` or
142
+ `mode:preview` stops with an env-class report when the session is missing
143
+ rather than retrying against a login page.
144
+
145
+ A worktree gets a fresh, empty `session/`. When a project's provider registers a
146
+ single callback URL, a second checkout usually cannot log in on its own, so the
147
+ usual answer is to copy or link the main checkout's session in the
148
+ `after_create` hook. Worth writing down, because a **cookie** is host-scoped and
149
+ crosses ports freely while a **`localStorage`** session is origin-scoped, port
150
+ included, and has to be injected per origin — the difference looks like a broken
151
+ transplant when it is only the wrong mechanism.
152
+
120
153
  ## Reports
121
154
 
122
155
  ```text
@@ -188,7 +221,8 @@ lying switch.
188
221
  |----------|-------|
189
222
  | `dogfood:` block in the config | `sassy-setup` — the only skill that writes the config |
190
223
  | `.sassywares/dogfood/recipe.md` | `sassy-dogfood` (`mode:discover` authors and repairs it; a `mode:run` never edits it to pass) |
191
- | `.sassywares/dogfood/.gitignore` | `sassy-setup`, at the skeleton; never removed |
224
+ | `.sassywares/.gitignore` | `sassy-setup`; never removes a line |
225
+ | `.sassywares/session/` contents | the project — obtained and written by its own step or hook, never by this skill |
192
226
  | `reports/` | `sassy-dogfood`, always gitignored, pruned to ten |
193
227
  | `Mode: Auto` QA rows | `sassy-plan`, a section name per row |
194
228
  | Row results | `sassy-work`, from a passing report — never from an opinion |
@@ -202,7 +236,9 @@ Structural, never executed:
202
236
  - `recipe` exists when `enabled` is `true` — absent, it is "created by the first
203
237
  `sassy-dogfood` run", a note rather than drift.
204
238
  - `reports` is gitignored in a `repo` topology (`git check-ignore`), since a run
205
- once committed would be drift nobody catches later.
239
+ once committed would be drift nobody catches later. The same check covers
240
+ `.sassywares/session` whenever that directory exists — a committed session is a
241
+ credential leak, not a heavy history.
206
242
  - The recipe has at least one `## ` section, every section has a `**Prove it:**`
207
243
  line, every numbered step has an `**Expect**`, and the file carries no
208
244
  secret-shaped strings.