@sassywares/skills 0.5.5 → 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`.
 
@@ -259,6 +259,14 @@ The fix gate offers four options:
 
 The artifact decides QA: a plan document carries manual QA tables that gate phase completion, an in-context brief does not. Gates are deliberate stops; the only way past one is the user's approval. `mode:auto` is accepted only by `sassy-ship` and `sassy-compound`.
 
+## Branching
+
+`sassy-work`, `sassy-lfg`, and `sassy-debug` decide the branch **before they touch code**, from `commit.branch` (default `new`) compared against `base_map`. On `new`, the run cuts a branch and every commit — phases, docs, ship — lands on it, so no change ever exists on a base branch. A run that is already on a branch that is not a base reuses it, which is how a handed-off phase, a resumed run, or `sassy-lfg` after `sassy-work` converges instead of cutting a second branch.
+
+A base is **any `base_map` value**, not just the remote default: in a repo whose `"*"` targets `staging`, standing on `staging` counts as standing on a base. That distinction is the whole point of the key — see [`skills/sassy-setup/references/branching.md`](skills/sassy-setup/references/branching.md).
+
+The three skills take `branch:infer|current|new` to override the config for one run: `infer` (default) means the config decides, `new` forces a branch, `current` commits where you stand. `sassy-ship` never creates a branch; finding the head on a base branch with unpublished commits is a stop-and-ask.
+
 ## Repository layout
 
 ```text

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sassywares/skills",
-  "version": "0.5.5",
+  "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

@@ -28,9 +28,11 @@ Treat the reads as a snapshot; re-read branch and staged set right before commit
 
 **Never bypass hooks.** No `--no-verify`, and never pass it through to a project script this run invokes. A repo's git hooks are the layer that cannot be skipped, so disabling them silently removes an enforcement the project relies on.
 
-**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.
+**Config.** Resolve `.sassywares/config.yaml` (nearest, walking up) per the `sassy-setup` skill's `references/config.md`. `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 `base_map` from the repo's own config when it has one, else `repos[<dir>]` from the workspace config, 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.
+**Who may pass a token.** Precedence is explicit token > session instruction > config > skill default, and a token counts as explicit only when the **caller** supplied it — the user typed it, or an earlier gate of the same run authorized it. A skill must never pass its own default as a token: that promotes a default over the project's config and makes `commit.branch` unreachable. When the entry skill (`sassy-work`, `sassy-lfg`, `sassy-debug`) has already resolved the branch through `sassy-setup`'s `references/branching.md`, it passes `branch:current`, because the branch exists and the work belongs on it.
+
+**Branch option.** `branch:current|new [<name>]`. `current` commits on the checked-out branch. `new` cuts a branch from `origin/<base>` — `<base>` is `base_map` from the repo's own config when it has one, else `repos[<dir>]` from the workspace config, else the probed base **confirmed with the user** — named `<name>` when given, else from the change. Use `new` only when no branch has been cut yet; the entry skills cut at the start of a run, so a `new` from them means the cut was skipped. `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.
 
@@ -38,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 exists, pick a non-conflicting suffix. With `branch:current` (default), commit on the checked-out branch; if that is the base branch or a detached HEAD, say so in one line before proceeding.
+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

@@ -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` supplies the `before_create` / `after_create` steps for this run's head.
+**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.
 
@@ -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.** 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`.
+**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-debug/SKILL.md

@@ -5,7 +5,7 @@ description: >-
   through sassy-cycle (fix, review, validate), and finally ship it
   through sassy-ship after code approval. Never auto-commits. Use when asked to
   debug or fix a failure.
-argument-hint: "[issue reference, error message, test path, or description]"
+argument-hint: "[issue reference, error message, test path, or description] [branch:infer|current|new]"
 disable-model-invocation: true
 ---
 
@@ -15,6 +15,8 @@ Find the root cause of a failure, get approval for the fix, fix it through the s
 
 **Done when:** the full causal chain is stated with `file:line` evidence, the fix gate was answered with one of its four options, and either the fix has passed the quality cycle and shipped after code approval, or the run ended at the fix gate.
 
+**Config.** Resolve `.sassywares/config.yaml` (nearest, walking up) per the `sassy-setup` skill's `references/config.md`. `commit.branch` decides whether the fix needs its own branch; `sassy-work` makes that decision when the fix starts, because the branch belongs to the work and not to the diagnosis.
+
 **Escalate rather than persist:** 2–3 hypotheses exhausted without confirmation, or 3 failed fix attempts, means diagnose *why* instead of trying again. One hypothesis, one change at a time — never shotgun-debug. Before escalating, re-search the prior learnings with the keywords of what you just ruled out: an exhausted hypothesis list is often a documented trap.
 
 ## Phase 0 — Triage
@@ -57,7 +59,11 @@ This gate is mandatory even when the original request said "fix the bug". Do not
 
 ### Option 1 — Fix it now
 
-Load the `sassy-work` skill with the fix brief as the work brief and the diagnosis from Phase 1 as the intent reference. Work runs one cycle, presents its own code approval gate, commits, and stops before ship. Continue to Phase 3.
+Load the `sassy-work` skill with the fix brief as the work brief and the diagnosis from Phase 1 as the intent reference, forwarding this run's `branch:` token if it was given. Work runs one cycle, presents its own code approval gate, commits, and stops before ship.
+
+The branch decision belongs to work, not to this phase: diagnosis writes nothing, so cutting a branch before the fix gate would leave an empty branch every time the gate ends in *Write a plan*, *Hand off*, or *Stop here*. Work resolves it per `sassy-setup`'s `references/branching.md` before it touches code, so the fix is on its own branch from the first edit and still never lands on a base branch.
+
+Continue to Phase 3.
 
 ### Option 2 — Write a plan
 

package/skills/sassy-lfg/SKILL.md

@@ -4,7 +4,7 @@ description: >-
   Execute a whole sassy plan phase by phase, or one settled in-context brief,
   then close out via sassy-ship after code approval. The orchestrator only
   coordinates. Best for small plans that one context can hold.
-argument-hint: "<plan path | brief>"
+argument-hint: "<plan path | brief> [branch:infer|current|new]"
 disable-model-invocation: true
 ---
 
@@ -14,7 +14,7 @@ disable-model-invocation: true
 
 **The orchestrator does not do work.** Read the plan, dispatch `sassy-cycle` per phase, then `sassy-ship`. Never edit application code. Keep the main context small — all heavy work happens in subagents.
 
-**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. Plans live under `artifacts.plans`; `git.repo` decides how the close-out persists.
+**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. Plans live under `artifacts.plans`; `git.repo` decides how the close-out persists; `commit.branch` decides whether the run needs its own branch.
 
 ## Input
 
@@ -38,18 +38,17 @@ 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. **Run every phase, in order.** For each phase not `Done`:
+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.
    - On `Status: blocked`, mark it `Blocked` and stop the run.
-3. **The gate.** After the last phase, report: the plan path, each phase's status, what changed per phase, and the validator/reviewer summaries. Then give every phase's QA checklist verbatim — row ID, check, how to run it, what passing looks like — with unreported rows `Pending`. Ask for both decisions: code approval and the QA result per row. Wait. Do not commit.
-4. **Resolve the gate.** Three outcomes:
+4. **The gate.** After the last phase, report: the plan path, each phase's status, what changed per phase, and the validator/reviewer summaries. Then give every phase's QA checklist verbatim — row ID, check, how to run it, what passing looks like — with unreported rows `Pending`. Ask for both decisions: code approval and the QA result per row. Wait. Do not commit.
+5. **Resolve the gate.** Three outcomes:
    - **Code approved and every QA row passes** → mark the rows `Done` with the user's notes, mark the phases `Done`, then run the close-out below.
    - **Code approved, QA still pending** → tick nothing, mark nothing `Done`, commit nothing, ship nothing. Report which rows are outstanding and how to resume (`/skill:sassy-lfg <plan>`), and stop.
    - **Any QA row fails** → run one more `sassy-cycle` on that phase with the failing rows as the intent reference, then present the gate again. A row that still fails is `Blocked` with the reason and stops the run.
-5. **Close-out.** On both gates passing, load the `sassy-ship` skill and follow it. Do only the close-out steps the user approves. Babysit options (`merge:on|off`, `delete-branch:on|off`) are forwarded through `sassy-ship` to `sassy-babysit`.
-
-Work commits to the current branch. `sassy-ship` creates the shipping branch at close-out when the checked-out branch is the repo default.
+6. **Close-out.** On both gates passing, load the `sassy-ship` skill and follow it. Do only the close-out steps the user approves. Babysit options (`merge:on|off`, `delete-branch:on|off`) are forwarded through `sassy-ship` to `sassy-babysit`. The branch from step 2 already carries the work, so ship commits and opens the PR on it; ship never creates the branch.
 
 ## Brief constraints
 
@@ -63,15 +62,17 @@ Every worker brief this run dispatches must include:
 
 When the argument is not a plan path, the brief is the one phase:
 
-1. 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.
-2. Present the code approval gate with no QA checklist, and wait.
-3. On code approval, run `sassy-ship`. Do not run `sassy-plan` or write a plan file.
+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.
 
 ## Hard rules
 
 | Rule | Requirement |
 |------|-------------|
 | Orchestrator only | Delegate every phase to `sassy-cycle`. Never read source or edit code. |
+| 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/SKILL.md

@@ -27,6 +27,7 @@ disable-model-invocation: true
    - **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 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.
+   - **`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.
    - **`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 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.

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

@@ -0,0 +1,132 @@
+# Branching
+
+One branch decision per run, made **before** the first change. `sassy-work`,
+`sassy-lfg`, and `sassy-debug` all resolve it here, through one detector, so the
+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 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. `--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 — 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` |
+| `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` |
+| `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`, `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` (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 `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 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
+`commit.branch` unreachable. Omitting `--policy` is how a skill defers to
+config. This applies to every token these skills forward, not just `branch`.
+
+## Act on `action`
+
+### `create`
+
+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`.
+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.
+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`
+
+Report `head` and carry on. Do **not** re-cut because `commit.branch` is `new`:
+a second phase, a resumed run, or a handed-off session is already standing on
+the branch the first one cut. That is the whole reason this is inferred rather
+than forced.
+
+### `commit-here`
+
+Only reachable with `policy: current`, which is an explicit statement that
+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 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 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
+
+Downstream steps forward `branch:current` to `sassy-commit`, because the decision
+has already been made and the commits belong on that branch. `sassy-ship` never
+creates the branch — by the time it runs, the branch carries the work. If it ever
+finds the run's head on a base branch with unpublished commits, that is a
+mis-run: stop and ask, never relocate commits silently.
+
+Report the branch and its start point in every gate summary. A decision the user
+cannot see is a decision they cannot correct.

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

@@ -25,6 +25,21 @@ explicit token in the request  >  instruction in this session
 >  .sassywares/config.yaml  >  skill default
 ```
 
+**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
 file. A skill invoked directly resolves it itself.
@@ -50,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
@@ -76,7 +91,7 @@ hooks:
 | `git.remote` | mirror of `git.repo` | Workspace only: mirror remote (URL or `owner/name`) |
 | `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 |
+| `commit.branch` | `new` | Resolved once per run, before the first change. `new` never commits on a base branch: `sassy-work`, `sassy-lfg`, and `sassy-debug` cut a branch first. `current` commits where you stand, base branch included |
 | `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 |
@@ -143,6 +158,35 @@ without asking, so the version line is how staleness surfaces.
 In `workspace` and `none`, changes still land on disk. Nothing is silently
 dropped; the refusal names why and what to run instead.
 
+## `commit.branch` — decide once, before code
+
+Resolved once per run, by the entry skill (`sassy-work`, `sassy-lfg`,
+`sassy-debug`), **before the first change**, through
+`sassy-setup/references/branching.md`. Not at commit time: committing first and
+re-branching later leaves the commits on a base branch, and cutting the new
+branch from `origin/<base>` then leaves them behind entirely.
+
+| Value | Meaning |
+|-------|---------|
+| `current` | Commit where you stand, even on a base branch. An explicit statement that this repo's work in progress is acceptable |
+| `new` (default) | Never commit on a base branch. Cut one first, then stay on it for the rest of the run |
+
+A branch that is already checked out and is **not** a base is reused, whatever
+the config says. That is what makes a second phase, a resumed run, or a
+handed-off session converge on the branch the first one cut instead of cutting
+another.
+
+A base is **any `base_map` value**, plus the remote default — not the remote
+default alone. In the config above `staging` is a base because `"*"` targets it,
+even though `origin/HEAD` is `main`. Comparing only against `origin/HEAD` is how
+phase work once got committed straight onto `staging`.
+
+The `branch:infer|current|new` token on those skills overrides this key for one
+run; `infer` means this key decides. In a workspace the key is resolved from the
+workspace config for the whole run, one branch name in every repo; a nested
+repo whose own `commit.branch` disagrees is drift, because one run cannot follow
+two policies.
+
 ## Resolution chains
 
 **Effective repo.** Inside a git work tree, the nearest toplevel is the repo —
@@ -186,9 +230,10 @@ config to. When a repo has both, the nested config wins and `--check` reports
 the disagreement rather than picking silently. A nested config needs no ladder
 of its own unless its PRs target more than one branch.
 
-**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
-`branch:new <name>`; a per-repo derived name would diverge.
+**Branch name**, one per run. Derived once from the plan slug or topic when the
+run starts, then used in every repo. The branch is cut at the start of the run,
+not at commit time, so every repo sits on it before any change exists; each
+repo cuts from its own upstream base and reuses the name in the others.
 
 Cut from the base, then verify:
 

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

@@ -7,12 +7,22 @@
 # 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 --branch [--policy P]   resolve the branch decision for this run
 #   detect.sh [--root DIR] --check    compare the existing config to reality
+#
+# --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
 
 while (( $# )); do
   case "$1" in
@@ -20,8 +30,13 @@ while (( $# )); do
     --root=*) ROOT_ARG="${1#*=}" ;;
     --head)   shift; [[ $# -ge 1 ]] || { echo "missing BRANCH after --head" >&2; exit 2; }; HEAD_ARG="$1" ;;
     --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,10p' "${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
@@ -29,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)"
 
@@ -409,11 +427,217 @@ 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
 fi
 
+# --- Branch decision -------------------------------------------------------
+# Read-only. Resolves commit.branch into the single decision the entry skills
+# (sassy-work, sassy-lfg, sassy-debug) make before they start: cut a branch,
+# reuse the one checked out, or commit where you stand.
+#
+# Every base_map VALUE counts as a base branch, not just the remote default.
+# tap2's day-to-day base is `staging`, so comparing only against origin/HEAD
+# declared staging "not a base" and let phase work commit onto it.
+if (( BRANCH )); then
+  policy="${POLICY_ARG:-infer}"
+  case "$policy" in
+    infer|current|new) ;;
+    *) echo "unknown --policy: $policy (expected infer, current, or new)" >&2; exit 2 ;;
+  esac
+  configured="$(yflat "commit${US}branch" 2>/dev/null || 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 "$dir" 2>/dev/null || true)"
+    printf '%s\n' "$out" | grep -v '^$' || true
+  }
+
+  # 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 dir="$1" want="$2" b
+    while IFS= read -r b; do
+      [[ "$b" == "$want" ]] && return 0
+    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" || "$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
+    # 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
+      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 "$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)
+    exit 0
+  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}"
+
+  state="$(classify "$ROOT" "$head")"
+  printf 'state: %s\n' "$state"
+  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)"
+  fi
+  if [[ -z "$pr_base" ]]; then
+    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
+
 # --- Emit a proposal -------------------------------------------------------
 # Every key carries its meaning and its allowed values. The file is the
 # documentation a teammate reads, so the comments are part of the output, not
@@ -532,12 +756,12 @@ esac
 cat <<'EOF'
 
 # --- Commit ---------------------------------------------------------------
-# current: commit on the checked-out branch.
-# 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.
+# current: commit on the checked-out branch, even on a base branch.
+# new: never commit on a base branch — sassy-work, sassy-lfg, and sassy-debug
+#      cut a branch at the start of the run and stay on it.
 commit:
 EOF
-kv branch current 34 '# current | new'
+kv branch new 34 '# current | new'
 cat <<'EOF'
 
 # --- Pull requests --------------------------------------------------------

package/skills/sassy-ship/SKILL.md

@@ -26,8 +26,10 @@ disable-model-invocation: true
 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.
-   - **`git.repo` is a remote.** Dispatch a `worker`: *load the `sassy-commit` skill and follow it*, 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. Use `branch:current` when already on a feature branch, so the docs land with the phase commits. When the checked-out branch is the base branch, use `branch:new <name>` so the branch is created from `origin/<base>` and carries every phase commit; a workspace run passes the run's shared branch name. Never push directly to the base branch. It returns the hash and subject.
-   - **`git.repo: workspace`.** Commit code inside each affected repo on the run's shared branch (cut once on the run's first commit, `branch:current` after), 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` 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. 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.
 
@@ -46,7 +48,8 @@ disable-model-invocation: true
 | Delegate everything | The orchestrator runs no git, gh, or file work itself. |
 | 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 | Docs land on the current feature branch; from the base branch, ship creates a feature branch so every phase commit moves with it. |
+| 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. 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

@@ -5,7 +5,7 @@ description: >-
   hand off to a fresh session for the next phase (or close out via sassy-ship if
   it was the last). Also runs one settled in-context brief and stops before ship.
   The orchestrator only coordinates.
-argument-hint: "<plan path | brief> [phase:<n>]"
+argument-hint: "<plan path | brief> [phase:<n>] [branch:infer|current|new]"
 disable-model-invocation: true
 ---
 
@@ -17,7 +17,7 @@ disable-model-invocation: true
 
 **The orchestrator does not do work.** Read the plan, dispatch `sassy-cycle`, apply its result, update the plan's tracking table, dispatch `sassy-commit` or the snapshot, and report. Never edit application code.
 
-**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. `git.repo` decides what the phase commit does, `artifacts.plans` decides where the plan lives.
+**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. `git.repo` decides what the phase commit does, `artifacts.plans` decides where the plan lives, and `commit.branch` decides whether this run needs its own branch.
 
 ## Input
 
@@ -46,26 +46,25 @@ 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 4 and does not rebuild the phase.
-2. **Run the cycle.** Set the phase `In progress` in the Phase tracking table, then load the `sassy-cycle` skill and follow it, with:
+   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
-3. **Evaluate the phase.** On `Status: done` with `Validator: Conforms` and no critical review findings, note that the code is ready but leave the phase `In progress` — both gates must pass before it closes. On `Status: blocked`, set it `Blocked` in the Phase tracking table and stop; a blocked phase is a real outcome and needs no approval.
-4. **Present the phase gate.** Report the phase, what changed, findings raised/resolved, the validator grade, and the reviewer summary. Then give the QA checklist verbatim: each row's ID, check, how to run it, and what passing looks like, with unreported rows `Pending`. Ask for both decisions — code approval and the QA result per row. Wait.
-5. **Resolve the gate.** Three outcomes, nothing in between:
-   - **Code approved and every QA row passes** → go to step 6.
+4. **Evaluate the phase.** On `Status: done` with `Validator: Conforms` and no critical review findings, note that the code is ready but leave the phase `In progress` — both gates must pass before it closes. On `Status: blocked`, set it `Blocked` in the Phase tracking table and stop; a blocked phase is a real outcome and needs no approval.
+5. **Present the phase gate.** Report the phase, what changed, findings raised/resolved, the validator grade, and the reviewer summary. Then give the QA checklist verbatim: each row's ID, check, how to run it, and what passing looks like, with unreported rows `Pending`. Ask for both decisions — code approval and the QA result per row. Wait.
+6. **Resolve the gate.** Three outcomes, nothing in between:
+   - **Code approved and every QA row passes** → go to step 7.
    - **Code approved, QA still pending** → record that code is approved but leave the phase `In progress`, tick nothing, commit nothing, hand off nothing, and report that the phase is waiting on manual QA plus the command that resumes it.
    - **Any QA row fails** → run `sassy-cycle` once more on the same phase, with the failing rows as the intent reference and a work brief that fixes exactly those failures. Then present the gate again. If a row still fails after that one pass, mark it `Blocked` with the reason and stop.
-6. **Commit the phase.** On both gates passing, first mark the phase's QA rows `Done` with the user's notes and the phase `Done` in the Phase tracking table, then persist according to `git.repo`:
+7. **Commit the phase.** On both gates passing, first mark the phase's QA rows `Done` with the user's notes and the phase `Done` in the Phase tracking table, then persist according to `git.repo`:
 
-   - **A remote** — dispatch a `worker` whose task is: *load the `sassy-commit` skill and follow it with `branch:current`*, naming that the commit must include the phase's code changes, the QA table results, and the now-updated Phase tracking table. It returns the hash and subject.
-   - **`workspace`** — dispatch a `worker` per affected repo to commit that repo's code on the run's shared branch (cut once on the run's first commit with `branch:new <name>`, `branch:current` after), then run `.sassywares/workspace/snapshot` for the plan, QA results, and docs at the root. The gate's approval is the commit approval; the snapshot runs right after it and is never skipped. A missing or outdated `.sassywares/workspace/snapshot` is a blocker — say to run `sassy-setup`.
+   - **A remote** — dispatch a `worker` whose task is: *load the `sassy-commit` skill and follow it with `branch:current`*, naming that the commit must include the phase's code changes, the QA table results, and the now-updated Phase tracking table. It returns the hash and subject. The branch already exists: step 2 cut it, so committing on it is the point of `branch:current` here.
+   - **`workspace`** — dispatch a `worker` per affected repo to commit that repo's code on the run's shared branch, then run `.sassywares/workspace/snapshot` for the plan, QA results, and docs at the root. The gate's approval is the commit approval; the snapshot runs right after it and is never skipped. A missing or outdated `.sassywares/workspace/snapshot` is a blocker — say to run `sassy-setup`.
    - **`none`** — nothing is persisted. Report that the phase's work is uncommitted and stop; never hand off on top of it.
 
-   Work commits on the current branch. `sassy-ship` creates the shipping branch at close-out when the checked-out branch is the repo base.
-
    Do not hand off or close out until the commit or snapshot succeeds.
-7. **On commit success:**
+8. **On commit success:**
    - **A next phase exists** → hand off so it starts in a fresh session:
 
      ```text
@@ -82,16 +81,18 @@ Always gate before committing. One worker fixes findings, one re-check, then pre
 
 When the argument is not a plan path, it is one settled brief:
 
-1. 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 cycles.
-2. Present the code approval gate with no QA checklist, and wait.
-3. On code approval, persist the brief's changes the same way the plan path does: a `sassy-commit` delegation with `branch:current` in a remote repo, or the workspace snapshot in a workspace.
-4. Stop and report. Shipping is a separate step (`sassy-ship`), or `sassy-lfg` would have taken it all the way. Never create or update a plan file.
+1. Resolve the branch exactly as the plan path does — `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 cycles.
+3. Present the code approval gate with no QA checklist, and wait.
+4. On code approval, persist the brief's changes the same way the plan path does: a `sassy-commit` delegation with `branch:current` in a remote repo, or the workspace snapshot in a workspace.
+5. Stop and report. Shipping is a separate step (`sassy-ship`), or `sassy-lfg` would have taken it all the way. Never create or update a plan file.
 
 ## Hard rules
 
 | Rule | Requirement |
 |------|-------------|
 | Orchestrator only | Delegate all implementation and quality work to `sassy-cycle`. |
+| 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. |