@sassywares/skills 0.8.0 → 0.9.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 CHANGED
@@ -74,6 +74,6 @@ A settled in-context brief produced by `sassy-plan` when the user picks "start w
74
74
 
75
75
  `sassy-handoff` in `mode:write` writes a self-contained handoff file under `/tmp/sassywares/<harness>/handoffs/` and gives the user a `sassy-handoff mode:read <path>` command; `mode:read` in the fresh session summarizes what was done, why, and the current state against the tree, then asks what to do next. A skill cannot start a session, so the user opens the fresh one; the file is the only bridge, in any harness.
76
76
 
77
- ## Sync
77
+ ## Release
78
78
 
79
- There is no background watcher. Any agent that changes a skill must run `scripts/sync.sh` immediately, without asking for confirmation. It commits and pushes; on `main`, when shipped files changed, it also bumps the patch version and tags, which publishes to npm. It installs nothing: `npx skills add` reads this repo directly. AGENTS.md has the details.
79
+ There is no background watcher. Releases go through `sassy-ship` under `commit.branch: current`: after the approved push, the `hooks.push` `after_push` hook runs the `sassy-skills-release` project skill, which runs the vendored `bin/release` script. It bumps the patch version and tags when consumer-facing files changed, and the tag publishes to npm. It installs nothing: `npx skills add` reads this repo directly. AGENTS.md has the details.
package/README.md CHANGED
@@ -162,11 +162,14 @@ hooks:
162
162
  after_merge: [] # this run observed the merge
163
163
  staging: # a per-point override for one head
164
164
  before_create: []
165
+ push: # only under commit.branch: current
166
+ "*":
167
+ after_push: [] # right after the push succeeds
165
168
  ```
166
169
 
167
170
  ### Extending the pipeline
168
171
 
169
- A project adds its own steps by naming a skill that lives in its own `.agents/skills/`. Nothing declared means nothing runs. Keys are the **head** branch — the one a PR comes from — and every point can be overridden per head; entries may carry args (`<skill> <args…>`).
172
+ A project adds its own steps by naming a skill that lives in its own `.agents/skills/`. Nothing declared means nothing runs. Keys are the **head** branch — the one a PR comes from (for `hooks.push`, the pushed branch) — and every point can be overridden per head; entries may carry args (`<skill> <args…>`).
170
173
 
171
174
  | Hook | Runs | Typical use |
172
175
  |---|---|---|
@@ -174,8 +177,9 @@ A project adds its own steps by naming a skill that lives in its own `.agents/sk
174
177
  | `after_create` | the PR was just created | labels, deploy-target comment |
175
178
  | `before_merge` | this run is about to merge | a final approval gate |
176
179
  | `after_merge` | this run observed the merge | sync a back-merge branch, tag, notify |
180
+ | `hooks.push` `after_push` | `commit.branch: current` only: after ship's push | notify, trigger a follow-up step |
177
181
 
178
- Hooks run in declared order, one subagent each, and fail closed: a declared skill that is missing or returns `blocked` stops the run. Only `before_create` may commit its own output, because it runs after the pipeline's commit. `before_merge` and `after_merge` never fire unless this run merges.
182
+ Hooks run in declared order, one subagent each, and fail closed: a declared skill that is missing or returns `blocked` stops the run. Which points may write, and how, is stated once in `sassy-setup`'s `references/config.md` (the hook contract). `before_merge` and `after_merge` never fire unless this run merges.
179
183
 
180
184
  This is deliberately not a fork mechanism. A project skill that *adds* a step is a hook; one that *restates* our steps is a copy, and copies rot. Rules are not hooks either — those belong in `AGENTS.md`.
181
185
 
@@ -366,4 +370,4 @@ pi install npm:@sassywares/skills
366
370
 
367
371
  ## Repository maintenance
368
372
 
369
- Any agent that changes a skill runs `scripts/sync.sh` immediately, which commits, pushes, and — on `main`, when shipped files changed — bumps the patch version and tags the release that publishes `@sassywares/skills` to npm. [`AGENTS.md`](AGENTS.md) is the full guide: layout, adding a skill, sync, and the manual release fallback.
373
+ Work here lands on `main` through `sassy-ship` (`commit.branch: current`). After the approved push, the project's `hooks.push` `after_push` step runs the release: on `main`, when files consumers receive changed, it bumps the patch version and tags it, and the tag publishes `@sassywares/skills` to npm. [`AGENTS.md`](AGENTS.md) is the full guide: layout, adding a skill, testing, and releasing.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@sassywares/skills",
3
- "version": "0.8.0",
3
+ "version": "0.9.0",
4
4
  "description": "Lean, explicit-invocation Agent Skills for shipping fast: plan, work, review, validate, ship.",
5
5
  "type": "module",
6
6
  "license": "MIT",
@@ -41,9 +41,9 @@ A check run never edits the config and never rewrites the tree: it prints what `
41
41
  - **Artifacts** — offer the detected paths as the default; take overrides.
42
42
  - **Knowledge** — `knowledge.read` defaults to the solutions dir plus the concepts file. Ask whether there are extra folders to read (a hand-written `notes/learnings/`, a `docs/adr/`).
43
43
  - **Base map** — detection proposes `"*"` from the probed remote default. Ask where ordinary work branches from, and whether the default branch itself releases to another branch (a `staging: main` rung). Never write `main` as a guess. In `workspace` mode, show the `repos` map and get a yes on every row — a probed base is only the remote's default.
44
- - **`commit.branch`** — default `new`: the run cuts a branch before the first change and never commits on a base branch. Offer `current` for a repo that genuinely wants work committed where it stands, and say plainly that `current` lets a run commit onto its base branch and push it, with no PR (`pr.*` and `hooks.pr` are ignored). Under `mode:auto` with `current` on a base branch, ship pushes to that base with no gate.
44
+ - **`commit.branch`** — default `new`: the run cuts a branch before the first change and never commits on a base branch. Offer `current` for a repo that genuinely wants work committed where it stands, and say plainly that `current` lets a run commit onto its base branch and push it, with no PR (`pr.*` and `hooks.pr` are ignored; `hooks.push` runs). Under `mode:auto` with `current` on a base branch, ship pushes to that base with no gate.
45
45
  - **`pr.*`** — default `babysit: true`, `merge: false`, `delete_branch: false`. Say plainly that `merge: true` authorizes merging every babysat PR in this project without asking.
46
- - **Hooks** — offer, do not impose. Ask whether the project wants steps injected at `before_create`, `after_create`, `before_merge`, or `after_merge`, and under which head branch (`"*"` for all). Entries may carry args (`<skill> <args…>`); a hook skill's args are its own vocabulary. Leave them `[]` when there is nothing to add. **Never write a hook skill yourself** — hooks are project skills, and copying one of ours into that role is the fork this mechanism exists to prevent.
46
+ - **Hooks** — offer, do not impose. Ask whether the project wants steps injected at `before_create`, `after_create`, `before_merge`, or `after_merge` (or `hooks.push` `after_push`, for `commit.branch: current` only), and under which head branch (`"*"` for all). Entries may carry args (`<skill> <args…>`); a hook skill's args are its own vocabulary. Leave them `[]` when there is nothing to add. **Never write a hook skill yourself** — hooks are project skills, and copying one of ours into that role is the fork this mechanism exists to prevent.
47
47
  4. **Write the config.** Build the file from the proposal plus the answers. It is written **fully commented**: every key keeps a description and its allowed values, exactly as the detector emits them. Never strip those comments to save lines — for a teammate opening the file, the comments are the documentation. If a config already exists, show what changes and ask before writing — never silently overwrite. Keep every key; an unset key falls back to its documented default, so a short file is legal when nothing deviates.
48
48
  5. **Wire the skills and the agents.** Both install the same way: if they are already there in either scope, report which and move on; if not, ask once where to install, recommending user scope.
49
49
 
@@ -76,7 +76,7 @@ A check run never edits the config and never rewrites the tree: it prints what `
76
76
  - **Tell the user to `/reload`** (or restart the harness). The skills and agents are invisible to the harness until it rescans.
77
77
 
78
78
  6. **Install the workspace tooling, `workspace` only.** The snapshot plus the `branches` / `pull` / `checkout-bases` git helpers, and one `workspace:<script>` alias per script in the project's own manifest. Read `references/workspace.md` and follow it.
79
- 7. **Verify.** Run `scripts/detect.sh --root <path> --check`. It validates the config against the tree — topology and remotes, `base_map` shape and cycles, `repos` against each nested repo, hooks, artifacts paths, `knowledge`, `pr.*` booleans, `commit.branch`, any unknown key, and in `workspace` mode the installed snapshot's version — plus, for a project-scope install, the pin: every `.agents/skills/sassy-*` folder hashed against `skills-lock.json`, the lock's coverage both ways, and whether git carries the lock. A user-scope install has no pin here; the check notes the scope it found. Report every `drift:` line verbatim, or that the config matches the tree. Drift blocks step 8.
79
+ 7. **Verify.** Run `scripts/detect.sh --root <path> --check`. It validates the config against the tree — topology and remotes, `base_map` shape and cycles, `repos` against each nested repo, hooks, artifacts paths, `knowledge`, `pr.*` booleans, `commit.branch`, any unknown key, and in `workspace` mode the installed snapshot's version — plus, for a project-scope install, the pin: every suite-skill folder in `.agents/skills` (a name in the suite's roster, `assets/roster` in sassy-setup, not any `sassy-` prefix) hashed against `skills-lock.json`, the lock's coverage both ways, and whether git carries the lock. A user-scope install has no pin here; the check notes the scope it found. Report every `drift:` line verbatim, or that the config matches the tree. Drift blocks step 8.
80
80
 
81
81
  Then check the skills and the agents exactly as step 5's **Installed** rules say, and report the scope each was found in or what is missing. A check run never installs them; a missing suite or roster is reported with the fix (`mode:init`), and it does not block step 8.
82
82
  8. **Commit what setup owns.** `repo` topology only, and only when step 7 is clean. The file list is exactly what setup wrote or found unwritten:
@@ -0,0 +1,19 @@
1
+ sassy-babysit
2
+ sassy-commit
3
+ sassy-commit-push-pr
4
+ sassy-compound
5
+ sassy-cycle
6
+ sassy-debug
7
+ sassy-goal
8
+ sassy-handbook
9
+ sassy-handoff
10
+ sassy-lfg
11
+ sassy-plan
12
+ sassy-review
13
+ sassy-scout
14
+ sassy-setup
15
+ sassy-ship
16
+ sassy-simplify
17
+ sassy-skill
18
+ sassy-validate
19
+ sassy-work
@@ -71,4 +71,4 @@ mirrored tree. The `sassy-*` skills do their own git and never call them.
71
71
 
72
72
  ## Hooks
73
73
 
74
- `hooks.pr` names project skills that run inside the PR pipeline, keyed by the PR's **head** branch: `"*"` for every PR, an exact branch, or a family such as `release/*`, overriding per point (`before_create`, `after_create`, `before_merge`, `after_merge`). An entry is `<skill> <args…>`; the args mean whatever that skill says they mean — `mode:auto` pre-authorizes the step. Hooks are ordinary skills in `.agents/skills/`, which makes them **code**: review them like code, and never point a hook at a copy of a suite skill. Under `commit.branch: current` there is no PR, so these hooks do not run.
74
+ `hooks.pr` names project skills that run inside the PR pipeline, keyed by the PR's **head** branch: `"*"` for every PR, an exact branch, or a family such as `release/*`, overriding per point (`before_create`, `after_create`, `before_merge`, `after_merge`). An entry is `<skill> <args…>`; the args mean whatever that skill says they mean — `mode:auto` pre-authorizes the step. Hooks are ordinary skills in `.agents/skills/`, which makes them **code**: review them like code, and never point a hook at a copy of a suite skill. Under `commit.branch: current` there is no PR, so these hooks do not run; `hooks.push` (one point, `after_push`, keyed by the pushed branch) runs there instead, right after a successful push.
@@ -94,7 +94,7 @@ Only reachable with `policy: current`, which is an explicit statement that
94
94
  committing on the base branch is intended. Proceed, and say in the run's gate
95
95
  summary that the commits are landing on `<head>`. When the config says
96
96
  `commit.branch: current`, the close-out commits and pushes `<head>` to its upstream with **no PR** — no
97
- `sassy-commit-push-pr`, no `hooks.pr.*`, no babysit, no merge. `pr-base` is
97
+ `sassy-commit-push-pr`, no `hooks.pr.*`, no babysit, no merge; only `hooks.push.after_push` runs. `pr-base` is
98
98
  irrelevant here. Never infer this from a skill default.
99
99
 
100
100
  ### `stop-and-ask`
@@ -76,6 +76,9 @@ hooks:
76
76
  before_create: [tap2-version mode:auto]
77
77
  staging:
78
78
  before_create: []
79
+ push:
80
+ "*":
81
+ after_push: [] # commit.branch: current only
79
82
  ```
80
83
 
81
84
  | Key | Default | Meaning |
@@ -96,6 +99,7 @@ hooks:
96
99
  | `pr.merge` | `false` | `true` authorizes merging a single babysat PR |
97
100
  | `pr.delete_branch` | `false` | Delete the head branch once merged |
98
101
  | `hooks.pr.<pattern>.<point>` | `[]` | Project steps, keyed by the PR's head branch |
102
+ | `hooks.push.<pattern>.after_push` | `[]` | Project steps after a push, keyed by the pushed branch (see Hooks) |
99
103
 
100
104
  Paths are relative to the config's own directory, never to the cwd.
101
105
 
@@ -183,7 +187,8 @@ phase work once got committed straight onto `staging`.
183
187
 
184
188
  Under `current` the close-out skips the PR pipeline: `pr.*` and `hooks.pr.*`
185
189
  are ignored (`before_create`, `after_create`, `before_merge`, `after_merge` never
186
- run), and there is no babysit or merge. A non-fast-forward push stops the run.
190
+ run), and there is no babysit or merge. `hooks.push.after_push` is the one hook
191
+ that does run (see Hooks). A non-fast-forward push stops the run.
187
192
  Only this config value triggers it. A typed `branch:current` token, or the one
188
193
  skills forward to `sassy-commit`, does not suppress the PR.
189
194
 
@@ -287,6 +292,12 @@ targets. `hooks.pr.staging` means *PRs whose source is staging*.
287
292
  | `after_create` | `sassy-commit-push-pr` | the PR was just created — not on an update |
288
293
  | `before_merge` | `sassy-babysit` | the PR looks ready **and** this run will merge it |
289
294
  | `after_merge` | `sassy-babysit` | this run observed the PR merged |
295
+ | `hooks.push.after_push` | `sassy-ship` | right after a successful push under `commit.branch: current` |
296
+
297
+ `hooks.push` has the same shape and resolution as `hooks.pr`, but its key is the
298
+ pushed head branch and its only point is `after_push`. It runs only under
299
+ `commit.branch: current`, in a single `remote` repo, never after a rejected push
300
+ or in a workspace.
290
301
 
291
302
  ### Resolution
292
303
 
@@ -317,15 +328,20 @@ in review, and commented when it is deliberate.
317
328
  - **Names**: a skill the project owns, never one of ours.
318
329
  - **Order**: declared order, one worker each, sequential.
319
330
  - **Brief**: plan path, changed files, artifact paths, base, branch, commit hash,
320
- and the PR URL where one exists.
331
+ and the PR URL where one exists. `after_push` has no PR and also gets the
332
+ pushed hash and the upstream.
321
333
  - **Result**: `done`, `blocked`, or `needs-decision`; a decision comes back to the
322
334
  orchestrator, which holds the gate.
323
335
  - **Fail closed**: a missing skill or a `blocked` result stops the pipeline.
324
- - **Writes**: only `before_create` may also commit, because it runs after the
325
- pipeline's commit; every other point leaves the tree clean.
326
- - **Never**: push, open a PR, change `mode`, `branch`, or `merge`.
336
+ - **Writes**: `before_create` may also commit, because it runs after the
337
+ pipeline's commit. `after_push` may commit and push the checked-out head and
338
+ push tags, never forcing, opening or merging a PR, or touching another branch.
339
+ Every other point leaves the tree clean.
340
+ - **Never**: push (bar `after_push`, above), open a PR, change `mode`, `branch`,
341
+ or `merge`.
327
342
  - **Idempotent**: `after_merge` can be reached by a later run observing an
328
- already merged PR, and `before_create` can run again on a re-ship.
343
+ already merged PR, `before_create` can run again on a re-ship, and `after_push`
344
+ runs after an up-to-date push (nothing new) too.
329
345
  - **Per PR**: in a workspace fan-out the hooks run once per PR.
330
346
 
331
347
  ### When they do not fire
@@ -365,8 +381,9 @@ per-PR say-so, because one switch would merge N PRs nobody re-read.
365
381
  - `git.repo` is `workspace`, `none`, or one existing remote name.
366
382
  - `git.remote` is required when `git.repo: workspace`; forbidden otherwise.
367
383
  `git.mirror_branch` and `repos` are workspace-only too.
368
- - `hooks` is allowed only with the four keys under `hooks.pr`, each a list of
369
- skill names that resolve to `.agents/skills/<name>/SKILL.md`.
384
+ - `hooks` is allowed only with the four keys under `hooks.pr` and `after_push`
385
+ under `hooks.push`, each a list of skill names that resolve to
386
+ `.agents/skills/<name>/SKILL.md`.
370
387
  - `commit.branch` is `current` or `new`; `pr.*` are `true` or `false`. Write
371
388
  booleans as `true`/`false`, never `on`/`off` — bare `on`/`off` are YAML 1.1
372
389
  booleans and parse inconsistently.
@@ -377,7 +394,7 @@ per-PR say-so, because one switch would merge N PRs nobody re-read.
377
394
 
378
395
  `scripts/detect.sh --check` enforces all of the above and reports each breach as
379
396
  a `drift:` line, exiting non-zero. When the suite is installed in project
380
- scope it also verifies the vendored pin offline: every `.agents/skills/sassy-*` folder is hashed with the `skills` CLI's own
397
+ scope it also verifies the vendored pin offline: every `.agents/skills/<name>` folder whose name is a suite skill (a name in the suite's roster, `assets/roster` in sassy-setup, not merely `sassy-`-prefixed) is hashed with the `skills` CLI's own
381
398
  definition and compared to `computedHash` in `skills-lock.json`, the lock is
382
399
  checked against the installed set in both directions, and git-tracked state of
383
400
  the lock is reported. A stale, hand-edited, or half-installed suite is drift
@@ -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
 
@@ -189,15 +207,35 @@ map_match() {
189
207
 
190
208
  base_for_head() { map_match base_map "$1"; }
191
209
 
210
+ # hook_patterns [KIND] — the head patterns declared under hooks.<kind> (pr by default).
192
211
  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
212
+ 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
213
+ }
214
+
215
+ # hook_points KIND — the single source of point names; empty for an unknown kind.
216
+ hook_points() {
217
+ case "$1" in
218
+ pr) printf '%s' "before_create after_create before_merge after_merge" ;;
219
+ push) printf '%s' "after_push" ;;
220
+ esac
194
221
  }
195
222
 
196
- # hooks_for_head_point HEAD POINT — exact head, then the longest matching
223
+ # hooks_declared KIND — succeeds when hooks.<kind> names at least one skill.
224
+ hooks_declared() {
225
+ local kind="$1" pat point
226
+ while IFS= read -r pat; do
227
+ for point in $(hook_points "$kind"); do
228
+ [[ -n "$(list_items "$(yflat "hooks${US}${kind}${US}${pat}${US}${point}")")" ]] && return 0
229
+ done
230
+ done < <(hook_patterns "$kind")
231
+ return 1
232
+ }
233
+
234
+ # hooks_for_head_point HEAD POINT [KIND] — exact head, then the longest matching
197
235
  # family, then "*". A pattern that declares no entry for this point inherits.
198
236
  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}")"
237
+ local head="$1" point="$2" kind="${3:-pr}" pat stem best="" bestlen=0 v
238
+ v="$(yflat "hooks${US}${kind}${US}${head}${US}${point}")"
201
239
  [[ -n "$v" ]] && { printf '%s' "$v"; return; }
202
240
  while IFS= read -r pat; do
203
241
  case "$pat" in *"*") ;; *) continue ;; esac
@@ -206,12 +244,12 @@ hooks_for_head_point() {
206
244
  if [[ "$head" == "$stem"* ]] && (( ${#stem} > bestlen )); then
207
245
  best="$pat"; bestlen=${#stem}
208
246
  fi
209
- done < <(hook_patterns)
247
+ done < <(hook_patterns "$kind")
210
248
  if [[ -n "$best" ]]; then
211
- v="$(yflat "hooks${US}pr${US}${best}${US}${point}")"
249
+ v="$(yflat "hooks${US}${kind}${US}${best}${US}${point}")"
212
250
  [[ -n "$v" ]] && { printf '%s' "$v"; return; }
213
251
  fi
214
- printf '%s' "$(yflat "hooks${US}pr${US}*${US}${point}")"
252
+ printf '%s' "$(yflat "hooks${US}${kind}${US}*${US}${point}")"
215
253
  }
216
254
 
217
255
  detect_base() {
@@ -331,7 +369,7 @@ if (( CHECK )); then
331
369
  repos.*) ;;
332
370
  commit.branch) ;;
333
371
  pr.babysit|pr.merge|pr.delete_branch) ;;
334
- hooks.pr.*) ;; # shape checked with the hooks
372
+ hooks.*) ;; # shape checked with the hooks
335
373
  *) bad "unknown key '$key' — it is ignored, so the run uses the default" ;;
336
374
  esac
337
375
  done < <(yaml_flat "$CONFIG")
@@ -482,39 +520,48 @@ if (( CHECK )); then
482
520
  if [[ -n "$(yflat "hooks${US}pr${US}before_create")" ]]; then
483
521
  bad "hooks.pr.<point> is now nested by head branch — write hooks.pr.\"*\".<point>"
484
522
  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)
523
+ for kind in pr push; do
524
+ while IFS= read -r pat; do
525
+ [[ -n "$pat" ]] || continue
526
+ case "$pat" in
527
+ "*") ;;
528
+ *"*") [[ "${pat%\*}" != *"*" ]] || bad "hook pattern '$pat': only one trailing * is allowed" ;;
529
+ esac
530
+ for point in $(hook_points "$kind"); do
531
+ val="$(yflat "hooks${US}${kind}${US}${pat}${US}${point}")"
532
+ [[ -n "$val" ]] || continue
533
+ while IFS= read -r entry; do
534
+ [[ -n "$entry" ]] || continue
535
+ name="${entry%% *}"
536
+ if is_suite_skill "$name"; then
537
+ bad "hooks.$kind.$pat.$point: '$name' is one of our skills — hooks are project skills only"
538
+ else
539
+ hook_skill_path "$name" >/dev/null 2>&1 \
540
+ || bad "hooks.$kind.$pat.$point: '$name' not found at .agents/skills/$name/SKILL.md"
541
+ fi
542
+ done < <(list_items "$val")
543
+ done
544
+ done < <(hook_patterns "$kind")
545
+ done
505
546
 
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.
547
+ # `hooks.<kind>.<head>.<point>` is the only shape. hooks.pr has four points and
548
+ # hooks.push has one; any other point name is a step that never fires.
508
549
  while IFS=$'\t' read -r depth hpath; do
509
550
  [[ -n "$depth" ]] || continue
551
+ kind="${hpath#hooks$US}"; kind="${kind%%$US*}"
552
+ case "$kind" in
553
+ pr|push) ;;
554
+ *) bad "hooks kind '$kind' is not one of pr|push"; continue ;;
555
+ esac
510
556
  if [[ "$depth" != "4" ]]; then
511
557
  bad "hooks entry '${hpath//$US/.}' is not head -> point -> list"
512
558
  continue
513
559
  fi
514
560
  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" ;;
561
+ points="$(hook_points "$kind")"
562
+ case " $points " in
563
+ *" $point "*) ;;
564
+ *) bad "hooks.$kind point '$point' is not one of ${points// /|}" ;;
518
565
  esac
519
566
  done < <(yaml_flat "$CONFIG" \
520
567
  | awk -F'\t' -v us="$US" '{n=split($1,a,us); if (n>=2 && a[1]=="hooks") print n "\t" $1}')
@@ -524,9 +571,11 @@ if (( CHECK )); then
524
571
  if [[ "$TOPOLOGY" == "repo" ]]; then
525
572
  note " base for '$HEAD_ARG': $(base_for_head "$HEAD_ARG")"
526
573
  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' )"
574
+ for kind in pr push; do
575
+ for point in $(hook_points "$kind"); do
576
+ resolved="$(hooks_for_head_point "$HEAD_ARG" "$point" "$kind")"
577
+ note " head '$HEAD_ARG' → $point: $( [[ -n "$resolved" ]] && printf '%s' "$resolved" || printf 'none' )"
578
+ done
530
579
  done
531
580
  fi
532
581
 
@@ -601,16 +650,30 @@ if (( CHECK )); then
601
650
  esac
602
651
  fi
603
652
 
653
+ # Hooks that cannot fire are a note, not drift: the config is legal, the step
654
+ # just never runs. hooks.push needs `current` in a single remote repo.
655
+ if [[ "$val" == "current" ]]; then
656
+ if hooks_declared pr; then
657
+ note " hooks.pr entries are declared but commit.branch is current — no PR, so they never run"
658
+ fi
659
+ if hooks_declared push && [[ "$configured_repo" == "workspace" || "$configured_repo" == "none" ]]; then
660
+ note " hooks.push entries are declared but git.repo is '$configured_repo' — they never run"
661
+ fi
662
+ elif hooks_declared push; then
663
+ note " hooks.push entries are declared but commit.branch is not current — they never run"
664
+ fi
665
+
604
666
  # The pin. A config can match the tree perfectly while the vendored suite is
605
667
  # stale, edited, or half-installed, and every skill downstream then runs
606
668
  # something other than what the lock says. Offline, no network.
669
+ [[ -n "$SUITE_ROSTER" ]] || note " suite roster not found — falling back to the sassy-* name prefix"
607
670
  if command -v node >/dev/null 2>&1; then
608
671
  while IFS=$'\t' read -r kind msg; do
609
672
  case "$kind" in
610
673
  drift) bad "$msg" ;;
611
674
  note) note " $msg" ;;
612
675
  esac
613
- done < <(node "$SKILL_DIR/scripts/lockcheck.mjs" --root "$ROOT" 2>/dev/null || true)
676
+ done < <(node "$SKILL_DIR/scripts/lockcheck.mjs" --root "$ROOT" --roster "$SUITE_ROSTER" 2>/dev/null || true)
614
677
  else
615
678
  note " node not found — the vendored pin is unverified (the skills CLI needs node)"
616
679
  fi
@@ -949,7 +1012,7 @@ cat <<'EOF'
949
1012
 
950
1013
  # --- Commit ---------------------------------------------------------------
951
1014
  # 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.
1015
+ # it to its upstream. No PR: pr.* and hooks.pr are ignored; hooks.push runs.
953
1016
  # new: never commit on a base branch — sassy-work, sassy-lfg, and sassy-debug
954
1017
  # cut a branch at the start of the run and stay on it.
955
1018
  commit:
@@ -966,7 +1029,8 @@ kv delete_branch false 24 '# true | false — delete the head branch once merged
966
1029
  cat <<'EOF'
967
1030
 
968
1031
  # --- Hooks ----------------------------------------------------------------
969
- # Project steps injected into the PR pipeline, keyed by the HEAD branch — the
1032
+ # Project steps injected into the PR pipeline, or after a push under
1033
+ # commit.branch: current, keyed by the HEAD branch — the
970
1034
  # branch the PR comes from, never the one it targets. `"*"` is the default;
971
1035
  # a name overrides per point, and `release/*` matches a family. Each entry is
972
1036
  # `<skill> <args…>`, resolved at .agents/skills/<name>/SKILL.md; args are passed
@@ -984,4 +1048,7 @@ cat <<'EOF'
984
1048
  # before_create: []
985
1049
  # release/*: # a family of heads
986
1050
  # after_merge: [notify mode:auto]
1051
+ # push: # commit.branch: current only; keyed by the pushed branch
1052
+ # "*":
1053
+ # after_push: []
987
1054
  EOF
@@ -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,7 +28,7 @@ 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.
@@ -37,7 +37,9 @@ argument-hint: "<plan path or topic> [steps:compound,handbook,commit,pr,babysit]
37
37
  **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
38
  - **`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
39
  - **`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.
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, 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.
41
+
42
+ **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
43
 
42
44
  **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
45
  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.
@@ -59,11 +61,11 @@ argument-hint: "<plan path or topic> [steps:compound,handbook,commit,pr,babysit]
59
61
  | 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
62
  | 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
63
  | 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. |
64
+ | 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
65
  | Snapshot after approval | In a workspace, the snapshot runs every time, immediately after the commit approval — never before it, never skipped. |
64
66
  | 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. |
67
+ | 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. |
68
+ | 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
69
  | Compact I/O | Receive hashes, URLs, and one-line statuses only; never paste diffs. |
68
70
 
69
71
  ## Context and token discipline