@sassywares/skills 0.8.0 → 0.10.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.
@@ -52,6 +52,24 @@ START="${ROOT_ARG:-$PWD}"
52
52
  START="$(cd "$START" && pwd -P)"
53
53
 
54
54
  SKILL_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
55
+
56
+ # The suite roster ships with sassy-setup (assets/roster, one skill name per
57
+ # line). Only these names are "ours"; a project skill that merely starts with
58
+ # `sassy-` is the project's. Never derived from sibling folders: in project scope
59
+ # those are the project's own skills. Empty/missing falls back to the prefix.
60
+ SUITE_ROSTER=""
61
+ if [[ -s "$SKILL_DIR/assets/roster" ]]; then
62
+ while IFS= read -r _n || [[ -n "$_n" ]]; do
63
+ _n="${_n//[$'\r\t ']/}"
64
+ [[ -n "$_n" ]] && SUITE_ROSTER="${SUITE_ROSTER:+$SUITE_ROSTER,}$_n"
65
+ done < "$SKILL_DIR/assets/roster"
66
+ fi
67
+ is_suite_skill() {
68
+ if [[ -n "$SUITE_ROSTER" ]]; then
69
+ case ",$SUITE_ROSTER," in *",$1,"*) return 0 ;; *) return 1 ;; esac
70
+ fi
71
+ [[ "$1" == sassy-* ]]
72
+ }
55
73
  ASSET_SNAPSHOT="$SKILL_DIR/assets/snapshot"
56
74
  ASSET_WORKSPACE="$SKILL_DIR/assets/workspace"
57
75
 
@@ -164,6 +182,46 @@ list_items() {
164
182
  | sed -E 's/^[[:space:]]+//; s/[[:space:]]+$//; s/^"//; s/"$//' | grep -v '^$' || true
165
183
  }
166
184
 
185
+ # recipe_lint FILE — structural lint for a dogfood procedure. Prints one message
186
+ # per breach; the caller turns each into a drift line. Nothing is executed: a
187
+ # check run validates the shape of a procedure, it never runs the product.
188
+ recipe_lint() {
189
+ awk '
190
+ BEGIN { pending = 0; sec = ""; sname = ""; prove = 0; step = ""; incomment = 0 }
191
+ index($0, "<!--") { incomment = 1 }
192
+ incomment {
193
+ if (index($0, "-->")) incomment = 0
194
+ next
195
+ }
196
+ index($0, "**Prove it:**") { prove = 1; next }
197
+ /^## / {
198
+ if (sec != "" && !prove)
199
+ printf "section \"%s\" has no **Prove it:** line — it has no verdict\n", sname
200
+ if (pending)
201
+ printf "step %s-%s has no **Expect** line — an unstated check is a suggestion\n", sname, step
202
+ pending = 0; prove = 0
203
+ sec = $0; sub(/^## +/, "", sec)
204
+ split(sec, parts, /[ \t]+/); sname = parts[1]
205
+ next
206
+ }
207
+ /^[0-9]+\. / && index($0, "**Do**") {
208
+ if (pending)
209
+ printf "step %s-%s has no **Expect** line — an unstated check is a suggestion\n", sname, step
210
+ step = $0; sub(/\..*$/, "", step)
211
+ pending = 1; next
212
+ }
213
+ index($0, "**Expect**") { pending = 0; next }
214
+ END {
215
+ if (pending)
216
+ printf "step %s-%s has no **Expect** line — an unstated check is a suggestion\n", sname, step
217
+ if (sec != "" && !prove)
218
+ printf "section \"%s\" has no **Prove it:** line — it has no verdict\n", sname
219
+ if (sec == "")
220
+ printf "has no \"## <section>\" heading — there is nothing to prove\n"
221
+ }
222
+ ' "$1"
223
+ }
224
+
167
225
  # map_match SECTION HEAD — exact key, then the longest matching family, then "*".
168
226
  # base_map uses it, and hooks use the same rule, so "which pattern applies" has
169
227
  # exactly one answer in the whole config.
@@ -189,15 +247,35 @@ map_match() {
189
247
 
190
248
  base_for_head() { map_match base_map "$1"; }
191
249
 
250
+ # hook_patterns [KIND] — the head patterns declared under hooks.<kind> (pr by default).
192
251
  hook_patterns() {
193
- yaml_flat | awk -F'\t' -v us="$US" '{n=split($1,a,us); if (n==4 && a[1]=="hooks" && a[2]=="pr") print a[3]}' | sort -u
252
+ yaml_flat | awk -F'\t' -v us="$US" -v k="${1:-pr}" '{n=split($1,a,us); if (n==4 && a[1]=="hooks" && a[2]==k) print a[3]}' | sort -u
194
253
  }
195
254
 
196
- # hooks_for_head_point HEAD POINT — exact head, then the longest matching
255
+ # hook_points KIND — the single source of point names; empty for an unknown kind.
256
+ hook_points() {
257
+ case "$1" in
258
+ pr) printf '%s' "before_create after_create before_merge after_merge" ;;
259
+ push) printf '%s' "after_push" ;;
260
+ esac
261
+ }
262
+
263
+ # hooks_declared KIND — succeeds when hooks.<kind> names at least one skill.
264
+ hooks_declared() {
265
+ local kind="$1" pat point
266
+ while IFS= read -r pat; do
267
+ for point in $(hook_points "$kind"); do
268
+ [[ -n "$(list_items "$(yflat "hooks${US}${kind}${US}${pat}${US}${point}")")" ]] && return 0
269
+ done
270
+ done < <(hook_patterns "$kind")
271
+ return 1
272
+ }
273
+
274
+ # hooks_for_head_point HEAD POINT [KIND] — exact head, then the longest matching
197
275
  # family, then "*". A pattern that declares no entry for this point inherits.
198
276
  hooks_for_head_point() {
199
- local head="$1" point="$2" pat stem best="" bestlen=0 v
200
- v="$(yflat "hooks${US}pr${US}${head}${US}${point}")"
277
+ local head="$1" point="$2" kind="${3:-pr}" pat stem best="" bestlen=0 v
278
+ v="$(yflat "hooks${US}${kind}${US}${head}${US}${point}")"
201
279
  [[ -n "$v" ]] && { printf '%s' "$v"; return; }
202
280
  while IFS= read -r pat; do
203
281
  case "$pat" in *"*") ;; *) continue ;; esac
@@ -206,12 +284,12 @@ hooks_for_head_point() {
206
284
  if [[ "$head" == "$stem"* ]] && (( ${#stem} > bestlen )); then
207
285
  best="$pat"; bestlen=${#stem}
208
286
  fi
209
- done < <(hook_patterns)
287
+ done < <(hook_patterns "$kind")
210
288
  if [[ -n "$best" ]]; then
211
- v="$(yflat "hooks${US}pr${US}${best}${US}${point}")"
289
+ v="$(yflat "hooks${US}${kind}${US}${best}${US}${point}")"
212
290
  [[ -n "$v" ]] && { printf '%s' "$v"; return; }
213
291
  fi
214
- printf '%s' "$(yflat "hooks${US}pr${US}*${US}${point}")"
292
+ printf '%s' "$(yflat "hooks${US}${kind}${US}*${US}${point}")"
215
293
  }
216
294
 
217
295
  detect_base() {
@@ -331,7 +409,8 @@ if (( CHECK )); then
331
409
  repos.*) ;;
332
410
  commit.branch) ;;
333
411
  pr.babysit|pr.merge|pr.delete_branch) ;;
334
- hooks.pr.*) ;; # shape checked with the hooks
412
+ dogfood.enabled|dogfood.recipe|dogfood.reports|dogfood.timeout) ;;
413
+ hooks.*) ;; # shape checked with the hooks
335
414
  *) bad "unknown key '$key' — it is ignored, so the run uses the default" ;;
336
415
  esac
337
416
  done < <(yaml_flat "$CONFIG")
@@ -482,39 +561,48 @@ if (( CHECK )); then
482
561
  if [[ -n "$(yflat "hooks${US}pr${US}before_create")" ]]; then
483
562
  bad "hooks.pr.<point> is now nested by head branch — write hooks.pr.\"*\".<point>"
484
563
  fi
485
- while IFS= read -r pat; do
486
- [[ -n "$pat" ]] || continue
487
- case "$pat" in
488
- "*") ;;
489
- *"*") [[ "${pat%\*}" != *"*" ]] || bad "hook pattern '$pat': only one trailing * is allowed" ;;
490
- esac
491
- for point in before_create after_create before_merge after_merge; do
492
- val="$(yflat "hooks${US}pr${US}${pat}${US}${point}")"
493
- [[ -n "$val" ]] || continue
494
- while IFS= read -r entry; do
495
- [[ -n "$entry" ]] || continue
496
- name="${entry%% *}"
497
- case "$name" in
498
- sassy-*) bad "hooks.$pat.$point: '$name' is one of our skills — hooks are project skills only" ;;
499
- *) hook_skill_path "$name" >/dev/null 2>&1 \
500
- || bad "hooks.$pat.$point: '$name' not found at .agents/skills/$name/SKILL.md" ;;
501
- esac
502
- done < <(list_items "$val")
503
- done
504
- done < <(hook_patterns)
564
+ for kind in pr push; do
565
+ while IFS= read -r pat; do
566
+ [[ -n "$pat" ]] || continue
567
+ case "$pat" in
568
+ "*") ;;
569
+ *"*") [[ "${pat%\*}" != *"*" ]] || bad "hook pattern '$pat': only one trailing * is allowed" ;;
570
+ esac
571
+ for point in $(hook_points "$kind"); do
572
+ val="$(yflat "hooks${US}${kind}${US}${pat}${US}${point}")"
573
+ [[ -n "$val" ]] || continue
574
+ while IFS= read -r entry; do
575
+ [[ -n "$entry" ]] || continue
576
+ name="${entry%% *}"
577
+ if is_suite_skill "$name"; then
578
+ bad "hooks.$kind.$pat.$point: '$name' is one of our skills — hooks are project skills only"
579
+ else
580
+ hook_skill_path "$name" >/dev/null 2>&1 \
581
+ || bad "hooks.$kind.$pat.$point: '$name' not found at .agents/skills/$name/SKILL.md"
582
+ fi
583
+ done < <(list_items "$val")
584
+ done
585
+ done < <(hook_patterns "$kind")
586
+ done
505
587
 
506
- # `hooks.pr.<head>.<point>` is the only shape, and the four points are the
507
- # only moments a skill asks for. A fifth point name is a step that never fires.
588
+ # `hooks.<kind>.<head>.<point>` is the only shape. hooks.pr has four points and
589
+ # hooks.push has one; any other point name is a step that never fires.
508
590
  while IFS=$'\t' read -r depth hpath; do
509
591
  [[ -n "$depth" ]] || continue
592
+ kind="${hpath#hooks$US}"; kind="${kind%%$US*}"
593
+ case "$kind" in
594
+ pr|push) ;;
595
+ *) bad "hooks kind '$kind' is not one of pr|push"; continue ;;
596
+ esac
510
597
  if [[ "$depth" != "4" ]]; then
511
598
  bad "hooks entry '${hpath//$US/.}' is not head -> point -> list"
512
599
  continue
513
600
  fi
514
601
  point="${hpath##*$US}"
515
- case "$point" in
516
- before_create|after_create|before_merge|after_merge) ;;
517
- *) bad "hooks point '$point' is not one of before_create|after_create|before_merge|after_merge" ;;
602
+ points="$(hook_points "$kind")"
603
+ case " $points " in
604
+ *" $point "*) ;;
605
+ *) bad "hooks.$kind point '$point' is not one of ${points// /|}" ;;
518
606
  esac
519
607
  done < <(yaml_flat "$CONFIG" \
520
608
  | awk -F'\t' -v us="$US" '{n=split($1,a,us); if (n>=2 && a[1]=="hooks") print n "\t" $1}')
@@ -524,9 +612,11 @@ if (( CHECK )); then
524
612
  if [[ "$TOPOLOGY" == "repo" ]]; then
525
613
  note " base for '$HEAD_ARG': $(base_for_head "$HEAD_ARG")"
526
614
  fi
527
- for point in before_create after_create before_merge after_merge; do
528
- resolved="$(hooks_for_head_point "$HEAD_ARG" "$point")"
529
- note " head '$HEAD_ARG' → $point: $( [[ -n "$resolved" ]] && printf '%s' "$resolved" || printf 'none' )"
615
+ for kind in pr push; do
616
+ for point in $(hook_points "$kind"); do
617
+ resolved="$(hooks_for_head_point "$HEAD_ARG" "$point" "$kind")"
618
+ note " head '$HEAD_ARG' → $point: $( [[ -n "$resolved" ]] && printf '%s' "$resolved" || printf 'none' )"
619
+ done
530
620
  done
531
621
  fi
532
622
 
@@ -601,16 +691,97 @@ if (( CHECK )); then
601
691
  esac
602
692
  fi
603
693
 
694
+ # Dogfood is a pointer and a switch, never commands: the recipe holds the
695
+ # procedure and its `Prove it:` step is the verdict. Everything below is
696
+ # structural. A check run never runs the product — a validator that boots an
697
+ # app is a validator nobody runs.
698
+ dg_enabled="$(block_value dogfood enabled || true)"
699
+ dg_recipe="$(block_value dogfood recipe || true)"
700
+ dg_reports="$(block_value dogfood reports || true)"
701
+ dg_timeout="$(block_value dogfood timeout || true)"
702
+ case "$dg_enabled" in
703
+ "") ;;
704
+ true|false) note " dogfood.enabled: $dg_enabled" ;;
705
+ *) bad "dogfood.enabled '$dg_enabled' must be true|false" ;;
706
+ esac
707
+ for dkey in recipe reports; do
708
+ case "$dkey" in
709
+ recipe) dpath="$dg_recipe" ;;
710
+ *) dpath="$dg_reports" ;;
711
+ esac
712
+ [[ -n "$dpath" ]] || continue
713
+ case "$dpath" in
714
+ /*|~*) bad "dogfood.$dkey '$dpath' is not relative to the config" ;;
715
+ .|./) bad "dogfood.$dkey is the project root itself" ;;
716
+ *) escapes_root "$dpath" && bad "dogfood.$dkey '$dpath' walks outside the project" ;;
717
+ esac
718
+ done
719
+ if [[ -n "$dg_timeout" ]]; then
720
+ case "$dg_timeout" in
721
+ *[!0-9]*) bad "dogfood.timeout '$dg_timeout' is not a positive integer" ;;
722
+ 0) bad "dogfood.timeout is 0 — a procedure that can never finish" ;;
723
+ *) note " dogfood.timeout: ${dg_timeout}s" ;;
724
+ esac
725
+ fi
726
+
727
+ # Reports are logs and screenshots. A project that drops the ignore line
728
+ # commits them, and nobody notices until the history is heavy. Probed with a
729
+ # child path: `/reports/` names a directory, so git only matches it when the
730
+ # probe goes through the directory — and the directory may not exist yet.
731
+ if [[ "$TOPOLOGY" == "repo" && -n "$dg_reports" ]]; then
732
+ if git -C "$ROOT" check-ignore -q -- "$dg_reports/run.log" 2>/dev/null; then
733
+ note " dogfood.reports is gitignored"
734
+ else
735
+ bad "dogfood.reports '$dg_reports' is not gitignored — a run's logs and screenshots would be committed"
736
+ fi
737
+ fi
738
+
739
+ if [[ -n "$dg_recipe" ]]; then
740
+ if [[ ! -f "$ROOT/$dg_recipe" ]]; then
741
+ if [[ "$dg_enabled" == "true" ]]; then
742
+ # Enabled with no procedure is the one state that lies: a planner would
743
+ # write Auto rows against a check that does not exist.
744
+ bad "dogfood.recipe '$dg_recipe' does not exist — run sassy-dogfood mode:discover"
745
+ else
746
+ note " dogfood.recipe: $dg_recipe (written by the first sassy-dogfood run)"
747
+ fi
748
+ else
749
+ while IFS= read -r msg; do
750
+ [[ -n "$msg" ]] || continue
751
+ bad "dogfood.recipe $msg"
752
+ done < <(recipe_lint "$ROOT/$dg_recipe")
753
+ while IFS= read -r line0; do
754
+ [[ -n "$line0" ]] || continue
755
+ bad "dogfood.recipe has a secret-shaped string at line $line0 — env var names only, never a value"
756
+ 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)
757
+ note " dogfood.recipe: $dg_recipe"
758
+ fi
759
+ fi
760
+
761
+ # Hooks that cannot fire are a note, not drift: the config is legal, the step
762
+ # just never runs. hooks.push needs `current` in a single remote repo.
763
+ if [[ "$val" == "current" ]]; then
764
+ if hooks_declared pr; then
765
+ note " hooks.pr entries are declared but commit.branch is current — no PR, so they never run"
766
+ fi
767
+ if hooks_declared push && [[ "$configured_repo" == "workspace" || "$configured_repo" == "none" ]]; then
768
+ note " hooks.push entries are declared but git.repo is '$configured_repo' — they never run"
769
+ fi
770
+ elif hooks_declared push; then
771
+ note " hooks.push entries are declared but commit.branch is not current — they never run"
772
+ fi
773
+
604
774
  # The pin. A config can match the tree perfectly while the vendored suite is
605
775
  # stale, edited, or half-installed, and every skill downstream then runs
606
776
  # something other than what the lock says. Offline, no network.
777
+ [[ -n "$SUITE_ROSTER" ]] || note " suite roster not found — falling back to the sassy-* name prefix"
607
778
  if command -v node >/dev/null 2>&1; then
608
779
  while IFS=$'\t' read -r kind msg; do
609
780
  case "$kind" in
610
781
  drift) bad "$msg" ;;
611
782
  note) note " $msg" ;;
612
783
  esac
613
- done < <(node "$SKILL_DIR/scripts/lockcheck.mjs" --root "$ROOT" 2>/dev/null || true)
784
+ done < <(node "$SKILL_DIR/scripts/lockcheck.mjs" --root "$ROOT" --roster "$SUITE_ROSTER" 2>/dev/null || true)
614
785
  else
615
786
  note " node not found — the vendored pin is unverified (the skills CLI needs node)"
616
787
  fi
@@ -949,7 +1120,7 @@ cat <<'EOF'
949
1120
 
950
1121
  # --- Commit ---------------------------------------------------------------
951
1122
  # current: commit on the checked-out branch, even on a base branch, then push
952
- # it to its upstream. No PR: pr.* and hooks.pr are ignored.
1123
+ # it to its upstream. No PR: pr.* and hooks.pr are ignored; hooks.push runs.
953
1124
  # new: never commit on a base branch — sassy-work, sassy-lfg, and sassy-debug
954
1125
  # cut a branch at the start of the run and stay on it.
955
1126
  commit:
@@ -966,7 +1137,8 @@ kv delete_branch false 24 '# true | false — delete the head branch once merged
966
1137
  cat <<'EOF'
967
1138
 
968
1139
  # --- Hooks ----------------------------------------------------------------
969
- # Project steps injected into the PR pipeline, keyed by the HEAD branch — the
1140
+ # Project steps injected into the PR pipeline, or after a push under
1141
+ # commit.branch: current, keyed by the HEAD branch — the
970
1142
  # branch the PR comes from, never the one it targets. `"*"` is the default;
971
1143
  # a name overrides per point, and `release/*` matches a family. Each entry is
972
1144
  # `<skill> <args…>`, resolved at .agents/skills/<name>/SKILL.md; args are passed
@@ -984,4 +1156,22 @@ cat <<'EOF'
984
1156
  # before_create: []
985
1157
  # release/*: # a family of heads
986
1158
  # after_merge: [notify mode:auto]
1159
+ # push: # commit.branch: current only; keyed by the pushed branch
1160
+ # "*":
1161
+ # after_push: []
1162
+ EOF
1163
+ cat <<'EOF'
1164
+
1165
+ # --- Dogfood --------------------------------------------------------------
1166
+ # Agent QA: a stored procedure that proves a change works in the running
1167
+ # product. This block only points at it — commands live in the recipe, because
1168
+ # a copy here would duplicate the manifest and could not express step order.
1169
+ # The recipe ends each section in a `Prove it:` step whose exit code is the
1170
+ # verdict. enabled: true lets a plan write Mode: Auto QA rows, but only for a
1171
+ # section that actually has one.
1172
+ dogfood:
987
1173
  EOF
1174
+ kv enabled false 42 '# true = plan writes Auto QA rows; false = all Manual'
1175
+ kv recipe .sassywares/dogfood/recipe.md 42 '# the procedure; sassy-dogfood writes it'
1176
+ kv reports .sassywares/dogfood/reports 42 '# run output; must stay gitignored'
1177
+ kv timeout 900 42 '# seconds for the whole procedure'
@@ -1,5 +1,5 @@
1
1
  #!/usr/bin/env node
2
- // Verify the vendored sassy-* folders against skills-lock.json.
2
+ // Verify the vendored suite skill folders against skills-lock.json.
3
3
  //
4
4
  // The suite installs in one of two scopes, like the agents: the project
5
5
  // (vendored into .agents/skills and pinned in skills-lock.json) or the user
@@ -12,7 +12,9 @@
12
12
  // path — so "identical to the pin" is a fact this script asserts, not a claim
13
13
  // the agent has to make in prose.
14
14
  //
15
- // Usage: lockcheck.mjs [--root DIR]
15
+ // Usage: lockcheck.mjs [--root DIR] [--roster a,b,c]
16
+ // A suite skill is a name in --roster (assets/roster in sassy-setup); without
17
+ // one, any name starting with `sassy-`.
16
18
  // Prints "<drift|note>\t<message>" per finding and always exits 0: the caller
17
19
  // owns the verdict and the formatting.
18
20
 
@@ -23,12 +25,17 @@ import { homedir } from "node:os";
23
25
  import { join, relative } from "node:path";
24
26
 
25
27
  const SUITE = "sassywares/sassy-skills";
26
- const SASSY = /^sassy-/;
28
+ let roster = null; // suite skill names (--roster a,b,c); null falls back to the sassy- prefix
29
+ const isSuite = (name) => (roster ? roster.has(name) : /^sassy-/.test(name));
27
30
 
28
31
  const argv = process.argv.slice(2);
29
32
  let root = process.cwd();
30
33
  for (let i = 0; i < argv.length; i += 1) {
31
- if (argv[i] === "--root") {
34
+ if (argv[i] === "--roster") {
35
+ const names = (argv[i + 1] ?? "").split(",").filter(Boolean);
36
+ roster = names.length > 0 ? new Set(names) : null;
37
+ i += 1;
38
+ } else if (argv[i] === "--root") {
32
39
  root = argv[i + 1];
33
40
  i += 1;
34
41
  }
@@ -65,12 +72,12 @@ async function folderHash(dir) {
65
72
  return hash.digest("hex");
66
73
  }
67
74
 
68
- // sassy-* skills in a skills directory. Follows symlinks: a user scope may link
75
+ // suite skills in a skills directory. Follows symlinks: a user scope may link
69
76
  // each skill to a working copy rather than holding the files.
70
77
  function suiteIn(dir) {
71
78
  if (!existsSync(dir)) return [];
72
79
  return readdirSync(dir).filter(
73
- (name) => SASSY.test(name) && existsSync(join(dir, name, "SKILL.md")),
80
+ (name) => isSuite(name) && existsSync(join(dir, name, "SKILL.md")),
74
81
  );
75
82
  }
76
83
 
@@ -89,7 +96,7 @@ async function main() {
89
96
  return;
90
97
  }
91
98
  if (!existsSync(lockPath)) {
92
- drift(`sassy-* folders in .agents/skills but no skills-lock.json — re-pin with npx skills add ${SUITE}`);
99
+ drift(`suite skill folders in .agents/skills but no skills-lock.json — re-pin with npx skills add ${SUITE}`);
93
100
  return;
94
101
  }
95
102
 
@@ -102,10 +109,10 @@ async function main() {
102
109
  }
103
110
 
104
111
  const pinned = Object.entries(lock.skills ?? {}).filter(
105
- ([name, entry]) => SASSY.test(name) || String(entry.source ?? "").includes("sassy-skills"),
112
+ ([name]) => isSuite(name),
106
113
  );
107
114
  if (pinned.length === 0) {
108
- drift(`skills-lock.json pins no sassy-* skill — install with npx skills add ${SUITE}`);
115
+ drift(`skills-lock.json pins no suite skill — install with npx skills add ${SUITE}`);
109
116
  return;
110
117
  }
111
118
 
@@ -116,7 +123,7 @@ async function main() {
116
123
  }
117
124
 
118
125
  const installed = (await readdir(suite, { withFileTypes: true }))
119
- .filter((entry) => entry.isDirectory() && SASSY.test(entry.name))
126
+ .filter((entry) => entry.isDirectory() && isSuite(entry.name))
120
127
  .map((entry) => entry.name);
121
128
  const installedNames = new Set(installed);
122
129
  const pinnedNames = new Set(pinned.map(([name]) => name));
@@ -141,7 +148,7 @@ async function main() {
141
148
  }
142
149
 
143
150
  if (matched > 0) {
144
- note(`${matched}/${pinned.length} sassy-* skill folders match skills-lock.json byte for byte`);
151
+ note(`${matched}/${pinned.length} suite skill folders match skills-lock.json byte for byte`);
145
152
  }
146
153
 
147
154
  const sources = [...new Set(pinned.map(([, entry]) => String(entry.source ?? "unknown")))];
@@ -18,7 +18,7 @@ argument-hint: "<plan path or topic> [steps:compound,handbook,commit,pr,babysit]
18
18
 
19
19
  **Config.** Resolve `.sassywares/config.yaml` (nearest, walking up) per the `sassy-setup` skill's `references/config.md`. Precedence: explicit token > session instruction > config > skill default. `pr.babysit`, `pr.merge`, and `pr.delete_branch` seed the close-out; `git.repo` decides whether this run commits, snapshots, or refuses; `hooks.pr.*` adds project steps to the PR pipeline. `commit.branch: current` replaces the PR pipeline with a push; see Current policy below.
20
20
 
21
- **Current policy.** `commit.branch: current` in the config is an explicit opt-in to work landing where it stands. Under it the close-out commits on the checked-out branch and pushes it to its upstream, base branch included, and skips the PR entirely: no `sassy-commit-push-pr`, no `hooks.pr.*`, no babysit, no merge. A user-typed `branch:current` token keeps its usual meaning (commit on the checked-out branch) and does not suppress the PR; neither does the `branch:current` ship forwards to `sassy-commit`.
21
+ **Current policy.** `commit.branch: current` in the config is an explicit opt-in to work landing where it stands. Under it the close-out commits on the checked-out branch and pushes it to its upstream, base branch included, and skips the PR entirely: no `sassy-commit-push-pr`, no `hooks.pr.*`, no babysit, no merge. `hooks.push.after_push` still runs. A user-typed `branch:current` token keeps its usual meaning (commit on the checked-out branch) and does not suppress the PR; neither does the `branch:current` ship forwards to `sassy-commit`.
22
22
 
23
23
  **How to obtain it.** Before the gate, in both `mode:manual` and `mode:auto`, dispatch one dedicated probe `worker`: run the `sassy-setup` skill's `scripts/detect.sh --branch` with **no `--policy`** and return `configured`, `head`, and the upstream (or that none is set). `configured: current` means the current policy applies. Never take the policy from the commit worker: it runs with the forwarded `branch:current` and always reports `policy: current`.
24
24
 
@@ -28,16 +28,20 @@ argument-hint: "<plan path or topic> [steps:compound,handbook,commit,pr,babysit]
28
28
 
29
29
  ## Steps (in order)
30
30
 
31
- 1. **Review gate.** In `mode:manual` only: present a compact shipping summary — the plan or topic, the changes from the cycle results, the docs the close-out expects to write, the branch/PR target, the babysit options, for a goal slice the `goal.md` change (slice → `Shipped`) and that babysit will not merge, and **the hooks resolved for this run's head — point, skill, and args — or that none are declared** — and wait. Under `commit.branch: current`, state instead "commit + push to `<head>`, no PR" and that no PR, babysit, merge, or `hooks.pr.*` (`before_create`, `after_create`, `before_merge`, `after_merge`) will run. In `mode:auto`, skip this gate.
31
+ 1. **Review gate.** In `mode:manual` only: present a compact shipping summary — the plan or topic, the changes from the cycle results, the docs the close-out expects to write, the branch/PR target, the babysit options, for a goal slice the `goal.md` change (slice → `Shipped`) and that babysit will not merge, and **the hooks resolved for this run's head — point, skill, and args — or that none are declared** — and wait. Under `commit.branch: current`, state instead "commit + push to `<head>`, no PR", that no PR, babysit, merge, or `hooks.pr.*` (`before_create`, `after_create`, `before_merge`, `after_merge`) will run, and **the `hooks.push.after_push` entries resolved for `<head>` — skill and args — or that none are declared**. In `mode:auto`, skip this gate.
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.
38
40
  - **`git.repo: workspace`.** Commit code inside each affected repo on the run's shared branch — cut once at the start of the run, `branch:current` from then on — then run `.sassywares/workspace/snapshot`. The snapshot is the workspace's commit and it runs every time, right after approval. A missing or outdated `.sassywares/workspace/snapshot` is a blocker: report it and say to run `sassy-setup`.
39
41
  - **`git.repo: none`.** No commit exists here. Report that the work is not persisted and stop.
40
- 5. **PR, or push.** Under `commit.branch: current` in a `remote` repo, skip the PR: dispatch a `worker` to push the head to its upstream with `git push` (upstream set), or `git push -u <remote> <head>` when the head has no upstream — never force. On a non-fast-forward rejection, stop and report; fetching or rebasing is a stop-and-ask. Return the pushed hash and `<head>`, then end the close-out (step 6 is skipped too). In a workspace, push each affected repo in `repos` order, stop at the first rejection, and return a per-repo table (pushed / rejected / not attempted). The final report says "no PR — hooks.pr.* skipped", in `mode:auto` too. Otherwise, in a `remote` repo, dispatch a `worker`: *load the `sassy-commit-push-pr` skill and follow it with `branch:current` and `babysit:off`, forwarding `base:<branch>` when the caller supplied one* (step 6 owns the babysit). It returns the PR URL. In a `workspace`, open one PR per affected repo — the same branch name in each, `--base` from that repo's own `base_map` when it carries a `.sassywares/config.yaml`, else its `repos` entry — and return a table. A touched repo missing from `repos`, or a base that cannot be resolved, is a stop-and-ask, never a guess. `none` opens nothing.
42
+ 5. **PR, or push.** Under `commit.branch: current` in a `remote` repo, skip the PR: dispatch a `worker` to push the head to its upstream with `git push` (upstream set), or `git push -u <remote> <head>` when the head has no upstream — never force. On a non-fast-forward rejection, stop and report; fetching or rebasing is a stop-and-ask. Return the pushed hash and `<head>`. Then, only after that push succeeded, run the resolved `hooks.push.after_push` entries (see below), and end the close-out (step 6 is skipped too). In a workspace, push each affected repo in `repos` order, stop at the first rejection, and return a per-repo table (pushed / rejected / not attempted); `hooks.push` is not run there — it is defined for a single `remote` repo only. The final report says "no PR — hooks.pr.* skipped" plus the push-hook outcome (ran: <names> / none declared / stopped at <name>), in `mode:auto` too. Otherwise, in a `remote` repo, dispatch a `worker`: *load the `sassy-commit-push-pr` skill and follow it with `branch:current` and `babysit:off`, forwarding `base:<branch>` when the caller supplied one* (step 6 owns the babysit). It returns the PR URL. In a `workspace`, open one PR per affected repo — the same branch name in each, `--base` from that repo's own `base_map` when it carries a `.sassywares/config.yaml`, else its `repos` entry — and return a table. A touched repo missing from `repos`, or a base that cannot be resolved, is a stop-and-ask, never a guess. `none` opens nothing.
43
+
44
+ **Push hooks.** Resolve `hooks.push.after_push` for the pushed head per `references/config.md` in the `sassy-setup` skill; empty means skip. An up-to-date push counts as successful, so the hooks run then too. Run each entry in declared order, one `worker` each: *load the project skill at `.agents/skills/<name>/SKILL.md` and follow it with the entry's args*, briefed with the standard hook brief from `references/config.md` plus the pushed hash and upstream. A missing skill or a `blocked` result stops the close-out and is reported; `needs-decision` is surfaced to the user and the close-out stops there, as with babysit and `sassy-commit-push-pr`. What an `after_push` hook may write is the contract in the same reference.
41
45
 
42
46
  **The PR step owns the PR hooks.** `before_create` and `after_create` run inside `sassy-commit-push-pr`, once per PR; ship neither runs nor repeats them.
43
47
  6. **Babysit.** Skipped under `commit.branch: current`. With `pr.babysit` (default `true`), dispatch a `worker`: *load the `sassy-babysit` skill and follow it for the PR just created, one checkpoint*, forwarding any `merge:on|off` and `delete-branch:on|off` the caller supplied, else `pr.merge` and `pr.delete_branch`. It reports looks-ready or blocked. For a continuous watch, tell the user to run `sassy-babysit` in-session.
@@ -50,6 +54,7 @@ argument-hint: "<plan path or topic> [steps:compound,handbook,commit,pr,babysit]
50
54
 
51
55
  | Rule | Requirement |
52
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. |
53
58
  | Review gate | `mode:manual` (default) presents the summary and waits before any write, commit, push, or PR. |
54
59
  | No review | `mode:auto` runs the close-out with no approval gate. Never toggled by the skill. |
55
60
  | All-or-nothing gate | In `mode:manual`, nothing is written until the gate is answered. |
@@ -59,11 +64,11 @@ argument-hint: "<plan path or topic> [steps:compound,handbook,commit,pr,babysit]
59
64
  | One branch | The branch is cut once, before the first change, by `sassy-work` or `sassy-lfg` (unless `commit.branch: current`). Ship and its docs commit land on it. |
60
65
  | Never create the branch | Ship never cuts a branch. Outside `commit.branch: current`, a head on a base branch with unpublished commits is a stop-and-ask, decided from the commit worker's `state` and `unpublished`. |
61
66
  | Never default | Never push directly to the repo base branch — except under `commit.branch: current`, an explicit opt-in, where ship pushes the checked-out branch (base or not) to its upstream, never forced. |
62
- | Current policy | `commit.branch: current` means commit + push, no PR: no `sassy-commit-push-pr`, no `hooks.pr.*`, no babysit, no merge. A non-fast-forward push is a stop-and-report; in a workspace the push stops at the first rejected repo. |
67
+ | Current policy | `commit.branch: current` means commit + push, no PR: no `sassy-commit-push-pr`, no `hooks.pr.*`, no babysit, no merge; `hooks.push.after_push` still runs (step 5). A non-fast-forward push is a stop-and-report; in a workspace the push stops at the first rejected repo. |
63
68
  | Snapshot after approval | In a workspace, the snapshot runs every time, immediately after the commit approval — never before it, never skipped. |
64
69
  | One PR per run | `pr.babysit` and `pr.merge` are single-PR. A fan-out gets one babysit run per PR and no automatic merge. |
65
- | Hooks are visible | The gate names every hook this run will trigger. A hook that runs unseen is a side effect nobody approved. |
66
- | One owner per hook | `before_create` and `after_create` belong to `sassy-commit-push-pr`; `before_merge` and `after_merge` belong to `sassy-babysit`. Ship never re-runs them. |
70
+ | Hooks are visible | The gate names every hook this run will trigger, `hooks.push` entries included. A hook that runs unseen is a side effect nobody approved. |
71
+ | One owner per hook | `before_create` and `after_create` belong to `sassy-commit-push-pr`; `before_merge` and `after_merge` belong to `sassy-babysit`; `after_push` belongs to ship (step 5). Ship never re-runs the first four. |
67
72
  | Compact I/O | Receive hashes, URLs, and one-line statuses only; never paste diffs. |
68
73
 
69
74
  ## Context and token discipline
@@ -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 manual QA checklist, 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.
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 manual and it 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.
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
- - The user runs the checks. The agent never ticks a row it did not hear confirmed: a row becomes `Done` only on the user's explicit confirmation in this conversation, with their note recorded.
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
- A brief has no QA table, so its gate is code approval alone. Never invent, enable, or disable QA.
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
- 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, how to run it, and what passing looks like, with unreported rows `Pending`. Ask for both decisions — code approval (or the changes wanted, including any suggestions picked) and the QA result per row. Wait.
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, QA 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.
60
- - **Changes requested, or any QA 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`, 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.
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 the user | Tick a QA row `Done` only from the user's explicit confirmation; keep unreported rows `Pending`; a failed row is a finding for a rework cycle. |
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