@sassywares/skills 0.5.1 → 0.5.3

package/README.md

@@ -133,8 +133,11 @@ knowledge:
   write: true                           # false = this project takes no learnings
 git:
   repo: origin                   # a remote name | workspace (repos below, none here) | none (no git)
-  # remote: org/backup           # workspace only: the snapshot mirror; required when repo: workspace
-  default_branch: main           # what branches are cut from and PRs target
+  base_map:                      # head branch -> the base it targets
+    "*": staging                 # ordinary work branches from and targets staging
+    staging: main                # staging releases to main
+  # remote: owner/backup         # workspace only: the snapshot mirror
+  # mirror_branch: main          # workspace only: the mirror's branch
 repos:                           # workspace only: each nested repo -> the base its PRs target
   fe: dev
 commit:
@@ -143,17 +146,20 @@ pr:
   babysit: true
   merge: false                   # true authorizes merging every babysat PR here
   delete_branch: false
-hooks:                           # project steps injected into the PR pipeline
+hooks:
   pr:
-    before_create: []            # after the commit, before the PR opens
-    after_create: []             # the moment the PR exists
-    before_merge: []             # this run is about to merge
-    after_merge: []              # this run observed the merge
+    "*":                         # keyed by the PR's HEAD branch
+      before_create: [tap2-version mode:auto]   # after the commit, before the PR opens
+      after_create: []           # the moment the PR exists
+      before_merge: []           # this run is about to merge
+      after_merge: []            # this run observed the merge
+    staging:                     # a per-point override for one head
+      before_create: []
 ```
 
 ### Extending the pipeline
 
-A project adds its own steps by naming a skill that lives in its own `.agents/skills/`. Nothing declared means nothing runs.
+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…>`).
 
 | Hook | Runs | Typical use |
 |---|---|---|

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sassywares/skills",
-  "version": "0.5.1",
+  "version": "0.5.3",
   "description": "Lean, explicit-invocation Agent Skills for shipping fast: plan, work, review, validate, ship.",
   "type": "module",
   "license": "MIT",

package/skills/sassy-babysit/SKILL.md

@@ -21,7 +21,9 @@ Keep an open PR moving toward merge by reacting to three streams as each arrives
 
 An explicit token always beats the config.
 
-**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.*` seeds `merge` and `delete_branch`; `hooks.pr.before_merge` and `hooks.pr.after_merge` inject project steps around a merge.
+**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.*` seeds `merge` and `delete_branch`; merge hooks come from `hooks.pr` for this run's head.
+
+**Keys are the head branch.** Resolve per head: the exact head, then the longest matching family (`release/*`), then `"*"`. Each point overrides independently. An entry is `<skill> <args…>` — split on the first whitespace and pass the args verbatim.
 
 **One PR per run.** This skill watches the PR resolved from the argument or the current branch. A workspace fan-out is N runs, one per PR, and `pr.merge` never merges a fan-out — that needs an explicit say-so per PR.
 
@@ -35,7 +37,7 @@ An explicit token always beats the config.
 
 Snapshot the PR state first, then act in this order:
 
-1. **Terminal** — `MERGED`/`CLOSED` → if it is `MERGED` and `hooks.pr.after_merge` is declared, run those hooks once (see Step 3) before stopping.
+1. **Terminal** — `MERGED`/`CLOSED` → if it is `MERGED` and `after_merge` resolves for this PR's head, run those hooks once (see Step 3) before stopping.
 2. **Capture the head SHA** — a later push invalidates this snapshot's CI.
 3. **Feedback before CI** — fetch open review threads (`gh pr view --json reviewThreads,comments`). Address each actionable thread: reply, then fix. Use `sassy-debug` for a real defect. Never wait for a reviewer who is "still reviewing" before acting on feedback already posted.
 4. **Stale-SHA cancellation** — if the head moved since step 2, skip the CI work for this snapshot.
@@ -50,7 +52,7 @@ Stop when any holds:
 - **Terminal** — merged or closed.
 - **Looks ready** — `MERGEABLE`, `CLEAN`, all checks terminal, no open review threads, no currency blocker, zero `needs-human` items. With `merge:on`, run the merge (and `delete-branch:on` branch deletion if set) before treating this as a stop; the merge turns it into the **Terminal** stop.
 
-  **Merge hooks.** Immediately before merging, run `hooks.pr.before_merge` in declared order — one `worker` per hook, with the same brief every hook gets: plan path, changed files, artifact paths, base, branch, commit hash, and the PR URL plus head SHA. These run before the merge, so they must leave the tree clean. A missing skill or a `blocked` result means **do not merge**: report it and stop at Blocked. After a successful merge, run `hooks.pr.after_merge` the same way; these follow the merge, so they must leave the tree clean. In a workspace fan-out, everything is per PR.
+  **Merge hooks.** Immediately before merging, resolve `before_merge` for this PR's head and run each entry in declared order — one `worker` per hook, with the same brief every hook gets: plan path, changed files, artifact paths, base, branch, commit hash, and the PR URL plus head SHA. These run before the merge, so they must leave the tree clean. A missing skill or a `blocked` result means **do not merge**: report it and stop at Blocked. After a successful merge, resolve `after_merge` for this PR's head and run each entry the same way; these follow the merge, so they must leave the tree clean. In a workspace fan-out, everything is per PR.
 
   **Which merge hook fires.** `before_merge` needs a merge this run will perform. `after_merge` fires whenever this run observes the PR merged, including one that was already merged when the run started — so it must be idempotent.
 

package/skills/sassy-commit-push-pr/SKILL.md

@@ -16,7 +16,9 @@ disable-model-invocation: true
 
 **Options.** `branch:new|current` selects the branch policy below. `babysit:on|off` (default `on`) controls the closing babysit. `checkpoint` bounds that babysit to a single tick. `merge:on|off` and `delete-branch:on|off` (both default `off`) are forwarded unchanged to `sassy-babysit`.
 
-**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. `commit.branch` seeds the branch policy, `pr.*` seeds the babysit options, and `hooks.pr.before_create` / `hooks.pr.after_create` inject project steps around the PR.
+**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. `commit.branch` seeds the branch policy, `pr.*` seeds the babysit options, and `hooks.pr` supplies the `before_create` / `after_create` steps for this run's head.
+
+**Keys are the head branch.** Resolve per head: the exact head, then the longest matching family (`release/*`), then `"*"`. Each point overrides independently. An entry is `<skill> <args…>` — split on the first whitespace and pass the args verbatim.
 
 ## Context
 
@@ -44,7 +46,7 @@ Only an exit-0 empty list means "no open PR". A non-zero exit means **unknown**
 ## Steps
 
 1. **Commit** — follow `sassy-commit` with the branch choice from the policy above (named files only, outcome-stating message). Honor an `exclude:<paths>` token if present.
-2. **`before_create` hooks.** Read `hooks.pr.before_create` from the config; empty means skip. Run each name in declared order, one `worker` per hook, whose task is *read `<repo>/.agents/skills/<name>/SKILL.md` and follow it* plus a brief: plan path, changed files, artifact paths, base, branch, and the commit hash. This point runs **after** the commit, so a hook may write and commit its own artifacts — push whatever ends up on the branch. A missing skill or a `blocked` result stops the run and names the hook; a `needs-decision` result comes back to you to present.
+2. **`before_create` hooks.** Resolve `before_create` for the head branch (`base_map` decides the base, the head is the branch you are on); empty means skip. Split each entry on the first whitespace — the first token is the skill, the rest are its args. Run each name in declared order, one `worker` per hook, whose task is *read `<repo>/.agents/skills/<name>/SKILL.md` and follow it* plus a brief: plan path, changed files, artifact paths, base, branch, and the commit hash. This point runs **after** the commit, so a hook may write and commit its own artifacts — push whatever ends up on the branch. A missing skill or a `blocked` result stops the run and names the hook; a `needs-decision` result comes back to you to present.
 3. **Pre-push gate** — resolve any pre-push or review-ready requirement from the project's active instructions. Only evidence valid for the exact commit being sent satisfies it; otherwise stop and report what is missing. If none, proceed.
 4. **Push** — `git push -u origin <branch>` for a new branch, else `git push`. Re-verify branch and remote first, and re-check that the branch is ahead of origin after any hook commits.
 5. **Compose the PR title and body**

package/skills/sassy-setup/assets/sassywares-readme.md

@@ -31,4 +31,4 @@ If a skill tells you another skill is missing, run `skills:sync` and restart. Su
 
 ## Hooks
 
-`hooks.pr.*` names project skills that run inside the PR pipeline: `before_create`, `after_create`, `before_merge`, `after_merge`. They are ordinary skills in `.agents/skills/`, which means they are **code** — review them like code, and never point a hook at a copy of a suite skill.
+`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.

package/skills/sassy-setup/references/config.md

@@ -157,8 +157,9 @@ feature/x  --base_map["*"]-->     staging  --base_map[staging]-->  main
 ```
 
 1. `base_map[<head>]` — the exact rung
-2. `base_map["*"]` — ordinary work
-3. stop and ask; never guess
+2. the longest matching family key (`release/*`) — a nested rung
+3. `base_map["*"]` — ordinary work
+4. stop and ask; never guess
 
 A rung is a release edge: standing on `staging`, a PR targets `main` without
 anyone passing `base:main`. Add a rung for any branch that releases elsewhere; a
@@ -169,6 +170,9 @@ The probed remote default is only useful as a hint for `"*"`: it tells you where
 the repository considers work to land, not what every branch targets. Confirm it
 before writing.
 
+`--head <branch>` prints the resolution for one head: the base (repo topology)
+and all four hook points. Use it instead of merging maps by hand.
+
 In a `workspace`, `base_map` does not apply — there are no branches at the
 workspace level. Nested repos carry their own bases in `repos`, and a nested repo
 that needs a ladder gets its own `.sassywares/config.yaml` rather than a nested
@@ -230,9 +234,9 @@ Per point, independently:
 3. `"*"`
 
 The first rule that declares a value for that point wins and the rest are not
-merged. So a `staging` entry that sets only `before_create` still inherits
-`after_merge` from `"*"`. Declaring the same point in two families that both
-match one head is a configuration error, not a precedence puzzle.
+merged, so a `staging` entry that sets only `before_create` still inherits
+`after_merge` from `"*"`. When two families match one head, the longer prefix
+wins — `release/v2/*` beats `release/*`.
 
 ### Entries carry arguments
 

package/skills/sassy-setup/scripts/detect.sh

@@ -6,6 +6,7 @@
 #
 # Usage:
 #   detect.sh [--root DIR]            print a proposed config to stdout
+#   detect.sh [--head BRANCH]         resolve the base and hooks for one head
 #   detect.sh [--root DIR] --check    compare the existing config to reality
 set -euo pipefail
 
@@ -290,6 +291,9 @@ if (( CHECK )); then
   fi
 
   if [[ "$TOPOLOGY" == "repo" ]]; then
+    if [[ -n "$(yflat "git${US}remote")" ]]; then
+      bad "git.remote is workspace-only — a repo config names its remote in git.repo"
+    fi
     if [[ -z "$(yflat "git${US}base_map${US}*")" ]]; then
       bad "git.base_map has no \"*\" entry — it is the base for ordinary work"
     else
@@ -302,7 +306,8 @@ if (( CHECK )); then
       done < <(yaml_flat | awk -F'\t' -v us="$US" '{n=split($1,a,us); if (n==3 && a[1]=="git" && a[2]=="base_map") print a[3]}' | sort -u)
       head_ref="${HEAD_ARG:-$(git -C "$ROOT" branch --show-current 2>/dev/null || true)}"
       if [[ -n "$head_ref" ]]; then
-        note "  base for '${head_ref}': $(base_for_head "$head_ref")"
+        # the --head readout below prints this line; avoid printing it twice
+        [[ -n "$HEAD_ARG" ]] || note "  base for '${head_ref}': $(base_for_head "$head_ref")"
         cur="$head_ref"; hops=0
         while [[ -n "$cur" ]] && (( hops < 8 )); do
           next="$(yflat "git${US}base_map${US}${cur}")"
@@ -453,7 +458,8 @@ EOF
     else
       printf '    "*": %s   # base for ordinary work; never guessed\n' "<confirm by hand>"
     fi
-    printf '    # staging: main   # uncomment when a branch releases somewhere else\n'
+    printf '    # staging: main    # uncomment when a branch releases somewhere else\n'
+    printf '    # release/*: main  # a family of heads, longest prefix wins\n'
     cat <<'EOF'
 
 # workspace only: each nested repo folder -> the base its PRs target

package/skills/sassy-ship/SKILL.md

@@ -22,7 +22,7 @@ disable-model-invocation: true
 
 ## Steps (in order)
 
-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, and **the hooks this run will trigger, by point and name, or that none are declared** — and wait. In `mode:auto`, skip this gate.
+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, and **the hooks resolved for this run's head — point, skill, and args — or that none are declared** — and wait. In `mode:auto`, skip this gate.
 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`.
 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.
 4. **Commit or snapshot.** After the review gate — never before it — the docs and any remaining code become durable.