@sassywares/skills 0.5.6 → 0.5.7

package/README.md

@@ -205,7 +205,7 @@ flowchart LR
   I -->|changes| H
   I --> Q{Manual QA}
   Q -->|fails| H
-  Q -->|passes, via sassy-work| J[Commit on current branch and stop]
+  Q -->|passes, via sassy-work| J[Commit on the run branch and stop]
   Q -->|passes, via sassy-lfg| K[sassy-ship]
   K --> L{Ship review}
   L -->|approve or mode:auto| M[Commit, PR, babysit]
@@ -215,7 +215,7 @@ Option 1 produces a durable plan with phased slices and manual QA tables. Option
 
 `sassy-work` handles one phase and hands off the next. `sassy-lfg` drains the whole plan in one session. Both delegate to `sassy-cycle` and stop at one gate carrying code approval plus the manual QA checklist; nothing is `Done`, committed, or shipped until both pass. With an in-context brief there are no QA rows, so the gate is code approval alone.
 
-Work always commits to the current branch; `sassy-ship` creates the shipping branch at close-out when the checked-out branch is the repo default.
+The branch is cut once, before the first change, by `sassy-work` or `sassy-lfg` — never at commit time — and `sassy-ship` never creates it. `commit.branch` (default `new`) decides whether the run cuts one at all; see [Branching](#branching).
 
 `sassy-ship` is the close-out. It summarizes what is about to ship and waits, unless the caller passed `mode:auto`.
 

package/package.json

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

package/skills/sassy-commit/SKILL.md

@@ -40,7 +40,12 @@ Treat the reads as a snapshot; re-read branch and staged set right before commit
 
 0. **Gather** the context above.
 1. **Nothing to commit** — if there are no staged, modified, or untracked files, say so and stop.
-2. **Branch** — honor the `branch` option. With `branch:new`, cut from the base: `git fetch <remote> <base>`, then `git checkout -b <name> <remote>/<base>`, then confirm `git merge-base HEAD <remote>/<base>` is `<remote>/<base>`. If that ancestry check fails, the branch was cut from the wrong base — recreate it, never push it. If the name already exists, reuse it when it descends from the base; fork a suffix only when it has diverged, and never cut a second branch off the base for the same work. With `branch:current`, commit on the checked-out branch. With no token and no `commit.branch`, treat it as `new` and cut one. **Base means any `base_map` value, not just `origin/HEAD`**: `bash .agents/skills/sassy-setup/scripts/detect.sh --branch` answers it, and a branch it reports as `on-base` must be named in the summary you return — a warning nobody sees protects nothing.
+2. **Branch** — honor the `branch` option. With `branch:new`, cut from the base: `git fetch <remote> <base>`, then `git checkout -b <name> <remote>/<base>`, then confirm `git merge-base HEAD <remote>/<base>` is `<remote>/<base>`. If that ancestry check fails, the branch was cut from the wrong base — recreate it, never push it. If the name already exists, reuse it when it descends from the base; fork a suffix only when it has diverged, and never cut a second branch off the base for the same work.
+
+   With `branch:current`, commit on the checked-out branch — but check what it is first with the `sassy-setup` skill's `scripts/detect.sh --branch`. **Base means any `base_map` value, not just `origin/HEAD`.** Resolve the two facts before committing:
+   - `state: on-base` with `policy: new` means the caller skipped the branch decision. **Stop and report** — do not commit. A warning inside a subagent's summary has already failed to protect a shared branch once; this is a stop, not a notice.
+   - `commit-here` means the config or a token explicitly chose to commit here. Proceed, and name the branch in the summary you return.
+   - Any other state: commit on the checked-out branch.
 3. **Convention** — match the project's existing commit style; else the recent log pattern; else conventional commits (`type(scope): description`). When `fix`/`feat` both fit, default to `fix:`.
 4. **Logical commits** — if changed files clearly split into distinct concerns, make separate commits (file level, 2–3 max, never `git add -p`). If ambiguous, one commit.
 5. **Message** — imperative subject naming the outcome, not the file list. Body only when the motivation is not obvious.

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

@@ -18,6 +18,8 @@ disable-model-invocation: true
 
 **Config.** Resolve `.sassywares/config.yaml` (nearest, walking up) per the `sassy-setup` skill's `references/config.md`. `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. Precedence is explicit token > session instruction > config > skill default, and a token is explicit only when the **caller** supplied it; never pass this skill's own default as a token.
 
+**Which branch is a base.** Use the `sassy-setup` skill's `scripts/detect.sh --branch`: a base is any `base_map` value, not `origin/HEAD`. Probing `origin/HEAD` alone calls `staging` "not a base" in a repo whose `base_map` routes `"*"` there, which is how a run once committed phase work straight onto a shared integration branch.
+
 **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
@@ -37,7 +39,7 @@ gh pr list --head <branch> --state open --json url,number
 
 Only an exit-0 empty list means "no open PR". A non-zero exit means **unknown** — resolve auth/connectivity first, never treat it as "none". Probe output is a snapshot; re-check branch/remote/PR state right before the push and the PR create.
 
-**Branch policy.** The run's branch is normally already decided: `sassy-work` and `sassy-lfg` cut it at the start via `sassy-setup`'s `references/branching.md`, and `sassy-ship` forwards `branch:current`. So the default here is to commit on the checked-out branch when it is not a base. Only when it *is* a base or a detached HEAD — a bare invocation with no orchestrator above it — 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>` only when this run creates a branch, else `branch:current`.
+**Branch policy.** The run's branch is normally already decided: `sassy-work` and `sassy-lfg` cut it at the start via the `sassy-setup` skill's `references/branching.md`, and `sassy-ship` forwards `branch:current`. So the default here is to commit on the checked-out branch when `state` is not `on-base`. Only when it *is* `on-base` or `detached` — a bare invocation with no orchestrator above it — 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>` only when this run creates a branch, else `branch:current`.
 
 **Base branch.** `<base>` is `base_map[<current head>]` from the nearest config — a nested repo's own config wins over the workspace's `repos[<dir>]` — 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>`.
 

package/skills/sassy-lfg/SKILL.md

@@ -38,7 +38,7 @@ A brief has no QA table, so its gate is code approval alone. Never invent, enabl
 ## Steps
 
 1. **Load the plan.** Read the plan and its Phase tracking table. If phases are already `In progress` from an interrupted run, ask once whether to resume at the gate or rerun those cycles, then continue from the answer.
-2. **Resolve the branch, before touching code.** Follow the `sassy-setup` skill's `references/branching.md` with this run's `branch:` token, if any. LFG runs every phase in one session, so the branch is cut once here and every phase commits onto it. Report the branch and its start point in the gate.
+2. **Resolve the branch, before touching code.** Follow the `sassy-setup` skill's `references/branching.md` with this run's `branch:` token, if any. LFG runs every phase in one session, so the branch is cut once here and every phase commits onto it. Report the branch and its start point in the gate. A `stop-and-ask` here stops the run before any phase starts.
 3. **Run every phase, in order.** For each phase not `Done`:
    - Set the phase `In progress`, then load the `sassy-cycle` skill and follow it, with work brief = the phase's goal/work/"Done when", and intent reference = the plan path and phase.
    - On `Status: done` and `Validator: Conforms`, leave the phase `In progress` — its QA rows are still owed, and only the gate closes them.
@@ -62,7 +62,7 @@ Every worker brief this run dispatches must include:
 
 When the argument is not a plan path, the brief is the one phase:
 
-1. Resolve the branch exactly as the plan path does — `references/branching.md`, this run's `branch:` token — before the cycle runs.
+1. Resolve the branch exactly as the plan path does — the `sassy-setup` skill's `references/branching.md`, this run's `branch:` token — before the cycle runs.
 2. Run one `sassy-cycle` with the brief as the work brief and its decisions / done-when as the intent reference. Do not split it into multiple phases.
 3. Present the code approval gate with no QA checklist, and wait.
 4. On code approval, run `sassy-ship`. Do not run `sassy-plan` or write a plan file.
@@ -72,7 +72,7 @@ When the argument is not a plan path, the brief is the one phase:
 | Rule | Requirement |
 |------|-------------|
 | Orchestrator only | Delegate every phase to `sassy-cycle`. Never read source or edit code. |
-| Branch before code | Resolve the branch per `references/branching.md` before any phase runs, so no change lands on a base branch. |
+| Branch before code | Resolve the branch per the `sassy-setup` skill's `references/branching.md` before any phase runs, so no change lands on a base branch. |
 | Phases in plan order | Phases run one after another, in plan order. |
 | Done needs both gates | Mark a phase `Done` only when the user approves the code and every QA row for it is `Done`. |
 | QA rows follow the user | Tick a QA row `Done` only from the user's explicit confirmation; keep unreported rows `Pending`; log a failed row as a finding for one more cycle. |

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

@@ -6,37 +6,49 @@ three cannot drift apart the way three hand-copied paragraphs would.
 
 ## Resolve
 
+Run the `sassy-setup` skill's `scripts/detect.sh` — by skill name, never by an
+absolute install path, because a consumer's copy may live in `.agents/skills/`
+or anywhere else a harness puts it:
+
 ```bash
-bash .agents/skills/sassy-setup/scripts/detect.sh --branch [--policy current|new]
+bash scripts/detect.sh --branch [--policy infer|current|new] [--name BRANCH]
 ```
 
 `--policy` is the `branch:` token: `infer` (the default), `current`, or `new`.
 Omit it to let `commit.branch` decide; `branch:infer` means exactly that and is
-passed only to be explicit.
+passed only to be explicit. `--name` is optional and answers one question early:
+which base a PR from the branch you are about to name will target.
+
+The detector is read-only, but not network-free: when the config names no base it
+falls back to the remote HEAD, which may shell out to `gh`.
 
-Output:
+## Output — repo topology
 
 | Key | Meaning |
 |---|---|
+| `note` | present only when the config is unusable, e.g. a bad `commit.branch`; it names the fallback taken |
 | `topology` | `repo`, `workspace`, or `none` |
-| `configured` | `commit.branch` from the config, or `none` |
+| `config` | the config file in force, or `none` |
+| `configured` | `commit.branch` from the config (after validation), or `none` |
 | `policy` | what actually applies: the token, else the config, else `new` |
-| `head` | the checked-out branch, or `none` when detached |
+| `checked-out` | printed only with `--head`, when you asked about a branch you are not on |
+| `head` | the branch being decided for |
 | `state` | `on-base`, `on-branch`, `detached`, or `no-git` |
-| `action` | `create`, `reuse`, `commit-here`, or `refuse` |
-| `start-point` | where a new branch is cut from — `origin/<head>`, never local `HEAD` |
-| `unpublished` | commits on local `<head>` that are not on `origin/<head>` |
+| `action` | `create`, `reuse`, `commit-here`, `stop-and-ask`, or `refuse` |
+| `start-point` | where a new branch is cut from — `<remote>/<head>`, or `none` |
+| `unpublished` | commits on local `<head>` missing upstream, `0`, `unknown`, or `n/a` |
 | `pr-base` | the base a PR from this run targets |
-| `pr-base-source` | `config`, `probed`, or `unknown` — a probed base is confirmed with the user before use |
+| `pr-base-source` | `config`, `probed` (confirm it with the user), or `unknown` |
+| `pr-base-final` | `yes` when `--name` resolved it for the real branch name, else `no` |
 
-A base branch is **any `base_map` value**, plus the remote default. That is why
-`staging` counts as a base in a repo whose `base_map` routes `"*"` to it: the
-remote default alone is not the base, it is only one of them.
+A base branch is **any `base_map` value**, plus the `repos` rung, plus the remote
+default. That is why `staging` counts as a base in a repo whose `base_map` routes
+`"*"` to it: the remote default alone is not the base, it is only one of them.
 
 ## Token authorship
 
 Pass `--policy` only when the **caller** asked for it — the user typed
-`branch:new`, or an earlier gate of this same run authorized it.
+`branch:new`, or the run's own gate summary already recorded the decision.
 
 Never pass a token that is merely this skill's own default. Doing that launders
 a default into "explicit token", which outranks the project's config and makes
@@ -47,16 +59,23 @@ config. This applies to every token these skills forward, not just `branch`.
 
 ### `create`
 
-1. `unpublished` must be `0`. If not, **stop and ask**: cutting from local HEAD
-   would carry commits stranded on the base into the new branch, and cutting
-   from `origin/<head>` would abandon them. Name the count, the branch, and the
-   choice.
-2. Name it `<type>/<slug>` from the plan filename or the topic, deterministically,
+1. Run `git fetch <remote> <head>` **before** trusting the detector: a stale
+   upstream ref reads as "unpublished commits" and produces a false stop.
+2. `unpublished` must be `0` and `start-point` must not be `none`. Anything else
+   is a stop: cutting from local HEAD would carry commits stranded on the base
+   into the new branch, and cutting from a missing upstream ref silently does
+   exactly that. Name the count, the branch, and the choice.
+3. Name it `<type>/<slug>` from the plan filename or the topic, deterministically,
    so a retried run converges on the same name instead of forking `-2`.
-3. If that name already exists: reuse it when it descends from `start-point`;
+4. Re-run with `--name <name>` and take `pr-base` from that answer: a name like
+   `release/1.2` or `hotfix/x` matches a `base_map` family and retargets the PR,
+   and it also changes which `hooks.pr` pattern applies — a plan slug containing
+   "release" is not a neutral name.
+5. If the name already exists: reuse it when it descends from `start-point`;
    stop and ask when it has diverged.
-4. `git fetch <remote> <head>`, then `git checkout -b <name> <start-point>`.
-5. Report the branch, the start point, and `pr-base`.
+6. `git checkout -b <name> <start-point>`. Uncommitted work comes along — say so
+   in the gate summary if the tree was dirty.
+7. Report the branch, the start point, and `pr-base`.
 
 ### `reuse`
 
@@ -72,18 +91,34 @@ committing on the base branch is intended. Proceed, and say in the run's gate
 summary that the commits are landing on `<head>` and that `pr-base` is
 `<pr-base>`. Never infer this from a skill default.
 
+### `stop-and-ask`
+
+The base has commits that never reached the remote. Present the choice — publish
+them, move them to the new branch, or drop them — and take the answer. Never
+resolve it by cutting anyway.
+
 ### `refuse`
 
-Detached HEAD with `policy: current`, or `topology: none`. Report and stop;
-there is no branch to commit to.
+Detached HEAD without a policy that permits it, `topology: none`, `git.repo:
+none`, or no upstream ref to cut from. Report the `reason` line and stop; there
+is no branch to commit to.
 
 ## Workspace
 
 Resolve once at the workspace root; the run uses **one branch name across every
-nested repo**. The detector prints each repo's head and state, so cut inside the
-repos whose state is `on-base` and reuse the rest. A nested repo carrying its own
-`commit.branch` that disagrees is printed as `drift` — that is a config bug to
-report, not a per-repo override, because one run cannot follow two policies.
+nested repo**. The detector prints one line per repo:
+
+```
+repo fe: head=staging state=on-base base=staging start-point=origin/staging unpublished=0 action=create
+drift fe: commit.branch=current
+```
+
+`base` is that repo's own `base_map["*"]` when it carries a config, else its
+`repos[<dir>]` rung. Apply `action` per repo — cut where it is `create`, keep the
+rest — and stop if any repo reports `stop-and-ask` or `refuse`. A nested repo
+carrying its own `commit.branch` that disagrees is printed as `drift` — a config
+bug to report, not a per-repo override, because one run cannot follow two
+policies.
 
 ## After the branch exists
 

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

@@ -25,14 +25,20 @@ explicit token in the request  >  instruction in this session
 >  .sassywares/config.yaml  >  skill default
 ```
 
-**A token is explicit only when the caller supplied it** — the user typed it, or
-an earlier gate of the same run authorized that side effect. A skill must never
-pass its own default as a token, to another skill or to itself: once a default
-sits in the token slot, nothing downstream can tell it apart from a user's
-choice, so it silently outranks the project's config. A skill defers to config
-by **omitting** the token, never by passing a value it invented. That is how
-`commit.branch` became unreachable while every skill still read as if it
-explained the rule correctly.
+**A token is explicit only when the caller supplied it.** Three sources qualify:
+
+1. the user typed it in the request;
+2. an approval gate earlier in the same run authorized that side effect;
+3. the run's own orchestration decision, already recorded in its gate summary —
+   for example `sassy-ship` passing `babysit:off` because its step 6 owns the
+   babysit, or `sassy-work` forwarding `branch:current` because its step 2 cut
+   the branch and the gate showed it.
+
+What never qualifies is **this skill's own default**. Once a default sits in the
+slot, nothing downstream can tell it apart from the user's choice, so it
+silently outranks the project's config. A skill defers to config by **omitting**
+the token, never by passing a value it invented. That is how `commit.branch`
+became unreachable while every skill still read as if it explained the rule.
 
 Read it once per run. An orchestrator resolves every config-backed value and
 passes the resolved values into subagent briefs; subagents never re-read the
@@ -59,7 +65,7 @@ git:
 repos:                      # workspace only: sibling dir -> PR base
   fe: dev
 commit:
-  branch: current           # current | new
+  branch: new               # current | new
 pr:
   babysit: true
   merge: false

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

@@ -13,11 +13,14 @@
 # --policy takes infer|current|new: the skill-level token. infer (the default)
 # defers to commit.branch in the config, and new is the fallback when the config
 # is silent. --branch is read-only; it prints the decision, it never cuts.
+# --name BRANCH resolves pr-base for the name a run is about to pick, because a
+# new name can match a base_map family (release/*) and retarget the PR.
 set -euo pipefail
 
 ROOT_ARG=""
 HEAD_ARG=""
 POLICY_ARG=""
+NAME_ARG=""
 CHECK=0
 BRANCH=0
 
@@ -29,9 +32,11 @@ while (( $# )); do
     --head=*) HEAD_ARG="${1#*=}" ;;
     --policy) shift; [[ $# -ge 1 ]] || { echo "missing POLICY after --policy" >&2; exit 2; }; POLICY_ARG="$1" ;;
     --policy=*) POLICY_ARG="${1#*=}" ;;
+    --name)   shift; [[ $# -ge 1 ]] || { echo "missing BRANCH after --name" >&2; exit 2; }; NAME_ARG="$1" ;;
+    --name=*) NAME_ARG="${1#*=}" ;;
     --branch) BRANCH=1 ;;
     --check)  CHECK=1 ;;
-    -h|--help) sed -n '2,14p' "${BASH_SOURCE[0]}" | sed 's|^# \{0,1\}||'; exit 0 ;;
+    -h|--help) sed -n '2,15p' "${BASH_SOURCE[0]}" | sed 's|^# \{0,1\}||'; exit 0 ;;
     *) echo "unknown argument: $1" >&2; exit 2 ;;
   esac
   shift
@@ -39,6 +44,9 @@ done
 
 START="${ROOT_ARG:-$PWD}"
 [[ -d "$START" ]] || { echo "not a directory: $START" >&2; exit 2; }
+# --branch prints a decision; --check validates a config. One at a time, or the
+# second is silently ignored.
+(( BRANCH && CHECK )) && { echo "--branch and --check are separate modes; run them one at a time" >&2; exit 2; }
 # Absolute, or the walk-up loop below re-reads "." forever.
 START="$(cd "$START" && pwd -P)"
 
@@ -419,6 +427,16 @@ if (( CHECK )); then
     [[ -n "$val" ]] && note "  artifacts.$key: $val"
   done
 
+  # commit.branch steers whether a run may touch a base branch, so an invalid
+  # value is reported rather than silently ignored.
+  val="$(yflat "commit${US}branch" 2>/dev/null || true)"
+  if [[ -n "$val" ]]; then
+    case "$val" in
+      current|new) note "  commit.branch: $val" ;;
+      *) bad "commit.branch '$val' is not current|new" ;;
+    esac
+  fi
+
   if (( drift )); then exit 1; fi
   note "  config matches the tree"
   exit 0
@@ -439,64 +457,145 @@ if (( BRANCH )); then
     *) echo "unknown --policy: $policy (expected infer, current, or new)" >&2; exit 2 ;;
   esac
   configured="$(yflat "commit${US}branch" 2>/dev/null || true)"
-  [[ "$policy" == "infer" ]] && policy="${configured:-new}"
-
-  # base_heads prints every branch this config treats as a base: each base_map
-  # value, plus the remote default it inherits from. With no config to speak,
-  # the probed remote HEAD is the only base there is.
-  base_heads() {
-    local v out=""
-    out="$(yaml_flat "$CONFIG" 2>/dev/null | awk -F'\t' -v us="$US" \
-      '{n=split($1,a,us); if (n==3 && a[1]=="git" && a[2]=="base_map") print $2}' | sort -u || true)"
-    if [[ "$TOPOLOGY" == "repo" ]]; then
-      v="$(git -C "$ROOT" symbolic-ref --short refs/remotes/origin/HEAD 2>/dev/null | sed 's|^origin/||' || true)"
+  note=""
+  if [[ -n "$configured" && "$configured" != "current" && "$configured" != "new" ]]; then
+    # A soft config error must not become a silently wrong branch decision.
+    note="commit.branch '$configured' is not current|new; using new"
+    configured=""
+  fi
+  if [[ "$policy" == "infer" ]]; then
+    policy="${configured:-new}"
+  fi
+
+  # base_heads_in DIR — every branch DIR's config treats as a base: each
+  # base_map value, the repos[<dir>] rung, and the remote default. A workspace
+  # has no base_map of its own, so repos[] is what names its bases; reading
+  # base_map alone reported every nested repo as on-branch and let runs commit
+  # onto staging, which is the bug this whole mode exists to stop.
+  base_heads_in() {
+    local dir="$1" r v out=""
+    if [[ -f "$dir/.sassywares/config.yaml" ]]; then
+      out="$(yaml_flat "$dir/.sassywares/config.yaml" 2>/dev/null | awk -F'\t' -v us="$US" \
+        '{n=split($1,a,us); if (n==3 && a[1]=="git" && a[2]=="base_map") print $2}' | sort -u || true)"
+    fi
+    v="$(yflat "repos${US}$(basename "$dir")" 2>/dev/null || true)"
+    [[ -n "$v" ]] && out="$out"$'\n'"$v"
+    r="$(remote_name "$dir")"
+    if [[ -n "$r" ]]; then
+      v="$(git -C "$dir" symbolic-ref --short "refs/remotes/$r/HEAD" 2>/dev/null | sed "s|^$r/||" || true)"
       [[ -n "$v" ]] && out="$out"$'\n'"$v"
     fi
     out="$(printf '%s\n' "$out" | grep -v '^$' | sort -u || true)"
     # Probing through gh costs a network call, so only when nothing else said.
-    [[ -n "$out" ]] || out="$(detect_base "$ROOT" 2>/dev/null || true)"
+    [[ -n "$out" ]] || out="$(detect_base "$dir" 2>/dev/null || true)"
     printf '%s\n' "$out" | grep -v '^$' || true
   }
 
-  # in_base_heads BRANCH — membership without a pipe: `base_heads | grep -q`
-  # trips pipefail, because grep exits on the first match and SIGPIPEs the
-  # producer, so a branch that IS a base reported as if it were not.
+  # in_base_heads DIR BRANCH — membership without a pipe: `… | grep -q` trips
+  # pipefail, because grep exits on the first match and SIGPIPEs the producer,
+  # so a branch that IS a base reported as if it were not.
   in_base_heads() {
-    local want="$1" b
+    local dir="$1" want="$2" b
     while IFS= read -r b; do
       [[ "$b" == "$want" ]] && return 0
-    done < <(base_heads)
+    done < <(base_heads_in "$dir")
     return 1
   }
 
+  # repo_base DIR — the base a PR from DIR targets, for a brand-new branch name.
+  repo_base() {
+    local dir="$1" v="" r
+    if [[ -f "$dir/.sassywares/config.yaml" ]]; then
+      v="$(yflat_in "$dir/.sassywares/config.yaml" "git${US}base_map${US}*" 2>/dev/null || true)"
+    fi
+    [[ -n "$v" ]] || v="$(yflat "repos${US}$(basename "$dir")" 2>/dev/null || true)"
+    if [[ -z "$v" ]]; then
+      v="$(detect_base "$dir" 2>/dev/null || true)"
+      [[ -n "$v" ]] && printf '%s' "$v" && return 0
+    fi
+    printf '%s' "$v"
+  }
+
+  # classify DIR [HEAD] — on-base, on-branch, detached, or unknown.
+  classify() {
+    local dir="$1" h="$2"
+    if [[ -z "$h" ]]; then printf 'detached'; return 0; fi
+    if in_base_heads "$dir" "$h"; then printf 'on-base'; else printf 'on-branch'; fi
+  }
+
+  # start_point DIR HEAD — the upstream ref a new branch is cut from. Prints
+  # "none" when there is no upstream ref: cutting from local HEAD would carry
+  # commits stranded on the base, which is the failure this prevents.
+  start_point() {
+    local dir="$1" h="$2" r
+    r="$(remote_name "$dir")"
+    if [[ -n "$r" && -n "$h" ]] && git -C "$dir" rev-parse --verify --quiet "refs/remotes/$r/$h" >/dev/null 2>&1; then
+      printf '%s/%s' "$r" "$h"
+    else
+      printf 'none'
+    fi
+  }
+
+  # unpublished DIR HEAD — commits on the local base that are not upstream.
+  # Unknown on error, never 0: an unreadable count must not read as "clean".
+  unpublished() {
+    local dir="$1" h="$2" r n
+    r="$(remote_name "$dir")"
+    [[ -n "$r" && -n "$h" ]] || { printf 'unknown'; return 0; }
+    git -C "$dir" rev-parse --verify --quiet "refs/remotes/$r/$h" >/dev/null 2>&1 || { printf 'unknown'; return 0; }
+    n="$(git -C "$dir" rev-list --count "$r/$h..$h" 2>/dev/null || true)"
+    [[ -n "$n" ]] && printf '%s' "$n" || printf 'unknown'
+  }
+
+  # decide STATE POLICY START UNPUBLISHED — the action, fail closed.
+  decide() {
+    local st="$1" pol="$2" start="$3" unp="$4"
+    case "$st:$pol" in
+      on-branch:*)     printf 'reuse'; return 0 ;;
+      on-base:new)     ;;
+      on-base:current) printf 'commit-here'; return 0 ;;
+      detached:new)    ;;
+      *)               printf 'refuse'; return 0 ;;
+    esac
+    # Cutting needs a known-clean upstream base.
+    [[ "$start" == "none" ]] && { printf 'refuse'; return 0; }
+    [[ "$unp" == "0" ]] || { printf 'stop-and-ask'; return 0; }
+    printf 'create'
+  }
+
+  repo_value="$(yflat "git${US}repo" 2>/dev/null || true)"
+
+  [[ -n "$note" ]] && printf 'note: %s\n' "$note"
   printf 'topology: %s\n' "$TOPOLOGY"
   printf 'config: %s\n' "${CONFIG:-none}"
   printf 'configured: %s\n' "${configured:-none}"
   printf 'policy: %s\n' "$policy"
 
-  if [[ "$TOPOLOGY" == "none" ]]; then
-    printf 'state: no-git\naction: refuse\n'
+  if [[ "$TOPOLOGY" == "none" || "$repo_value" == "none" ]]; then
+    if [[ "$repo_value" == "none" ]]; then
+      printf 'state: no-git\naction: refuse\nreason: git.repo is none\n'
+    else
+      printf 'state: no-git\naction: refuse\nreason: not a git work tree\n'
+    fi
     exit 0
   fi
 
   if [[ "$TOPOLOGY" == "workspace" ]]; then
-    # The run shares one branch name across every repo, so the decision is made
-    # once, here, and applied inside each nested repo. A nested repo carrying
-    # its own commit.branch that disagrees is drift, not an override: it would
-    # give one run two branch policies.
+    # One policy for the whole run, resolved per repo: a run cannot follow two
+    # branch policies, so a nested repo that disagrees is reported as drift.
     while IFS= read -r dir; do
       [[ -n "$dir" ]] || continue
-      head="$(git -C "$ROOT/$dir" branch --show-current 2>/dev/null || true)"
-      if [[ -z "$head" ]]; then
-        printf 'repo %s: head=detached state=detached\n' "$dir"
-      elif in_base_heads "$head"; then
-        printf 'repo %s: head=%s state=on-base\n' "$dir" "$head"
-      else
-        printf 'repo %s: head=%s state=on-branch\n' "$dir" "$head"
-      fi
+      d="$ROOT/$dir"
+      h="$(git -C "$d" branch --show-current 2>/dev/null || true)"
+      st="$(classify "$d" "$h")"
+      sp="$(start_point "$d" "$h")"
+      base="$(repo_base "$d")"
+      if [[ "$st" == "on-base" ]]; then unp="$(unpublished "$d" "$h")"; else unp=n/a; fi
+      printf 'repo %s: head=%s state=%s base=%s start-point=%s unpublished=%s action=%s\n' \
+        "$dir" "${h:-none}" "$st" "${base:-none}" "$sp" "$unp" "$(decide "$st" "$policy" "$sp" "$unp")"
       own=""
-      if [[ -f "$ROOT/$dir/.sassywares/config.yaml" ]]; then
-        own="$(yflat_in "$ROOT/$dir/.sassywares/config.yaml" "commit${US}branch" 2>/dev/null || true)"
+      if [[ -f "$d/.sassywares/config.yaml" ]]; then
+        own="$(yflat_in "$d/.sassywares/config.yaml" "commit${US}branch" 2>/dev/null || true)"
       fi
       [[ -n "$own" && "$own" != "$policy" ]] && printf 'drift %s: commit.branch=%s\n' "$dir" "$own"
     done < <(nested_repos)
@@ -504,53 +603,38 @@ if (( BRANCH )); then
   fi
 
   head="${HEAD_ARG:-$(git -C "$ROOT" branch --show-current 2>/dev/null || true)}"
+  actual="$(git -C "$ROOT" branch --show-current 2>/dev/null || true)"
+  [[ -n "$HEAD_ARG" && "$HEAD_ARG" != "$actual" ]] && printf 'checked-out: %s\n' "${actual:-none}"
   printf 'head: %s\n' "${head:-none}"
 
-  if [[ -z "$head" ]]; then
-    state=detached
-  elif in_base_heads "$head"; then
-    state=on-base
-  else
-    state=on-branch
-  fi
+  state="$(classify "$ROOT" "$head")"
   printf 'state: %s\n' "$state"
-
-  case "$state:$policy" in
-    on-branch:*)     action=reuse ;;
-    on-base:new)     action=create ;;
-    on-base:current) action=commit-here ;;
-    detached:new)    action=create ;;
-    *)               action=refuse ;;
-  esac
-  printf 'action: %s\n' "$action"
-
-  # A new branch starts at the upstream tip, never at local HEAD: commits that
-  # were stranded on the base earlier must not ride along silently.
-  if [[ -n "$head" ]] && git -C "$ROOT" rev-parse --verify --quiet "refs/remotes/origin/$head" >/dev/null 2>&1; then
-    printf 'start-point: origin/%s\n' "$head"
-    printf 'unpublished: %s\n' "$(git -C "$ROOT" rev-list --count "origin/$head..$head" 2>/dev/null || echo 0)"
-  else
-    printf 'start-point: %s\n' "${head:-none}"
-    printf 'unpublished: unknown\n'
-  fi
-
-  if [[ "$action" == "create" ]]; then
-    # The head will be a brand-new name, so only the "*" rung can apply to it.
-    pr_base="$(yflat "git${US}base_map${US}*" 2>/dev/null || true)"
-    pr_src=config
+  start="$(start_point "$ROOT" "$head")"
+  unp=n/a
+  [[ "$state" == "on-base" ]] && unp="$(unpublished "$ROOT" "$head")"
+  printf 'action: %s\n' "$(decide "$state" "$policy" "$start" "$unp")"
+  printf 'start-point: %s\n' "$start"
+  printf 'unpublished: %s\n' "$unp"
+
+  # pr-base is provisional for a branch that does not exist yet: the name the
+  # skill picks can match a base_map family (release/*, hotfix/*) and retarget
+  # the PR. Pass --name once the name is known to get the final answer.
+  pr_src=config
+  if [[ -n "$NAME_ARG" ]]; then
+    pr_base="$(base_for_head "$NAME_ARG" 2>/dev/null || true)"
+  elif [[ "$state" == "on-base" || "$state" == "detached" ]]; then
+    pr_base="$(repo_base "$ROOT")"
   else
     pr_base="$(base_for_head "$head" 2>/dev/null || true)"
-    pr_src=config
   fi
   if [[ -z "$pr_base" ]]; then
-    # No config named a base. A probed value is not a decision: the skills must
-    # confirm it with the user before it becomes a PR target.
     pr_base="$(detect_base "$ROOT" 2>/dev/null || true)"
     pr_src=probed
   fi
   [[ -n "$pr_base" ]] || pr_src=unknown
   printf 'pr-base: %s\n' "$pr_base"
   printf 'pr-base-source: %s\n' "$pr_src"
+  printf 'pr-base-final: %s\n' "$( [[ -n "$NAME_ARG" ]] && printf yes || printf no )"
   exit 0
 fi
 

package/skills/sassy-ship/SKILL.md

@@ -28,7 +28,7 @@ disable-model-invocation: true
 4. **Commit or snapshot.** After the review gate — never before it — the docs and any remaining code become durable.
    - **`git.repo` is a remote.** Dispatch a `worker`: *load the `sassy-commit` skill and follow it with `branch:current`*, naming that the commit must include the plan, any new solutions docs, the concepts file, `AGENTS.md`, and any handbook just written — resolved from `artifacts.*`, never hardcoded. The branch already exists: `sassy-work` or `sassy-lfg` cut it before the first change, so the docs belong on it with the phase commits. It returns the hash and subject.
 
-     **Ship never creates the branch.** If this run's head is a base branch with unpublished commits, that is a mis-run — `sassy-work` was supposed to cut before touching code. Stop and ask, naming the branch and the count; never relocate commits silently, never push to the base.
+     **Ship never creates the branch.** If this run's head is a base branch with unpublished commits, that 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.
    - **`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`.
    - **`git.repo: none`.** No commit exists here. Report that the work is not persisted and stop.
 5. **PR.** 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.
@@ -49,7 +49,7 @@ disable-model-invocation: true
 | Conditional docs | Compound and handbook are skipped when they do not qualify. |
 | Docs in the commit | New docs and pointer lines ship in the same change. |
 | One branch | The branch is cut once, before the first change, by `sassy-work` or `sassy-lfg`. Ship and its docs commit land on it. |
-| Never create the branch | Ship never cuts a branch. Finding the run's head on a base branch with unpublished commits is a stop-and-ask. |
+| Never create the branch | Ship never cuts a branch. A head on a base branch with unpublished commits is a stop-and-ask, decided from the commit worker's `state` and `unpublished`. |
 | Never default | Never push directly to the repo base branch. |
 | Snapshot after approval | In a workspace, the snapshot runs every time, immediately after the commit approval — never before it, never skipped. |
 | 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. |

package/skills/sassy-work/SKILL.md

@@ -46,8 +46,8 @@ Always gate before committing. One worker fixes findings, one re-check, then pre
 
 1. **Load the phase.** Read the plan and only the selected phase's section. If it is already `Done`, stop and report.
 
-   If the phase is `In progress`, an earlier run was interrupted before both gates passed. Ask one question — resume at the gate, or re-run the cycle from scratch — and take the answer. Resuming skips straight to step 5 and does not rebuild the phase.
-2. **Resolve the branch, before touching code.** Follow the `sassy-setup` skill's `references/branching.md` with this run's `branch:` token, if any. On `create`, cut the branch now — not at commit time — so no change ever exists on a base branch. On `reuse`, stay where you are, which is how a handed-off later phase or a resumed run lands on the branch the first phase cut. Carry the branch and its start point into every gate summary you present. Stop and ask when the reference says to.
+   If the phase is `In progress`, an earlier run was interrupted before both gates passed. Ask one question — resume at the gate, or re-run the cycle from scratch — and take the answer. Resuming skips the cycle and goes straight to step 5, but **still resolve the branch at step 2 first**: on `reuse` it is a no-op, and on `create` it is the difference between committing on the base and not.
+2. **Resolve the branch, before touching code.** Follow the `sassy-setup` skill's `references/branching.md` with this run's `branch:` token, if any. On `create`, cut the branch now — not at commit time — so no change ever exists on a base branch. On `reuse`, stay where you are, which is how a handed-off later phase or a resumed run lands on the branch the first phase cut. On `stop-and-ask`, present the choice and wait. Carry the branch and its start point into every gate summary you present.
 3. **Run the cycle.** Set the phase `In progress` in the Phase tracking table, then load the `sassy-cycle` skill and follow it, with:
    - work brief = the phase's goal, work items, and "Done when" criteria
    - intent reference = the plan path and phase
@@ -92,7 +92,7 @@ When the argument is not a plan path, it is one settled brief:
 | Rule | Requirement |
 |------|-------------|
 | Orchestrator only | Delegate all implementation and quality work to `sassy-cycle`. |
-| Branch before code | Resolve the branch per `references/branching.md` before the cycle runs, so no change ever lands on a base branch. |
+| Branch before code | Resolve the branch per the `sassy-setup` skill's `references/branching.md` before the cycle runs, so no change ever lands on a base branch. |
 | One phase per run | Do exactly one phase. Never continue into the next phase in this session. |
 | Gate before commit and handoff | Do not commit, hand off, or close out until the user approves the code and the phase QA rows pass. |
 | Commit per phase | Commit the phase, its QA results, and the plan update via `sassy-commit` before handoff or close-out. |