@sassywares/skills 0.4.3 → 0.5.0

package/package.json

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

package/skills/sassy-commit/SKILL.md

@@ -30,7 +30,7 @@ Treat the reads as a snapshot; re-read branch and staged set right before commit
 
 **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` supplies the default.
 
-**Branch option.** `branch:current|new [<name>]`. `current` commits on the checked-out branch. `new` cuts a branch from `origin/<base>` — `<base>` is `repos[<dir>]` in a workspace config, else `git.default_branch`, else the probed base **confirmed with the user** — named `<name>` when given, else from the change. `sassy-commit-push-pr` forwards its own `branch` choice here.
+**Branch option.** `branch:current|new [<name>]`. `current` commits on the checked-out branch. `new` cuts a branch from `origin/<base>` — `<base>` is `repos[<dir>]` in a workspace config, else `base_map[<current head>]` (falling back to `base_map["*"]`), else the probed base **confirmed with the user** — named `<name>` when given, else from the change. `sassy-commit-push-pr` forwards its own `branch` choice here.
 
 **Not in a workspace root, not outside git.** With `git.repo: workspace` there is no local commit to make: refuse in one line and name the snapshot instead. With `git.repo: none`, refuse and say the project is deliberately outside git. Inside a nested repo, a normal commit is correct — the nearest work tree is the repo.
 

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

@@ -37,7 +37,7 @@ Only an exit-0 empty list means "no open PR". A non-zero exit means **unknown**
 
 **Branch policy.** Default: if on the base branch or detached HEAD, create a feature branch named from the work and say so. `branch:current` or a plain request keeps the checked-out branch (that run pushes and skips the PR). Never ask whether to branch. Forward the resolved choice to `sassy-commit`: `branch:new <name>` when this run creates a branch, else `branch:current`.
 
-**Base branch.** `<base>` is `repos[<repo dir>]` from a workspace config, else `git.default_branch`, else the probed remote HEAD, **confirmed with the user before use**. An explicit `base:<branch>` token wins over all of them — use it when this PR targets something other than the day-to-day base, such as a release PR aimed at `main` while work lands on `staging`. **Never use `defaultBranchRef` as the PR base when the config names one.** Pass it explicitly: `gh pr create --base <base>`.
+**Base branch.** `<base>` is `repos[<repo dir>]` from a workspace config, else `base_map[<current head>]` falling back to `base_map["*"]`, else the probed remote HEAD **confirmed with the user before use**. The map is the reason a release PR targets `main` while the work sits on `staging`, with no token passed. An explicit `base:<branch>` token wins over all of them — use it when this PR targets something other than the day-to-day base, such as a release PR aimed at `main` while work lands on `staging`. **Never use `defaultBranchRef` as the PR base when the config names one.** Pass it explicitly: `gh pr create --base <base>`.
 
 **Refused topologies.** From a `workspace` root there is no single PR to open — refuse in one line and point at `sassy-ship`, which owns the per-repo fan-out. With `git.repo: none`, refuse and say why. Neither ever pushes directly to a base branch.
 

package/skills/sassy-setup/SKILL.md

@@ -26,9 +26,9 @@ disable-model-invocation: true
    - **`none`** — confirm the intent: this folder is deliberately outside git, so commit, PR, and babysit refuse here.
    - **Artifacts** — offer the detected paths as the default; take overrides.
    - **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/`).
-   - **Base branch** — if detection printed no `default_branch`, ask; 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, so a repo that targets `dev` or `staging` reads `main` until a human corrects it.
+   - **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.
    - **`pr.*`** — default `babysit: true`, `merge: false`, `delete_branch: false`. Say plainly that `merge: true` authorizes merging every babysat PR in this project without asking.
-   - **Hooks** — offer, do not impose. Ask whether the project wants steps injected at `before_create`, `after_create`, `before_merge`, or `after_merge`, and write the skills they name. Leave them `[]` when they have 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.
+   - **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.
 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.
 5. **Wire the skills.** The suite is installed from upstream with the open `skills` CLI, which vendors the skill files into the project and pins them. Never copy skill files in by hand, never add the suite as a dependency.
 

package/skills/sassy-setup/assets/snapshot

@@ -120,7 +120,7 @@ resolve_branch() {
     fi
   fi
   local configured
-  configured="$(config_value default_branch || true)"
+  configured="$(config_value mirror_branch || true)"
   BRANCH="${configured:-main}"
 }
 

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

@@ -42,11 +42,13 @@ knowledge:
   write: true
 git:
   repo: origin              # <remote name> | workspace | none
-  remote: thekayshawn/knit  # workspace only: the snapshot mirror
-  default_branch: main      # repo base; workspace: the mirror branch
+  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: sibling dir -> PR base
   fe: dev
-  knit-ai-pipeline: master
 commit:
   branch: current           # current | new
 pr:
@@ -55,10 +57,10 @@ pr:
   delete_branch: false
 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
+    "*":
+      before_create: [tap2-version mode:auto]
+    staging:
+      before_create: []
 ```
 
 | Key | Default | Meaning |
@@ -70,14 +72,15 @@ hooks:
 | `knowledge.read` | `[docs/solutions, CONCEPTS.md]` | Paths scouted for prior learnings |
 | `knowledge.write` | `true` | `false` = this project takes no learnings |
 | `git.repo` | `origin` | Remote name, or a reserved value (below) |
+| `git.base_map` | probed `"*"` | Head branch → the base it targets. `"*"` is required |
 | `git.remote` | mirror of `git.repo` | Workspace only: mirror remote (URL or `owner/name`) |
-| `git.default_branch` | probed | Repo base branch; workspace: the mirror branch |
+| `git.mirror_branch` | `main` | Workspace only: the branch the mirror pushes to |
 | `repos` | `{}` | Workspace only: repo dir name → the base its PRs target |
 | `commit.branch` | `current` | `current` commits where you are; `new` cuts a branch |
 | `pr.babysit` | `true` | Whether close-out babysits the PR it opened |
 | `pr.merge` | `false` | `true` authorizes merging a single babysat PR |
 | `pr.delete_branch` | `false` | Delete the head branch once merged |
-| `hooks.pr.*` | `[]` | Project steps injected into the PR pipeline |
+| `hooks.pr.<pattern>.<point>` | `[]` | Project steps, keyed by the PR's head branch |
 
 Paths are relative to the config's own directory, never to the cwd.
 
@@ -91,8 +94,9 @@ Paths are relative to the config's own directory, never to the cwd.
 
 `workspace` and `none` are reserved words; a remote cannot be named either.
 
-`remote` and `default_branch` are conditional. In a repo config, `remote` is
-omitted (the repo name is `git.repo`) and `default_branch` is the repo's base.
+`base_map` is repo-only. `remote` and `mirror_branch` are workspace-only and
+describe the snapshot mirror — in a repo config the remote is simply
+the value of `git.repo`.
 In a workspace config, both describe **the snapshot mirror**: where it pushes,
 and its branch.
 
@@ -145,21 +149,30 @@ dropped; the refusal names why and what to run instead.
 even when the resolved config says `workspace`. Ran from `fe/`, work commits in
 `fe/`. Ran from the workspace root (no repo), the workspace rules above apply.
 
-**Base branch**, per affected repo:
+**Base branch of a head.** `base_map` answers one question — *given this head,
+what does a PR target?* — so there is no free-floating "default branch":
 
-1. `repos[<dir name>]` in a workspace config; `git.default_branch` in a repo config
-2. `git -C <repo> symbolic-ref --short refs/remotes/origin/HEAD`
-3. `gh repo view <repo> --json defaultBranchRef -q .defaultBranchRef.name`
-4. stop and ask — **never guess `main`**
+```
+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
 
-Steps 2 and 3 can only learn the **remote's default**, which is not necessarily the team's base: a repo whose PRs target `dev` or `staging` still reports `main`. So a probed base is reported as probed, and confirmed by a human before it is written. A wrong base aims PRs at the wrong branch — the exact failure a hand-kept integration table exists to prevent.
+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
+three-rung ladder is just one more line. The map must be acyclic, and `"*"` must
+exist — that is the rung everything falls back to.
 
-Because of that, a declared base differing from the remote default is **not**
-drift: `sassy-setup --check` reports the override and moves on. Only a missing
-base, or a repo with no `repos` entry, is drift.
+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.
 
-A repo on disk but absent from `repos` is a question, not a default. A `repos`
-entry with no directory on disk is ignored with one line.
+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
+map here.
 
 **Branch name**, one per run. Derived once from the plan slug or topic before the
 first commit, then passed to every repo. Multi-repo runs pass
@@ -180,7 +193,7 @@ recreate it. Never leave a PR aimed at the wrong base.
 `origin` → `git.remote` → stop and say setup is incomplete.
 
 **Mirror branch**: `SASSY_WORKSPACE_BRANCH` → the mirror's own
-`refs/remotes/origin/HEAD` → `git.default_branch` → `main`.
+`refs/remotes/origin/HEAD` → `git.mirror_branch` → `main`.
 
 **Knowledge read.** Every path in `knowledge.read` that exists is searched for
 prior learnings; a path that does not exist is skipped with one line. Absence of
@@ -188,13 +201,18 @@ matches is a fact worth stating, never evidence that no similar problem exists.
 
 ## Hooks
 
-A project injects its own steps into our pipeline by declaring them here. They are
-run by the skill that owns the moment, so they fire no matter which pipeline the
-user started. Nothing declared means nothing runs.
+A project injects its own steps into the PR pipeline. They run by the skill that
+owns the moment, so they fire whichever pipeline the user started. Nothing
+declared means nothing runs.
 
-Only the PR has hook points. Planning, phases, review, and commit do not: their
-extension point is `AGENTS.md` for rules, or a project skill the user invokes
-directly.
+**Keys are the head branch** — the branch the PR comes from, never the one it
+targets. `hooks.pr.staging` means *PRs whose source is staging*.
+
+| Key form | Matches |
+|----------|---------|
+| `staging` | that exact head |
+| `release/*` | a family; only one trailing `*` is allowed |
+| `"*"` | every other head |
 
 | Point | Owner | Fires |
 |-------|-------|-------|
@@ -203,25 +221,44 @@ directly.
 | `before_merge` | `sassy-babysit` | the PR looks ready **and** this run will merge it |
 | `after_merge` | `sassy-babysit` | this run observed the PR merged |
 
+### Resolution
+
+Per point, independently:
+
+1. the exact head
+2. the longest matching family, if the head starts with its prefix
+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.
+
+### Entries carry arguments
+
+An entry is `<skill>` or `<skill> <args…>`, split on the first whitespace. Args
+are passed to the hook verbatim — they are that skill's vocabulary, not ours. A
+hook skill documents the args it accepts and must not silently ignore one.
+
+Args are how a project pre-authorizes a step: `tap2-version mode:auto` runs
+versioning without its approval prompt. Treat it like `pr.merge: true` — visible
+in review, and commented when it is deliberate.
+
 ### Contract
 
 - **Resolution**: `<repo>/.agents/skills/<name>/SKILL.md`, nearest walking up.
-- **Names**: a skill the project owns, never one of ours. A `tap2-`/`knit-`
-  prefix is the convention when the name could be confused with a general
-  workflow; `version` is fine when it is plainly the project's.
+- **Names**: a skill the project owns, never one of ours.
 - **Order**: declared order, one worker each, sequential.
 - **Brief**: plan path, changed files, artifact paths, base, branch, commit hash,
   and the PR URL where one exists.
-- **Result**: `done`, `blocked`, or `needs-decision`. A decision comes back to the
-  orchestrator, which holds the gate — a worker never blocks on a prompt.
-- **Fail closed**: a missing file or a `blocked` result stops the pipeline and
-  names the hook. A mandatory step must never evaporate.
-- **Writes**: a hook may write files. Only `before_create` may also **commit**
-  them, because it runs after the pipeline's own commit; every other point must
-  leave the tree clean.
+- **Result**: `done`, `blocked`, or `needs-decision`; a decision comes back to the
+  orchestrator, which holds the gate.
+- **Fail closed**: a missing skill or a `blocked` result stops the pipeline.
+- **Writes**: only `before_create` may also commit, because it runs after the
+  pipeline's commit; every other point leaves the tree clean.
 - **Never**: push, open a PR, change `mode`, `branch`, or `merge`.
-- **Idempotent**: `after_merge` can be reached by a later run observing an already
-  merged PR, and `before_create` can run again on a re-ship.
+- **Idempotent**: `after_merge` can be reached by a later run observing an
+  already merged PR, and `before_create` can run again on a re-ship.
 - **Per PR**: in a workspace fan-out the hooks run once per PR.
 
 ### When they do not fire

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

@@ -10,12 +10,15 @@
 set -euo pipefail
 
 ROOT_ARG=""
+HEAD_ARG=""
 CHECK=0
 
 while (( $# )); do
   case "$1" in
     --root)   shift; [[ $# -ge 1 ]] || { echo "missing DIR after --root" >&2; exit 2; }; ROOT_ARG="$1" ;;
     --root=*) ROOT_ARG="${1#*=}" ;;
+    --head)   shift; [[ $# -ge 1 ]] || { echo "missing BRANCH after --head" >&2; exit 2; }; HEAD_ARG="$1" ;;
+    --head=*) HEAD_ARG="${1#*=}" ;;
     --check)  CHECK=1 ;;
     -h|--help) sed -n '2,10p' "${BASH_SOURCE[0]}" | sed 's|^# \{0,1\}||'; exit 0 ;;
     *) echo "unknown argument: $1" >&2; exit 2 ;;
@@ -102,6 +105,91 @@ hook_skill_path() { # $1 hook skill name — nearest .agents/skills/<name>/SKILL
   done
 }
 
+# --- config readers -------------------------------------------------------
+# The file is flattened to `path<TAB>value` with paths joined by unit separators,
+# which is enough to read the two nested maps we own (git.base_map, hooks.pr.*).
+US=$'\037'
+
+yaml_flat() {
+  awk -v us="$(printf '\037')" '
+    function ind(s,  m) { m = match(s, /^ */); return m ? RLENGTH : 0 }
+    {
+      line = $0; sub(/#.*$/, "", line)
+      if (line ~ /^[[:space:]]*$/) next
+      d = ind(line)
+      body = line; sub(/^[[:space:]]*/, "", body); sub(/[[:space:]]+$/, "", body)
+      if (body ~ /:$/) {
+        key = body; sub(/:$/, "", key); gsub(/"/, "", key)
+        while (sp > 0 && sd[sp] >= d) sp--
+        sd[++sp] = d; sk[sp] = key
+        next
+      }
+      if (body !~ /:/) next
+      key = body; sub(/:.*/, "", key); gsub(/"/, "", key)
+      val = body; sub(/^[^:]*:[[:space:]]*/, "", val); gsub(/^"|"$/, "", val)
+      path = ""
+      for (i = 1; i <= sp; i++) if (sd[i] < d) path = path (path == "" ? "" : us) sk[i]
+      print path (path == "" ? "" : us) key "\t" val
+    }' "$CONFIG"
+}
+
+yflat() { yaml_flat | awk -F'\t' -v p="$1" '$1 == p { print $2; exit }'; }
+
+list_items() {
+  printf '%s' "$1" | sed -e 's/^\[//' -e 's/\]$//' | tr ',' '\n' \
+    | sed -E 's/^[[:space:]]+//; s/[[:space:]]+$//; s/^"//; s/"$//' | grep -v '^$' || true
+}
+
+# map_match SECTION HEAD — exact key, then the longest matching family, then "*".
+# base_map uses it, and hooks use the same rule, so "which pattern applies" has
+# exactly one answer in the whole config.
+map_match() {
+  local section="$1" head="$2" pat stem best="" bestlen=0 v
+  v="$(yflat "git${US}${section}${US}${head}")"
+  [[ -n "$v" ]] && { printf '%s' "$v"; return; }
+  while IFS= read -r pat; do
+    case "$pat" in *"*") ;; *) continue ;; esac
+    [[ "$pat" == "*" ]] && continue
+    stem="${pat%\*}"
+    if [[ "$head" == "$stem"* ]] && (( ${#stem} > bestlen )); then
+      best="$pat"; bestlen=${#stem}
+    fi
+  done < <(yaml_flat | awk -F'\t' -v us="$US" -v sec="$section" \
+             '{n=split($1,a,us); if (n==3 && a[1]=="git" && a[2]==sec) print a[3]}' | sort -u)
+  if [[ -n "$best" ]]; then
+    v="$(yflat "git${US}${section}${US}${best}")"
+    [[ -n "$v" ]] && { printf '%s' "$v"; return; }
+  fi
+  yflat "git${US}${section}${US}*"
+}
+
+base_for_head() { map_match base_map "$1"; }
+
+hook_patterns() {
+  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
+}
+
+# hooks_for_head_point HEAD POINT — exact head, then the longest matching
+# family, then "*". A pattern that declares no entry for this point inherits.
+hooks_for_head_point() {
+  local head="$1" point="$2" pat stem best="" bestlen=0 v
+  v="$(yflat "hooks${US}pr${US}${head}${US}${point}")"
+  [[ -n "$v" ]] && { printf '%s' "$v"; return; }
+  while IFS= read -r pat; do
+    case "$pat" in *"*") ;; *) continue ;; esac
+    [[ "$pat" == "*" ]] && continue
+    stem="${pat%\*}"
+    if [[ "$head" == "$stem"* ]] && (( ${#stem} > bestlen )); then
+      best="$pat"; bestlen=${#stem}
+    fi
+  done < <(hook_patterns)
+  if [[ -n "$best" ]]; then
+    v="$(yflat "hooks${US}pr${US}${best}${US}${point}")"
+    [[ -n "$v" ]] && { printf '%s' "$v"; return; }
+  fi
+  printf '%s' "$(yflat "hooks${US}pr${US}*${US}${point}")"
+}
+
 detect_base() {
   local dir="$1" b
   b="$(git -C "$dir" symbolic-ref --short refs/remotes/origin/HEAD 2>/dev/null | sed 's|^origin/||' || true)"
@@ -156,7 +244,7 @@ case "$TOPOLOGY" in
     ;;
   workspace)
     MIRROR_REMOTE="$(config_value remote 2>/dev/null || true)"
-    MIRROR_BRANCH="$(config_value default_branch 2>/dev/null || true)"
+    MIRROR_BRANCH="$(config_value mirror_branch 2>/dev/null || true)"
     MIRROR_BRANCH="${MIRROR_BRANCH:-main}"
     ;;
 esac
@@ -194,17 +282,35 @@ if (( CHECK )); then
   fi
 
   if [[ "$TOPOLOGY" == "repo" ]]; then
-    configured_base="$(config_value default_branch 2>/dev/null || true)"
-    [[ -n "$configured_base" ]] || DEFAULT_BRANCH="$(detect_base "$ROOT")"
-    if [[ -z "$configured_base" ]]; then
-      bad "git.default_branch is unset — name the branch new work is cut from"
-    elif [[ -n "$DEFAULT_BRANCH" && "$configured_base" != "$DEFAULT_BRANCH" ]]; then
-      # A team base is a policy choice: staging, dev, or the release branch can
-      # all differ from the remote default. Report it, do not call it drift.
-      note "  default_branch '$configured_base' overrides the remote default '$DEFAULT_BRANCH' — expected when PRs target a team base"
+    if [[ -n "$(yflat "git${US}default_branch")" ]]; then
+      bad "git.default_branch is gone — use git.base_map with a \"*\" entry"
+    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
+      while IFS= read -r pat; do
+        [[ -n "$pat" ]] || continue
+        case "$pat" in
+          "*") ;;
+          *"*") [[ "${pat%\*}" != *"*" ]] || bad "base_map key '$pat': only one trailing * is allowed" ;;
+        esac
+      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")"
+        cur="$head_ref"; hops=0
+        while [[ -n "$cur" ]] && (( hops < 8 )); do
+          next="$(yflat "git${US}base_map${US}${cur}")"
+          [[ -z "$next" ]] && break
+          cur="$next"; hops=$((hops + 1))
+          if [[ "$cur" == "$head_ref" ]]; then
+            bad "git.base_map cycles through '$head_ref'"; break
+          fi
+        done
+      else
+        note "  detached HEAD — pass --head <branch> to see the resolved base"
+      fi
     fi
-    configured_remote="$(config_value remote 2>/dev/null || true)"
-    [[ -z "$configured_remote" ]] || bad "git.remote is set but git.repo is not workspace"
   fi
 
   if [[ "$TOPOLOGY" == "workspace" ]]; then
@@ -235,34 +341,37 @@ if (( CHECK )); then
     done < <(nested_repos)
   fi
 
-  # Hooks: every declared name resolves to a project skill, and none may be ours.
-  if grep -q '^hooks:' "$CONFIG" 2>/dev/null; then
-    while IFS= read -r hline; do
-      [[ "$hline" == " "* ]] || continue          # only nested lines belong here
-      hkey="$(printf '%s' "$hline" | sed -nE 's/^[[:space:]]*([A-Za-z_]+):.*/\1/p')"
-      case "$hkey" in
-        "") continue ;;
-        pr) continue ;;
-        before_create|after_create|before_merge|after_merge) ;;
-        *) bad "unknown hook point '$hkey' under hooks:"; continue ;;
-      esac
-      hlist="$(printf '%s' "$hline" | sed -nE 's/^[^:]+:[[:space:]]*\[([^]]*)\].*/\1/p')"
-      [[ -n "$hlist" ]] || continue
-      while IFS= read -r hraw; do
-        hname="$(printf '%s' "$hraw" | sed -E 's/#.*$//; s/^[[:space:]]+//; s/[[:space:]]+$//; s/^["'\'']//; s/["'\'']$//')"
-        [[ -n "$hname" ]] || continue
-        case "$hname" in
-          sassy-*) bad "hook $hkey: '$hname' is one of our skills — hooks are project skills only" ;;
-          *)
-            if hook_skill_path "$hname" >/dev/null; then
-              note "  hook $hkey → $hname"
-            else
-              bad "hook $hkey: '$hname' not found at .agents/skills/$hname/SKILL.md"
-            fi
-            ;;
+  # Hooks: head-scoped, so `staging` means "the PR is from staging".
+  if [[ -n "$(yflat "hooks${US}pr${US}before_create")" ]]; then
+    bad "hooks.pr.<point> is now nested by head branch — write hooks.pr.\"*\".<point>"
+  fi
+  while IFS= read -r pat; do
+    [[ -n "$pat" ]] || continue
+    case "$pat" in
+      "*") ;;
+      *"*") [[ "${pat%\*}" != *"*" ]] || bad "hook pattern '$pat': only one trailing * is allowed" ;;
+    esac
+    for point in before_create after_create before_merge after_merge; do
+      val="$(yflat "hooks${US}pr${US}${pat}${US}${point}")"
+      [[ -n "$val" ]] || continue
+      while IFS= read -r entry; do
+        [[ -n "$entry" ]] || continue
+        name="${entry%% *}"
+        case "$name" in
+          sassy-*) bad "hooks.$pat.$point: '$name' is one of our skills — hooks are project skills only" ;;
+          *) hook_skill_path "$name" >/dev/null 2>&1 \
+               || bad "hooks.$pat.$point: '$name' not found at .agents/skills/$name/SKILL.md" ;;
         esac
-      done < <(printf '%s\n' "$hlist" | tr ',' '\n')
-    done < <(sed -n '/^hooks:/,/^[a-z]/p' "$CONFIG")
+      done < <(list_items "$val")
+    done
+  done < <(hook_patterns)
+
+  # Resolve for one head, so nobody has to merge maps in their head.
+  if [[ -n "$HEAD_ARG" && "$TOPOLOGY" == "repo" ]]; then
+    for point in before_create after_create before_merge after_merge; do
+      resolved="$(hooks_for_head_point "$HEAD_ARG" "$point")"
+      note "  head '$HEAD_ARG' → $point: $( [[ -n "$resolved" ]] && printf '%s' "$resolved" || printf 'none' )"
+    done
   fi
 
   for key in plans solutions handbooks concepts; do
@@ -325,15 +434,18 @@ case "$TOPOLOGY" in
 # --- Git ------------------------------------------------------------------
 # repo: a remote name (this folder is the repo) | workspace (repos live below,
 #       this folder is not a repo) | none (no git anywhere here).
-# default_branch: what new branches are cut from, and what PRs target.
+# base_map: the base for a HEAD branch, so a PR targets the right rung.
+#   "*" is ordinary work; add a rung for a branch that releases elsewhere.
 git:
 EOF
     kv repo "$REPO_NAME" 0
+    printf '  base_map:\n'
     if [[ -n "$DEFAULT_BRANCH" ]]; then
-      kv default_branch "$DEFAULT_BRANCH" 34 '# probed — confirm it is the team base'
+      printf '    "*": %s   # probed — confirm this is where ordinary work branches from\n' "$DEFAULT_BRANCH"
     else
-      kv default_branch "<confirm by hand>" 34 '# base for branches and PRs; never guessed'
+      printf '    "*": %s   # base for ordinary work; never guessed\n' "<confirm by hand>"
     fi
+    printf '    # staging: main   # uncomment when a branch releases somewhere else\n'
     cat <<'EOF'
 
 # workspace only: each nested repo folder -> the base its PRs target
@@ -347,12 +459,13 @@ EOF
 # --- Git ------------------------------------------------------------------
 # repo: workspace means repos live below and this folder is not a repo.
 # remote: the snapshot mirror (GitHub owner/name or URL), required here.
-# default_branch: the mirror's branch, not any nested repo's base.
+# mirror_branch: the branch the mirror pushes to. Not a PR base — nested repos
+#   carry their own, and a workspace has no branches of its own.
 git:
 EOF
     kv repo workspace 0
     kv remote "${MIRROR_REMOTE:-<set the snapshot mirror, owner/name or URL>}" 0
-    kv default_branch "$MIRROR_BRANCH" 0
+    kv mirror_branch "$MIRROR_BRANCH" 0
     cat <<'EOF'
 
 # --- Repos ----------------------------------------------------------------
@@ -389,7 +502,7 @@ cat <<'EOF'
 
 # --- Commit ---------------------------------------------------------------
 # current: commit on the checked-out branch.
-# new: cut a branch from origin/<default_branch>; name it in multi-repo runs so
+# new: cut a branch from the base map for the current head; name it in multi-repo runs so
 #      every repo gets the same branch name.
 commit:
 EOF
@@ -405,17 +518,22 @@ kv delete_branch false 24 '# true | false — delete the head branch once merged
 cat <<'EOF'
 
 # --- Hooks ----------------------------------------------------------------
-# Project steps injected into the PR pipeline. Each entry is a skill name,
-# resolved at .agents/skills/<name>/SKILL.md, nearest walking up. Declared
-# order, one worker each, and a declared-but-missing skill fails closed.
-#   before_create — after the commit, before the PR opens (may commit its output)
-#   after_create  — the PR was just created
-#   before_merge  — this run is about to merge the PR
-#   after_merge   — this run observed the PR merged
+# Project steps injected into the PR pipeline, keyed by the HEAD branch — the
+# branch the PR comes from, never the one it targets. `"*"` is the default;
+# a name overrides per point, and `release/*` matches a family. Each entry is
+# `<skill> <args…>`, resolved at .agents/skills/<name>/SKILL.md; args are passed
+# to the skill verbatim. Declared order, one worker each, missing skill fails closed.
 hooks:
   pr:
+    "*":
+EOF
+kv before_create '[]' 30 '# after the commit, before the PR opens' '      '
+kv after_create '[]' 30 '# the PR was just created' '      '
+kv before_merge '[]' 30 '# this run is about to merge' '      '
+kv after_merge '[]' 30 '# this run observed the merge' '      '
+cat <<'EOF'
+    # staging:            # per-point override for one head branch
+    #   before_create: []
+    # release/*:          # a family of heads
+    #   after_merge: [notify mode:auto]
 EOF
-kv before_create '[]' 24 '# after the commit, before the PR opens' '    '
-kv after_create '[]' 24 '# the PR was just created' '    '
-kv before_merge '[]' 24 '# this run is about to merge' '    '
-kv after_merge '[]' 24 '# this run observed the merge' '    '

package/skills/sassy-skill/SKILL.md

@@ -6,7 +6,7 @@ description: >-
   the rules and release steps that location requires. Use when asked to create a
   skill, turn a workflow into a skill, fix a description or triggering,
   restructure a bloated skill, or retune an existing one.
-argument-hint: "[create|retune] [name, idea, or skill path]"
+argument-hint: "[mode:create|retune|verify] [name, idea, or skill path]"
 disable-model-invocation: true
 ---
 
@@ -14,6 +14,8 @@ disable-model-invocation: true
 
 **Outcome:** a well-formed Agent Skill at a location the user chose, or an existing skill improved and re-verified. The harness loads it with no diagnostics.
 
+**Modes.** `mode:create` writes a new skill. `mode:retune` changes the smallest thing that fixes a named failure in an existing skill. `mode:verify` checks an existing skill against the checklist and reports — it edits nothing. Omitted, detect it from the argument: something that already resolves to a skill directory is `retune`, or `verify` when the user only asked whether it is any good; anything else is `create`. State the mode you picked and why; when both are plausible, ask instead of guessing.
+
 **Locations are not interchangeable** — they decide who gets the skill, how it ships, and what it may be called. Ask before writing.
 
 **Scope:** skills only — not extensions, packages, or prompt templates.
@@ -54,7 +56,7 @@ Paths in the table are the defaults. Harnesses also read `skills` arrays in sett
 
 ## Workflow
 
-1. **Intake.** What the skill does, when it should trigger, and **where it lives** — internal, project, or user (see above). Ask; do not infer from the cwd. For a retune, read the existing skill and name the specific failure (won't trigger, too long, wrong steps, stale, wrong scope).
+1. **Intake.** Settle the mode (above), then what the skill does, when it should trigger, and **where it lives** — internal, project, or user (see above). Ask; do not infer from the cwd. In `mode:retune`, read the existing skill and name the specific failure (won't trigger, too long, wrong steps, stale, wrong scope). In `mode:verify`, read it, run the checklist and Verify, report, and stop without writing.
 2. **Choose the shape.** Single file, or `SKILL.md` + `references/` per the rule above.
 3. **Write the frontmatter.** A description that states both what and when.
 4. **Write the body.** Outcome, a hard-rules table, the workflow, and reference pointers. Plain English. Structured output where the skill returns a result. Match this setup's house style.
@@ -72,7 +74,7 @@ Paths in the table are the defaults. Harnesses also read `skills` arrays in sett
 
 ## Retune
 
-When asked to retune or improve a skill, change the **smallest** thing that fixes the named failure:
+In `mode:retune`, change the **smallest** thing that fixes the named failure:
 
 - **Won't trigger** → rewrite the description (what + when, concrete verbs).
 - **Too long / bloated** → extract conditional content to `references/`, or delete what never gets used.
@@ -83,6 +85,8 @@ Re-verify after any retune.
 
 ## Verify
 
+Run this at the end of `create` and `retune`, and as the whole job in `mode:verify`.
+
 - `/reload`.
 - Check pi's startup output for warnings about the skill.
 - Run `/skill:<name>` and confirm it loads and behaves.