@sassywares/skills 0.9.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.
- package/CONCEPTS.md +39 -4
- package/README.md +86 -6
- package/package.json +1 -1
- package/skills/sassy-commit/SKILL.md +1 -1
- package/skills/sassy-commit-push-pr/SKILL.md +1 -1
- package/skills/sassy-cycle/SKILL.md +1 -1
- package/skills/sassy-dogfood/SKILL.md +79 -0
- package/skills/sassy-handoff/SKILL.md +2 -1
- package/skills/sassy-handoff/references/read.md +1 -1
- package/skills/sassy-handoff/references/write.md +1 -1
- package/skills/sassy-lfg/SKILL.md +11 -8
- package/skills/sassy-plan/SKILL.md +6 -2
- package/skills/sassy-plan/references/plan-format.md +28 -8
- package/skills/sassy-scout/SKILL.md +4 -3
- package/skills/sassy-setup/SKILL.md +26 -9
- package/skills/sassy-setup/assets/dogfood-recipe.md +31 -0
- package/skills/sassy-setup/assets/roster +2 -0
- package/skills/sassy-setup/assets/worktree/_lib.sh +269 -0
- package/skills/sassy-setup/assets/worktree/create +104 -0
- package/skills/sassy-setup/assets/worktree/list +78 -0
- package/skills/sassy-setup/assets/worktree/prune +84 -0
- package/skills/sassy-setup/assets/worktree/remove +85 -0
- package/skills/sassy-setup/assets/worktree/stop +61 -0
- package/skills/sassy-setup/references/branching.md +19 -5
- package/skills/sassy-setup/references/config.md +104 -5
- package/skills/sassy-setup/references/dogfood.md +245 -0
- package/skills/sassy-setup/references/harness.md +14 -5
- package/skills/sassy-setup/references/worktree.md +151 -0
- package/skills/sassy-setup/scripts/detect.sh +261 -4
- package/skills/sassy-ship/SKILL.md +3 -0
- package/skills/sassy-work/SKILL.md +15 -11
- package/skills/sassy-worktree/SKILL.md +87 -0
|
@@ -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.
|
|
81
|
-
|
|
82
|
-
|
|
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
|
|
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,19 @@ 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
|
|
90
|
+
dogfood:
|
|
91
|
+
enabled: false # true = sassy-plan writes Mode: Auto QA rows
|
|
92
|
+
recipe: .sassywares/dogfood/recipe.md # the procedure
|
|
93
|
+
reports: .sassywares/dogfood/reports # run output, never committed
|
|
94
|
+
timeout: 900 # whole procedure, seconds
|
|
82
95
|
```
|
|
83
96
|
|
|
84
97
|
| Key | Default | Meaning |
|
|
@@ -100,6 +113,13 @@ hooks:
|
|
|
100
113
|
| `pr.delete_branch` | `false` | Delete the head branch once merged |
|
|
101
114
|
| `hooks.pr.<pattern>.<point>` | `[]` | Project steps, keyed by the PR's head branch |
|
|
102
115
|
| `hooks.push.<pattern>.after_push` | `[]` | Project steps after a push, keyed by the pushed branch (see Hooks) |
|
|
116
|
+
| `dogfood.enabled` | `false` | `true` lets a plan write automated QA rows. Absent means `false` — manual QA, today's behavior |
|
|
117
|
+
| `dogfood.recipe` | `.sassywares/dogfood/recipe.md` | The stored procedure `sassy-dogfood` executes. Its `Prove it:` step is the verdict |
|
|
118
|
+
| `dogfood.reports` | `.sassywares/dogfood/reports` | Where a run writes its summary, step logs, and artifacts. Must be gitignored |
|
|
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 |
|
|
103
123
|
|
|
104
124
|
Paths are relative to the config's own directory, never to the cwd.
|
|
105
125
|
|
|
@@ -293,6 +313,13 @@ targets. `hooks.pr.staging` means *PRs whose source is staging*.
|
|
|
293
313
|
| `before_merge` | `sassy-babysit` | the PR looks ready **and** this run will merge it |
|
|
294
314
|
| `after_merge` | `sassy-babysit` | this run observed the PR merged |
|
|
295
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.
|
|
296
323
|
|
|
297
324
|
`hooks.push` has the same shape and resolution as `hooks.pr`, but its key is the
|
|
298
325
|
pushed head branch and its only point is `after_push`. It runs only under
|
|
@@ -367,12 +394,72 @@ partial failures explicitly. Never collapse it into one status.
|
|
|
367
394
|
fan-out means one `sassy-babysit` run per PR; merging a fan-out needs an explicit
|
|
368
395
|
per-PR say-so, because one switch would merge N PRs nobody re-read.
|
|
369
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
|
+
|
|
425
|
+
## Dogfood
|
|
426
|
+
|
|
427
|
+
Agent QA: a stored procedure that proves a change works in the running product,
|
|
428
|
+
not just in the diff. The block is a **pointer and a switch**, deliberately —
|
|
429
|
+
four keys, no commands.
|
|
430
|
+
|
|
431
|
+
```yaml
|
|
432
|
+
dogfood:
|
|
433
|
+
enabled: true
|
|
434
|
+
recipe: .sassywares/dogfood/recipe.md
|
|
435
|
+
reports: .sassywares/dogfood/reports
|
|
436
|
+
timeout: 900
|
|
437
|
+
```
|
|
438
|
+
|
|
439
|
+
Commands live in the recipe, not here. A copied command duplicates
|
|
440
|
+
`package.json` or a `Makefile` and drifts from it silently, and a single command
|
|
441
|
+
cannot express what makes dogfooding project-specific anyway: which order, which
|
|
442
|
+
prerequisites, and what counts as success between the steps. The recipe holds
|
|
443
|
+
the order, an `Expect` per step, and one `Prove it:` step whose exit code is the
|
|
444
|
+
verdict.
|
|
445
|
+
|
|
446
|
+
**Two gates.** An `Auto` QA row needs `enabled: true` **and** a recipe section
|
|
447
|
+
with a `Prove it:` step. One without the other keeps the row `Manual`, which is
|
|
448
|
+
how an unfinished recipe degrades safely instead of producing a green gate that
|
|
449
|
+
proves nothing.
|
|
450
|
+
|
|
451
|
+
`enabled` is written explicitly by `sassy-setup`, never inferred: no block means
|
|
452
|
+
`false`, which is today's behavior — every QA row is manual. The format, the
|
|
453
|
+
report layout, the verdict classes, and the lint are in
|
|
454
|
+
[`dogfood.md`](dogfood.md).
|
|
455
|
+
|
|
370
456
|
## Fail closed vs soft
|
|
371
457
|
|
|
372
458
|
- **Fail closed** (stop, say why): an unusable `artifacts.*` or `git.*` value.
|
|
373
459
|
A typo must not silently write docs into the wrong place.
|
|
374
|
-
- **Soft** (fall back, say so): an unusable `commit
|
|
375
|
-
`knowledge.read` path that is missing.
|
|
460
|
+
- **Soft** (fall back, say so): an unusable `commit.*`, `pr.*`, or `dogfood.*`
|
|
461
|
+
value, and any `knowledge.read` path that is missing. A `dogfood` failure
|
|
462
|
+
never fails a run: it only means QA rows stay manual.
|
|
376
463
|
|
|
377
464
|
## Validation rules
|
|
378
465
|
|
|
@@ -381,14 +468,26 @@ per-PR say-so, because one switch would merge N PRs nobody re-read.
|
|
|
381
468
|
- `git.repo` is `workspace`, `none`, or one existing remote name.
|
|
382
469
|
- `git.remote` is required when `git.repo: workspace`; forbidden otherwise.
|
|
383
470
|
`git.mirror_branch` and `repos` are workspace-only too.
|
|
384
|
-
- `hooks` is allowed only with the four
|
|
385
|
-
under `hooks.push`,
|
|
386
|
-
`.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.
|
|
387
480
|
- `commit.branch` is `current` or `new`; `pr.*` are `true` or `false`. Write
|
|
388
481
|
booleans as `true`/`false`, never `on`/`off` — bare `on`/`off` are YAML 1.1
|
|
389
482
|
booleans and parse inconsistently.
|
|
390
483
|
- `knowledge.read` is an inline list (`read: [a, b]`). A block list is not read
|
|
391
484
|
by the config reader, so it would silently scout nothing.
|
|
485
|
+
- `dogfood.*` is exactly four keys; `enabled` is `true` or `false`, `timeout`
|
|
486
|
+
is a positive integer, and both paths are repo-relative and inside the
|
|
487
|
+
project. `reports` must be gitignored in a `repo` topology, and the recipe is
|
|
488
|
+
structurally linted — a section without a `Prove it:` line, a step without an
|
|
489
|
+
`Expect`, or a secret-shaped string is drift. See
|
|
490
|
+
[`dogfood.md`](dogfood.md).
|
|
392
491
|
- An unknown key is an error, not a fallback: a typo parses, is ignored, and the
|
|
393
492
|
run uses a default this project never chose.
|
|
394
493
|
|
|
@@ -0,0 +1,245 @@
|
|
|
1
|
+
# Dogfood
|
|
2
|
+
|
|
3
|
+
Agent QA: a stored procedure that proves a change actually works in the running
|
|
4
|
+
product, not just in the diff. `sassy-dogfood` executes it, `sassy-plan` writes
|
|
5
|
+
automated QA rows against it, `sassy-work` gates on it, and `sassy-ship` refuses
|
|
6
|
+
to open a PR with it red.
|
|
7
|
+
|
|
8
|
+
The reference is deliberately tooling-agnostic. Nothing here names a browser, a
|
|
9
|
+
driver, or an MCP server: a recipe is steps and expectations, and whatever the
|
|
10
|
+
harness has connected at run time is what satisfies them.
|
|
11
|
+
|
|
12
|
+
## Why a procedure, and not a command
|
|
13
|
+
|
|
14
|
+
A single command cannot say "seed first, boot the simulator, wait for the health
|
|
15
|
+
endpoint, then re-auth if the token is stale" — and that ordering is the entire
|
|
16
|
+
project-specific knowledge. It is also what every fresh agent otherwise
|
|
17
|
+
re-derives, differently, every time.
|
|
18
|
+
|
|
19
|
+
So the config stores a **pointer and a switch**, never commands. Commands live in
|
|
20
|
+
the recipe because only the recipe can express their order, their prerequisites,
|
|
21
|
+
and what counts as success between them. A command copied into the config would
|
|
22
|
+
duplicate `package.json` or a `Makefile` and drift from it silently.
|
|
23
|
+
|
|
24
|
+
## Config
|
|
25
|
+
|
|
26
|
+
```yaml
|
|
27
|
+
dogfood:
|
|
28
|
+
enabled: false # false = every QA row is Manual
|
|
29
|
+
recipe: .sassywares/dogfood/recipe.md # the procedure
|
|
30
|
+
reports: .sassywares/dogfood/reports # run logs and artifacts; never committed
|
|
31
|
+
timeout: 900 # whole procedure, seconds
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
| Key | Default | Meaning |
|
|
35
|
+
|-----|---------|---------|
|
|
36
|
+
| `dogfood.enabled` | `false` | `true` lets `sassy-plan` write `Mode: Auto` QA rows. `false` forbids them. Absent means `false`: no block is today's behavior — manual QA |
|
|
37
|
+
| `dogfood.recipe` | `.sassywares/dogfood/recipe.md` | The procedure. Relative to the config. Point it at an existing runbook only if that runbook is already in this format |
|
|
38
|
+
| `dogfood.reports` | `.sassywares/dogfood/reports` | Where a run writes its summary, step logs, and artifacts. Must be gitignored |
|
|
39
|
+
| `dogfood.timeout` | `900` | Wall-clock for one whole run. A timeout is a failure, never a hang |
|
|
40
|
+
|
|
41
|
+
`enabled` is written explicitly by `sassy-setup`, never left to inference, so a
|
|
42
|
+
teammate reads the decision instead of guessing at it. `enabled: true` is not a
|
|
43
|
+
promise that a check exists: an unfinished recipe degrades to Manual rows
|
|
44
|
+
(see *Two gates*), which is why the switch alone can never make a gate lie.
|
|
45
|
+
|
|
46
|
+
## Files
|
|
47
|
+
|
|
48
|
+
```text
|
|
49
|
+
.sassywares/
|
|
50
|
+
├── config.yaml
|
|
51
|
+
├── .gitignore /session/ and /dogfood/reports/ — setup-owned
|
|
52
|
+
├── session/ cookie jar, storage state, token — shared, never committed
|
|
53
|
+
└── dogfood/
|
|
54
|
+
├── recipe.md the procedure — committed, reviewed like code
|
|
55
|
+
└── reports/ run output — never committed
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
The two ignore lines are setup-owned. `--check` reports it missing as drift,
|
|
59
|
+
because a project that "helpfully" removes it commits screenshots by accident.
|
|
60
|
+
|
|
61
|
+
## Recipe format
|
|
62
|
+
|
|
63
|
+
```markdown
|
|
64
|
+
# Dogfood — <project>
|
|
65
|
+
|
|
66
|
+
**Never** production. Local or staging only.
|
|
67
|
+
|
|
68
|
+
**Set up once:** `bun install`; `docker compose up -d db`;
|
|
69
|
+
copy `.env.example` → `.env` and fill `DOGFOOD_USER`, `DOGFOOD_PASS`.
|
|
70
|
+
|
|
71
|
+
**Reset:** `bun run db:reset`; `rm -rf .sassywares/dogfood/reports/*`
|
|
72
|
+
|
|
73
|
+
**Preview:** `bun dev --port $PORT`, then open `$BASE_URL`
|
|
74
|
+
|
|
75
|
+
## catalog — a search returns matching products
|
|
76
|
+
|
|
77
|
+
1. **Do** `bun run db:seed -- --fixtures catalog-small`
|
|
78
|
+
**Expect** `seeded 12 products`
|
|
79
|
+
2. **Do** `bun dev &`, then poll `curl -fsS localhost:3000/healthz`
|
|
80
|
+
**Expect** `ok` within 60s
|
|
81
|
+
3. **Do** open `/catalog` and sign in as `DOGFOOD_USER`
|
|
82
|
+
**Expect** the header shows that email; a 401 means the token env var is stale
|
|
83
|
+
4. **Do** search "wool socks", open the first result
|
|
84
|
+
**Expect** the detail page titles match the search term
|
|
85
|
+
5. **Do** `bun run e2e -- --grep catalog`
|
|
86
|
+
**Expect** exit 0
|
|
87
|
+
|
|
88
|
+
**Prove it:** step 5 — its exit code is the verdict.
|
|
89
|
+
|
|
90
|
+
## auth — an expired session re-authenticates
|
|
91
|
+
|
|
92
|
+
1. …
|
|
93
|
+
**Prove it:** step 2.
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
**A section is one testable area** — `catalog`, `auth`, `mobile`, `api`. A QA row
|
|
97
|
+
names a section; it never restates a step.
|
|
98
|
+
|
|
99
|
+
**Every step has `Do` and `Expect`.** Without an `Expect` it is a suggestion, not
|
|
100
|
+
a check, and `--check` reports it as drift. `Do` is a command *or* an
|
|
101
|
+
instruction ("open `/catalog`, sign in as `DOGFOOD_USER`") — the instruction is
|
|
102
|
+
why the recipe outlives whatever tool the agent happens to have this quarter.
|
|
103
|
+
|
|
104
|
+
**One `Prove it:` per section**, and its exit code is the verdict. Steps before
|
|
105
|
+
it set up state and assert along the way; the prove step is the machine-readable
|
|
106
|
+
answer. A section without one has no verdict.
|
|
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
|
+
|
|
113
|
+
**Rules.**
|
|
114
|
+
|
|
115
|
+
- Ordered, numbered, **append-only**: add steps at the end of their section;
|
|
116
|
+
never reorder or renumber. A removal carries its one-line why in the commit.
|
|
117
|
+
- **Env var names only.** Never a credential, a token, or a session cookie. If a
|
|
118
|
+
step needs one, it names the variable and the project's own gitignored env file
|
|
119
|
+
holds the value.
|
|
120
|
+
- **Local or staging only.** A recipe that names production is a bug.
|
|
121
|
+
- **The happy path plus its checks.** Debris ("metro holds 8081") is a learning,
|
|
122
|
+
not a step: it goes to `artifacts.solutions` via `sassy-compound`, which
|
|
123
|
+
scouting already reads. This is what keeps a busy project's recipe at forty
|
|
124
|
+
lines instead of becoming a wiki.
|
|
125
|
+
- **No tool names.** Never "use Playwright" or "use the Chrome MCP". Say what to
|
|
126
|
+
do and what to see, and let the run discover how.
|
|
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
|
+
|
|
153
|
+
## Reports
|
|
154
|
+
|
|
155
|
+
```text
|
|
156
|
+
.sassywares/dogfood/reports/
|
|
157
|
+
└── 20260514-093107/ run id: YYYYMMDD-HHMMSS, sorts chronologically
|
|
158
|
+
├── summary.md the only file read whole
|
|
159
|
+
├── steps/
|
|
160
|
+
│ ├── catalog-01.log <section>-<NN> — a file name is a citation
|
|
161
|
+
│ └── catalog-05.log
|
|
162
|
+
└── artifacts/
|
|
163
|
+
├── catalog-03-header.png
|
|
164
|
+
└── catalog-05-trace.zip
|
|
165
|
+
```
|
|
166
|
+
|
|
167
|
+
```markdown
|
|
168
|
+
# Dogfood run 20260514-093107
|
|
169
|
+
|
|
170
|
+
**status:** failed
|
|
171
|
+
**class:** code
|
|
172
|
+
**section:** catalog
|
|
173
|
+
**recipe:** .sassywares/dogfood/recipe.md @ a91f3c2
|
|
174
|
+
**started:** 09:31:07 **finished:** 09:33:41
|
|
175
|
+
|
|
176
|
+
| Step | Expect | Result |
|
|
177
|
+
|---|---|---|
|
|
178
|
+
| catalog-1 | `seeded 12 products` | pass |
|
|
179
|
+
| catalog-5 | exit 0 | **fail, exit 1** |
|
|
180
|
+
|
|
181
|
+
**Prove it:** catalog-5 → exit 1. 3 of 41 e2e specs failed.
|
|
182
|
+
**Artifacts:** `artifacts/catalog-05-report.json`, `artifacts/catalog-05-trace.zip`
|
|
183
|
+
**Next:** re-run from catalog-4, not catalog-1.
|
|
184
|
+
```
|
|
185
|
+
|
|
186
|
+
`summary.md` is created at the start with `status: running` and finalized on exit.
|
|
187
|
+
A killed session therefore leaves an accurate breadcrumb, and the next one reads
|
|
188
|
+
one file to know where it stopped.
|
|
189
|
+
|
|
190
|
+
- **`status`** — `running` | `pass` | `failed`.
|
|
191
|
+
- **`class`** — `code` (a finding for the rework cycle) | `env` (the toolchain is
|
|
192
|
+
broken: a missing dependency, exit 75 or 127 — report and park, never loop) |
|
|
193
|
+
`recipe` (the procedure itself is stale: a renamed script, a dead URL, a step
|
|
194
|
+
that cannot be followed). `recipe` is the rot signal: the run proposes a
|
|
195
|
+
one-line diff and never quietly improvises around it.
|
|
196
|
+
- **One log per executed step**, capped head-and-tail (~64 KB) with a
|
|
197
|
+
`[truncated N lines]` marker, so a runaway loop cannot fill the disk.
|
|
198
|
+
- **Redaction happens before the write.** Every value of an env var the recipe
|
|
199
|
+
names is masked, plus a token-shape pass. A recipe that "stores creds" must not
|
|
200
|
+
leave them in a log an agent will later paste into a report.
|
|
201
|
+
- **The agent never reads a log whole.** It reads `summary.md`, then the last
|
|
202
|
+
~600 characters of the failing step. An agent that reads a 40k-line log dies of
|
|
203
|
+
a missing semicolon.
|
|
204
|
+
- **Reports are pruned to the ten most recent** at the start of each run. Nothing
|
|
205
|
+
is committed here, so nothing must survive. The durable record is the QA row's
|
|
206
|
+
note — `catalog-5 exit 1, run 20260514-093107` — which never depends on a path
|
|
207
|
+
that will be deleted.
|
|
208
|
+
- **Never committed.** Not the logs, the artifacts, or the traces.
|
|
209
|
+
|
|
210
|
+
## Two gates: `enabled` and the recipe
|
|
211
|
+
|
|
212
|
+
An Auto QA row needs **both** `dogfood.enabled: true` **and** a section whose
|
|
213
|
+
recipe carries a `Prove it:` step. One without the other means the row stays
|
|
214
|
+
`Manual`. That is how an unfinished recipe degrades safely instead of producing a
|
|
215
|
+
green gate that proves nothing — there is no third state in the config and no
|
|
216
|
+
lying switch.
|
|
217
|
+
|
|
218
|
+
## Who writes what
|
|
219
|
+
|
|
220
|
+
| Artifact | Owner |
|
|
221
|
+
|----------|-------|
|
|
222
|
+
| `dogfood:` block in the config | `sassy-setup` — the only skill that writes the config |
|
|
223
|
+
| `.sassywares/dogfood/recipe.md` | `sassy-dogfood` (`mode:discover` authors and repairs it; a `mode:run` never edits it to pass) |
|
|
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 |
|
|
226
|
+
| `reports/` | `sassy-dogfood`, always gitignored, pruned to ten |
|
|
227
|
+
| `Mode: Auto` QA rows | `sassy-plan`, a section name per row |
|
|
228
|
+
| Row results | `sassy-work`, from a passing report — never from an opinion |
|
|
229
|
+
|
|
230
|
+
## `--check` lint
|
|
231
|
+
|
|
232
|
+
Structural, never executed:
|
|
233
|
+
|
|
234
|
+
- `enabled` is `true|false`; `timeout` is a positive integer; both paths are
|
|
235
|
+
relative and stay inside the project.
|
|
236
|
+
- `recipe` exists when `enabled` is `true` — absent, it is "created by the first
|
|
237
|
+
`sassy-dogfood` run", a note rather than drift.
|
|
238
|
+
- `reports` is gitignored in a `repo` topology (`git check-ignore`), since a run
|
|
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.
|
|
242
|
+
- The recipe has at least one `## ` section, every section has a `**Prove it:**`
|
|
243
|
+
line, every numbered step has an `**Expect**`, and the file carries no
|
|
244
|
+
secret-shaped strings.
|
|
245
|
+
- `dogfood.*` is a known key block; anything else in it is an unknown key.
|