@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
|
@@ -30,13 +30,12 @@ For any other harness, give the skill name and its arguments and let the user in
|
|
|
30
30
|
|
|
31
31
|
## Temp files
|
|
32
32
|
|
|
33
|
-
Every file a skill or agent writes outside the repo goes under **`/tmp/sassywares/<
|
|
33
|
+
Every file a skill or agent writes outside the repo goes under **`/tmp/sassywares/<purpose>/`** — never loose in `/tmp`, never inside the working tree. One folder per purpose, shared by every harness: a handoff written in one harness has to be findable from another, which is the whole point of the file.
|
|
34
34
|
|
|
35
35
|
```bash
|
|
36
36
|
SW=/tmp/sassywares
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
for d in "$SW" "$SW/$HARNESS" "$DIR"; do [ -L "$d" ] && { echo "unsafe symlink: $d" >&2; exit 1; }; done
|
|
37
|
+
DIR="$SW/<purpose>"
|
|
38
|
+
[ -L "$SW" ] && { echo "unsafe symlink: $SW" >&2; exit 1; }
|
|
40
39
|
(umask 077; mkdir -p "$DIR")
|
|
41
40
|
[ -O "$SW" ] || { echo "not owned by you: $SW" >&2; exit 1; }
|
|
42
41
|
```
|
|
@@ -49,4 +48,14 @@ for d in "$SW" "$SW/$HARNESS" "$DIR"; do [ -L "$d" ] && { echo "unsafe symlink:
|
|
|
49
48
|
| PR bodies | `prs/` | `sassy-commit-push-pr` |
|
|
50
49
|
| Anything else — clones, captured output, drafts | `scratch/` | any skill or agent |
|
|
51
50
|
|
|
52
|
-
Name files so a run can find its own: a UTC timestamp
|
|
51
|
+
Name files so a run can find its own: a UTC timestamp, a short slug, and a short random suffix (`20261027T101500Z-fix-checkout-4f2a.txt`). The suffix keeps two harnesses writing in the same second apart, now that they share a folder. A clone or any temporary tree gets its own `mktemp -d` under `scratch/` for the same reason. Delete scratch you no longer need; `/tmp` clearing on reboot covers the rest. A new purpose gets a new row here, not a new top-level folder.
|
|
52
|
+
|
|
53
|
+
**Harness is not a path segment.** It is recorded inside the file where it still matters — a handoff carries `**Harness:**` so a reader knows which agent wrote it — and the resume command is generated for whoever is reading, not for the writer. When a file needs it:
|
|
54
|
+
|
|
55
|
+
```bash
|
|
56
|
+
HARNESS="${SASSY_HARNESS:-$(if [ -n "${CLAUDECODE:-}" ]; then echo claude; elif [ -n "${PI_CODING_AGENT:-}" ]; then echo pi; else echo other; fi)}"
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
## Durable state
|
|
60
|
+
|
|
61
|
+
`/tmp` is for files a run produces and forgets. Anything that must survive a reboot lives under **`~/.sassywares/<purpose>/`**: today that is `worktrees/`, whose checkouts carry uncommitted work (see `worktree.md`). Never put working state under `/tmp`, and never bury durable state inside a checkout — `/tmp` clearing is harmless for a handoff and fatal for a worktree.
|
|
@@ -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=""
|
|
@@ -182,6 +183,46 @@ list_items() {
|
|
|
182
183
|
| sed -E 's/^[[:space:]]+//; s/[[:space:]]+$//; s/^"//; s/"$//' | grep -v '^$' || true
|
|
183
184
|
}
|
|
184
185
|
|
|
186
|
+
# recipe_lint FILE — structural lint for a dogfood procedure. Prints one message
|
|
187
|
+
# per breach; the caller turns each into a drift line. Nothing is executed: a
|
|
188
|
+
# check run validates the shape of a procedure, it never runs the product.
|
|
189
|
+
recipe_lint() {
|
|
190
|
+
awk '
|
|
191
|
+
BEGIN { pending = 0; sec = ""; sname = ""; prove = 0; step = ""; incomment = 0 }
|
|
192
|
+
index($0, "<!--") { incomment = 1 }
|
|
193
|
+
incomment {
|
|
194
|
+
if (index($0, "-->")) incomment = 0
|
|
195
|
+
next
|
|
196
|
+
}
|
|
197
|
+
index($0, "**Prove it:**") { prove = 1; next }
|
|
198
|
+
/^## / {
|
|
199
|
+
if (sec != "" && !prove)
|
|
200
|
+
printf "section \"%s\" has no **Prove it:** line — it has no verdict\n", sname
|
|
201
|
+
if (pending)
|
|
202
|
+
printf "step %s-%s has no **Expect** line — an unstated check is a suggestion\n", sname, step
|
|
203
|
+
pending = 0; prove = 0
|
|
204
|
+
sec = $0; sub(/^## +/, "", sec)
|
|
205
|
+
split(sec, parts, /[ \t]+/); sname = parts[1]
|
|
206
|
+
next
|
|
207
|
+
}
|
|
208
|
+
/^[0-9]+\. / && index($0, "**Do**") {
|
|
209
|
+
if (pending)
|
|
210
|
+
printf "step %s-%s has no **Expect** line — an unstated check is a suggestion\n", sname, step
|
|
211
|
+
step = $0; sub(/\..*$/, "", step)
|
|
212
|
+
pending = 1; next
|
|
213
|
+
}
|
|
214
|
+
index($0, "**Expect**") { pending = 0; next }
|
|
215
|
+
END {
|
|
216
|
+
if (pending)
|
|
217
|
+
printf "step %s-%s has no **Expect** line — an unstated check is a suggestion\n", sname, step
|
|
218
|
+
if (sec != "" && !prove)
|
|
219
|
+
printf "section \"%s\" has no **Prove it:** line — it has no verdict\n", sname
|
|
220
|
+
if (sec == "")
|
|
221
|
+
printf "has no \"## <section>\" heading — there is nothing to prove\n"
|
|
222
|
+
}
|
|
223
|
+
' "$1"
|
|
224
|
+
}
|
|
225
|
+
|
|
185
226
|
# map_match SECTION HEAD — exact key, then the longest matching family, then "*".
|
|
186
227
|
# base_map uses it, and hooks use the same rule, so "which pattern applies" has
|
|
187
228
|
# exactly one answer in the whole config.
|
|
@@ -217,6 +258,7 @@ hook_points() {
|
|
|
217
258
|
case "$1" in
|
|
218
259
|
pr) printf '%s' "before_create after_create before_merge after_merge" ;;
|
|
219
260
|
push) printf '%s' "after_push" ;;
|
|
261
|
+
worktree) printf '%s' "after_create before_remove" ;;
|
|
220
262
|
esac
|
|
221
263
|
}
|
|
222
264
|
|
|
@@ -369,6 +411,8 @@ if (( CHECK )); then
|
|
|
369
411
|
repos.*) ;;
|
|
370
412
|
commit.branch) ;;
|
|
371
413
|
pr.babysit|pr.merge|pr.delete_branch) ;;
|
|
414
|
+
dogfood.enabled|dogfood.recipe|dogfood.reports|dogfood.timeout) ;;
|
|
415
|
+
worktrees.enabled|worktrees.dir|worktrees.ports) ;;
|
|
372
416
|
hooks.*) ;; # shape checked with the hooks
|
|
373
417
|
*) bad "unknown key '$key' — it is ignored, so the run uses the default" ;;
|
|
374
418
|
esac
|
|
@@ -520,7 +564,7 @@ if (( CHECK )); then
|
|
|
520
564
|
if [[ -n "$(yflat "hooks${US}pr${US}before_create")" ]]; then
|
|
521
565
|
bad "hooks.pr.<point> is now nested by head branch — write hooks.pr.\"*\".<point>"
|
|
522
566
|
fi
|
|
523
|
-
for kind in pr push; do
|
|
567
|
+
for kind in pr push worktree; do
|
|
524
568
|
while IFS= read -r pat; do
|
|
525
569
|
[[ -n "$pat" ]] || continue
|
|
526
570
|
case "$pat" in
|
|
@@ -550,8 +594,8 @@ if (( CHECK )); then
|
|
|
550
594
|
[[ -n "$depth" ]] || continue
|
|
551
595
|
kind="${hpath#hooks$US}"; kind="${kind%%$US*}"
|
|
552
596
|
case "$kind" in
|
|
553
|
-
pr|push) ;;
|
|
554
|
-
*) 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 ;;
|
|
555
599
|
esac
|
|
556
600
|
if [[ "$depth" != "4" ]]; then
|
|
557
601
|
bad "hooks entry '${hpath//$US/.}' is not head -> point -> list"
|
|
@@ -571,7 +615,7 @@ if (( CHECK )); then
|
|
|
571
615
|
if [[ "$TOPOLOGY" == "repo" ]]; then
|
|
572
616
|
note " base for '$HEAD_ARG': $(base_for_head "$HEAD_ARG")"
|
|
573
617
|
fi
|
|
574
|
-
for kind in pr push; do
|
|
618
|
+
for kind in pr push worktree; do
|
|
575
619
|
for point in $(hook_points "$kind"); do
|
|
576
620
|
resolved="$(hooks_for_head_point "$HEAD_ARG" "$point" "$kind")"
|
|
577
621
|
note " head '$HEAD_ARG' → $point: $( [[ -n "$resolved" ]] && printf '%s' "$resolved" || printf 'none' )"
|
|
@@ -650,6 +694,191 @@ if (( CHECK )); then
|
|
|
650
694
|
esac
|
|
651
695
|
fi
|
|
652
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
|
+
|
|
805
|
+
# Dogfood is a pointer and a switch, never commands: the recipe holds the
|
|
806
|
+
# procedure and its `Prove it:` step is the verdict. Everything below is
|
|
807
|
+
# structural. A check run never runs the product — a validator that boots an
|
|
808
|
+
# app is a validator nobody runs.
|
|
809
|
+
dg_enabled="$(block_value dogfood enabled || true)"
|
|
810
|
+
dg_recipe="$(block_value dogfood recipe || true)"
|
|
811
|
+
dg_reports="$(block_value dogfood reports || true)"
|
|
812
|
+
dg_timeout="$(block_value dogfood timeout || true)"
|
|
813
|
+
case "$dg_enabled" in
|
|
814
|
+
"") ;;
|
|
815
|
+
true|false) note " dogfood.enabled: $dg_enabled" ;;
|
|
816
|
+
*) bad "dogfood.enabled '$dg_enabled' must be true|false" ;;
|
|
817
|
+
esac
|
|
818
|
+
for dkey in recipe reports; do
|
|
819
|
+
case "$dkey" in
|
|
820
|
+
recipe) dpath="$dg_recipe" ;;
|
|
821
|
+
*) dpath="$dg_reports" ;;
|
|
822
|
+
esac
|
|
823
|
+
[[ -n "$dpath" ]] || continue
|
|
824
|
+
case "$dpath" in
|
|
825
|
+
/*|~*) bad "dogfood.$dkey '$dpath' is not relative to the config" ;;
|
|
826
|
+
.|./) bad "dogfood.$dkey is the project root itself" ;;
|
|
827
|
+
*) escapes_root "$dpath" && bad "dogfood.$dkey '$dpath' walks outside the project" ;;
|
|
828
|
+
esac
|
|
829
|
+
done
|
|
830
|
+
if [[ -n "$dg_timeout" ]]; then
|
|
831
|
+
case "$dg_timeout" in
|
|
832
|
+
*[!0-9]*) bad "dogfood.timeout '$dg_timeout' is not a positive integer" ;;
|
|
833
|
+
0) bad "dogfood.timeout is 0 — a procedure that can never finish" ;;
|
|
834
|
+
*) note " dogfood.timeout: ${dg_timeout}s" ;;
|
|
835
|
+
esac
|
|
836
|
+
fi
|
|
837
|
+
|
|
838
|
+
# Reports are logs and screenshots. A project that drops the ignore line
|
|
839
|
+
# commits them, and nobody notices until the history is heavy. Probed with a
|
|
840
|
+
# child path: `/reports/` names a directory, so git only matches it when the
|
|
841
|
+
# probe goes through the directory — and the directory may not exist yet.
|
|
842
|
+
if [[ "$TOPOLOGY" == "repo" && -n "$dg_reports" ]]; then
|
|
843
|
+
if git -C "$ROOT" check-ignore -q -- "$dg_reports/run.log" 2>/dev/null; then
|
|
844
|
+
note " dogfood.reports is gitignored"
|
|
845
|
+
else
|
|
846
|
+
bad "dogfood.reports '$dg_reports' is not gitignored — a run's logs and screenshots would be committed"
|
|
847
|
+
fi
|
|
848
|
+
fi
|
|
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
|
+
|
|
860
|
+
if [[ -n "$dg_recipe" ]]; then
|
|
861
|
+
if [[ ! -f "$ROOT/$dg_recipe" ]]; then
|
|
862
|
+
if [[ "$dg_enabled" == "true" ]]; then
|
|
863
|
+
# Enabled with no procedure is the one state that lies: a planner would
|
|
864
|
+
# write Auto rows against a check that does not exist.
|
|
865
|
+
bad "dogfood.recipe '$dg_recipe' does not exist — run sassy-dogfood mode:discover"
|
|
866
|
+
else
|
|
867
|
+
note " dogfood.recipe: $dg_recipe (written by the first sassy-dogfood run)"
|
|
868
|
+
fi
|
|
869
|
+
else
|
|
870
|
+
while IFS= read -r msg; do
|
|
871
|
+
[[ -n "$msg" ]] || continue
|
|
872
|
+
bad "dogfood.recipe $msg"
|
|
873
|
+
done < <(recipe_lint "$ROOT/$dg_recipe")
|
|
874
|
+
while IFS= read -r line0; do
|
|
875
|
+
[[ -n "$line0" ]] || continue
|
|
876
|
+
bad "dogfood.recipe has a secret-shaped string at line $line0 — env var names only, never a value"
|
|
877
|
+
done < <(grep -nE 'sk-[A-Za-z0-9_-]{16,}|ghp_[A-Za-z0-9]{20,}|AKIA[0-9A-Z]{16}|xox[baprs]-[A-Za-z0-9-]{10,}' "$ROOT/$dg_recipe" 2>/dev/null | cut -d: -f1)
|
|
878
|
+
note " dogfood.recipe: $dg_recipe"
|
|
879
|
+
fi
|
|
880
|
+
fi
|
|
881
|
+
|
|
653
882
|
# Hooks that cannot fire are a note, not drift: the config is legal, the step
|
|
654
883
|
# just never runs. hooks.push needs `current` in a single remote repo.
|
|
655
884
|
if [[ "$val" == "current" ]]; then
|
|
@@ -1052,3 +1281,31 @@ cat <<'EOF'
|
|
|
1052
1281
|
# "*":
|
|
1053
1282
|
# after_push: []
|
|
1054
1283
|
EOF
|
|
1284
|
+
cat <<'EOF'
|
|
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
|
+
|
|
1299
|
+
# --- Dogfood --------------------------------------------------------------
|
|
1300
|
+
# Agent QA: a stored procedure that proves a change works in the running
|
|
1301
|
+
# product. This block only points at it — commands live in the recipe, because
|
|
1302
|
+
# a copy here would duplicate the manifest and could not express step order.
|
|
1303
|
+
# The recipe ends each section in a `Prove it:` step whose exit code is the
|
|
1304
|
+
# verdict. enabled: true lets a plan write Mode: Auto QA rows, but only for a
|
|
1305
|
+
# section that actually has one.
|
|
1306
|
+
dogfood:
|
|
1307
|
+
EOF
|
|
1308
|
+
kv enabled false 42 '# true = plan writes Auto QA rows; false = all Manual'
|
|
1309
|
+
kv recipe .sassywares/dogfood/recipe.md 42 '# the procedure; sassy-dogfood writes it'
|
|
1310
|
+
kv reports .sassywares/dogfood/reports 42 '# run output; must stay gitignored'
|
|
1311
|
+
kv timeout 900 42 '# seconds for the whole procedure'
|
|
@@ -32,6 +32,8 @@ argument-hint: "<plan path or topic> [steps:compound,handbook,commit,pr,babysit]
|
|
|
32
32
|
2. **Compound (conditional).** If the work produced a qualifying learning, dispatch a `worker` whose task is: *load the `sassy-compound` skill and follow it with `mode:auto`* — with a compact learnings brief (the solved problems, root causes, and solutions taken from the cycle results, not from re-reading the tree). It always gets `mode:auto` because ship's own gate already covered the approval. Skip cleanly when nothing qualifies, and skip entirely when `knowledge.write` is `false`.
|
|
33
33
|
3. **Handbook (conditional).** If the feature is self-contained and independent enough that a teammate would benefit from a handover, dispatch a `worker` whose task is: *load the `sassy-handbook` skill and follow it* — with the plan path and topic. The worker reads the tree itself. Skip for small or tightly-coupled changes.
|
|
34
34
|
4. **Commit or snapshot.** After the review gate — never before it — the docs and any remaining code become durable.
|
|
35
|
+
|
|
36
|
+
**Before anything is persisted, check the plan's `Auto` QA rows.** If the plan carries any and one is not `Done` from a passing `sassy-dogfood` report, stop here: report the outstanding rows, the report path, and what it would take to prove them. Ship never commits, pushes, or opens a PR behind an unproven automated row, and never runs the recipe itself — proving is `sassy-work`'s step, and re-running it here would let a red row reach a commit by being retried instead of fixed. A brief and a plan with only `Manual` rows skip this entirely.
|
|
35
37
|
- **`git.repo` is a remote.** Dispatch a `worker`: *load the `sassy-commit` skill and follow it with `branch:current`*, naming that the commit must include the plan, any new solutions docs, the concepts file, `AGENTS.md`, and any handbook just written — resolved from `artifacts.*`, never hardcoded. The branch already exists: `sassy-work` or `sassy-lfg` cut it before the first change, so the docs belong on it with the phase commits. It returns the hash and subject.
|
|
36
38
|
|
|
37
39
|
**Ship never creates the branch.** Outside `commit.branch: current`, a head on a base branch with unpublished commits is a mis-run — `sassy-work` was supposed to cut before touching code. Ask the commit worker to return `state` and `unpublished` from the `sassy-setup` skill's `scripts/detect.sh --branch`, and stop and ask if they show a base with a non-zero count. Never relocate commits silently, never push to the base. Under `commit.branch: current` this check does not fire: unpublished commits on the head are simply pushed along with the close-out commit.
|
|
@@ -52,6 +54,7 @@ argument-hint: "<plan path or topic> [steps:compound,handbook,commit,pr,babysit]
|
|
|
52
54
|
|
|
53
55
|
| Rule | Requirement |
|
|
54
56
|
|------|-------------|
|
|
57
|
+
| Unproven rows stop the close-out | A plan's `Auto` QA row that is not `Done` from a passing dogfood report stops ship before anything is persisted. Ship never runs the recipe itself. |
|
|
55
58
|
| Review gate | `mode:manual` (default) presents the summary and waits before any write, commit, push, or PR. |
|
|
56
59
|
| No review | `mode:auto` runs the close-out with no approval gate. Never toggled by the skill. |
|
|
57
60
|
| All-or-nothing gate | In `mode:manual`, nothing is written until the gate is answered. |
|
|
@@ -10,7 +10,7 @@ argument-hint: "<plan path | brief> [phase:<n>] [branch:infer|current|new]"
|
|
|
10
10
|
|
|
11
11
|
# Sassy Work
|
|
12
12
|
|
|
13
|
-
**Outcome:** one phase run through `sassy-cycle`, findings fixed, then a single gate that carries both the code approval and the phase's
|
|
13
|
+
**Outcome:** one phase run through `sassy-cycle`, findings fixed, then a single gate that carries both the code approval and the phase's QA checklist (`Manual` rows from the user, `Auto` rows from a `sassy-dogfood` report), marked `Done` only when both pass, committed via `sassy-commit`; then a handoff that continues the **next** phase in a fresh session, or a `sassy-ship` close-out if this was the last phase.
|
|
14
14
|
|
|
15
15
|
**Brief input** runs one cycle, presents the code approval gate, commits, and **stops before shipping**.
|
|
16
16
|
|
|
@@ -31,13 +31,15 @@ If a plan path is given but the file does not exist, run `sassy-plan` first and
|
|
|
31
31
|
|
|
32
32
|
## QA gate
|
|
33
33
|
|
|
34
|
-
Read the plan's `**QA:**` line and its per-phase QA table. QA is
|
|
34
|
+
Read the plan's `**QA:**` line and its per-phase QA table. QA is part of the phase gate, not a separate track: a phase turns `Done` only when the code is approved **and** every QA row for that phase has passed.
|
|
35
35
|
|
|
36
|
-
|
|
37
|
-
- A row the user reports failing is a finding. It goes through a rework cycle (step 6) and the gate is presented again; a row that fails again after its rework is `Blocked` with the reason.
|
|
38
|
-
- Rows nobody has reported on stay `Pending`, and they keep the phase `In progress`. Never infer, batch-assume, or self-certify a pass.
|
|
36
|
+
Rows split by `Mode`, and the split decides who can settle them:
|
|
39
37
|
|
|
40
|
-
|
|
38
|
+
- **`Manual` rows are the user's.** The agent never ticks one it did not hear confirmed: it becomes `Done` only on the user's explicit confirmation in this conversation, with their note recorded.
|
|
39
|
+
- **`Auto` rows are proved, not opined.** Step 4 runs `sassy-dogfood` for the phase's sections before the gate, and a row becomes `Done` only from a report whose verdict is `pass`, with the run id in `Notes`. A failed run is a finding into a rework cycle; the row never becomes `Done` because the agent judged it fine.
|
|
40
|
+
- A row failing again after its rework is `Blocked` with the reason. Rows nobody has reported on stay `Pending`, and they keep the phase `In progress`. Never infer, batch-assume, or self-certify a pass.
|
|
41
|
+
|
|
42
|
+
A brief has no QA table, so its gate is code approval alone. Never invent, enable, or disable QA. A plan's `Auto` rows exist because the project enabled them: `dogfood.enabled` and a recipe section with a `Prove it:` step, per the `sassy-setup` skill's `references/dogfood.md`. Never edit the recipe to turn a red run green — propose the diff and ask.
|
|
41
43
|
|
|
42
44
|
## Phase gate
|
|
43
45
|
|
|
@@ -53,12 +55,14 @@ Always gate before committing. The cycle has already fixed and verified its find
|
|
|
53
55
|
- work brief = the phase's goal, work items, and "Done when" criteria
|
|
54
56
|
- intent reference = the plan path and phase
|
|
55
57
|
4. **Evaluate the phase.** On `Status: done`, the code is ready for the gate, but leave the phase `In progress` — both gates must pass before it closes. On `Status: blocked`, set it `Blocked` in the Phase tracking table and stop; a blocked phase is a real outcome and needs no approval.
|
|
56
|
-
|
|
58
|
+
|
|
59
|
+
**Then prove the `Auto` rows.** If the phase has any, run the `sassy-dogfood` skill in `mode:run` with each row's section named, before the gate and never after it. Record what each report said. A `failed` verdict is a finding, so the phase goes back through step 3's cycle with the failing step and the report's log tail as its findings, and this step runs again; a `class: env` verdict is not a finding — report that the toolchain is broken, leave the phase `In progress`, and stop. An `Auto` row with no report is `Pending`, never `Done`.
|
|
60
|
+
5. **Present the phase gate.** Report the phase, what changed, findings raised and resolved (with the fix passes it took), the simplifications applied, the validator grade, the reviewer summary, and the reviewer's suggestions as options the user may pick. Then give the QA checklist verbatim: each row's ID, check, `Mode`, and — for `Manual` — how to run it and what passing looks like, and for `Auto` — the dogfood verdict and run id, with unreported rows `Pending`. Ask for both decisions — code approval (or the changes wanted, including any suggestions picked) and the result per `Manual` row. Wait.
|
|
57
61
|
6. **Resolve the gate.** Three outcomes, nothing in between:
|
|
58
62
|
- **Code approved and every QA row passes** → go to step 7.
|
|
59
|
-
- **Code approved,
|
|
60
|
-
- **Changes requested, or any
|
|
61
|
-
7. **Commit the phase.** On both gates passing, first mark the phase's QA rows `Done` with the user's notes and the phase `Done` in the Phase tracking table, then persist according to `git.repo`:
|
|
63
|
+
- **Code approved, `Manual` rows still pending** → record that code is approved but leave the phase `In progress`, tick nothing, commit nothing, hand off nothing, and report that the phase is waiting on manual QA plus the command that resumes it.
|
|
64
|
+
- **Changes requested, or any row fails** → a rework cycle: load `sassy-cycle` with the requested changes and the failing rows as its findings, and the plan path and phase as the intent reference. On `done`, re-prove the `Auto` rows (step 4) and present the gate again from step 5; on `blocked`, mark the phase `Blocked` and stop. A QA row that fails again after its rework is `Blocked` with the reason and stops the phase. Change requests have no cap — each one is the user's call.
|
|
65
|
+
7. **Commit the phase.** On both gates passing, first mark the phase's QA rows `Done` — `Manual` rows with the user's notes, `Auto` rows with the verdict and run id from the report — and the phase `Done` in the Phase tracking table, then persist according to `git.repo`:
|
|
62
66
|
|
|
63
67
|
- **A remote** — dispatch a `worker` whose task is: *load the `sassy-commit` skill and follow it with `branch:current`*, naming that the commit must include the phase's code changes, the QA table results, and the now-updated Phase tracking table. It returns the hash and subject. The branch already exists: step 2 cut it, so committing on it is the point of `branch:current` here.
|
|
64
68
|
- **`workspace`** — dispatch a `worker` per affected repo to commit that repo's code on the run's shared branch, then run `.sassywares/workspace/snapshot` for the plan, QA results, and docs at the root. The gate's approval is the commit approval; the snapshot runs right after it and is never skipped. A missing or outdated `.sassywares/workspace/snapshot` is a blocker — say to run `sassy-setup`.
|
|
@@ -92,7 +96,7 @@ When the argument is not a plan path, it is one settled brief:
|
|
|
92
96
|
| Gate before commit and handoff | Do not commit, hand off, or close out until the user approves the code and the phase QA rows pass. |
|
|
93
97
|
| Commit per phase | Commit the phase, its QA results, and the plan update via `sassy-commit` before handoff or close-out. |
|
|
94
98
|
| Done needs both gates | Mark a phase `Done` only when the user approves the code and every QA row for that phase is `Done`, never before. |
|
|
95
|
-
| QA rows follow
|
|
99
|
+
| QA rows follow their mode | Tick a `Manual` row `Done` only from the user's explicit confirmation, and an `Auto` row only from a passing dogfood report; keep unreported rows `Pending`; a failed row is a finding for a rework cycle. |
|
|
96
100
|
| Send-backs are rework | Requested changes and failed QA rows go through `sassy-cycle` as findings — verified, two fix passes at most — never a direct edit. |
|
|
97
101
|
| No shipping on the brief path | The brief path commits and stops. Shipping is `sassy-ship` or `sassy-lfg`. |
|
|
98
102
|
|