@sassywares/skills 0.5.4 → 0.5.6

package/CONCEPTS.md

@@ -56,4 +56,4 @@ A settled in-context brief produced by `sassy-plan` when the user picks "start w
 
 ## Sync
 
-There is no background watcher. Any agent that changes a skill must run `scripts/sync.sh` immediately, without asking for confirmation. The sync script commits the change, rebases on `origin/main`, and pushes. It installs nothing: a changed skill reaches consumers only when a new version is released and a consumer bumps its pin.
+There is no background watcher. Any agent that changes a skill must run `scripts/sync.sh` immediately, without asking for confirmation. The sync script bumps the patch version, commits, pushes `main`, then tags and pushes the tag, which publishes to npm. It installs nothing: `npx skills add` reads this repo directly, and the npm package follows the tag the script creates.

package/README.md

@@ -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
@@ -313,12 +321,14 @@ pi install npm:@sassywares/skills
 
 ## Repository maintenance
 
-`scripts/sync.sh` commits skill changes, rebases on `origin/main`, and pushes. Any agent that changes a skill must run it immediately, without asking for confirmation. It installs nothing anywhere — consumers get a change when they run `npx skills update` after a push. `AGENTS.md` documents the workflow for agents working on this repo.
+`scripts/sync.sh` bumps the patch version, commits, pushes `main`, then tags and pushes the tag — so a change to a skill is released in one step. Any agent that changes a skill must run it immediately, without asking for confirmation. It installs nothing anywhere; consumers get a change when they run `npx skills update` after a push. `AGENTS.md` documents the workflow for agents working on this repo.
 
 ### Releases
 
 Publishing is tag-driven. The `Publish` workflow (`.github/workflows/publish.yml`) validates every `skills/*/SKILL.md`, checks that the tag matches `package.json`, and publishes `@sassywares/skills` to npm on a `v*` tag push.
 
+`scripts/sync.sh` does this for you on `main`. The manual sequence is the fallback for recovering a failed run:
+
 ```bash
 npm version patch --no-git-tag-version
 git add -A && git commit -m "chore: release v$(node -p "require('./package.json').version")"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sassywares/skills",
-  "version": "0.5.4",
+  "version": "0.5.6",
   "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,7 @@ 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. 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.
 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,7 @@ 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.
 
 **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 +37,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 `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`.
 
 **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.
+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 — `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 `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/assets/sassywares-readme.md

@@ -19,7 +19,7 @@ The vendored skills and the lock are committed; `.claude/skills` is a link and i
 
 `.agents/skills/` is read by pi and Cursor; Claude Code reads `.claude/skills/` only, which is why that symlink exists. After any change, `/reload` your harness.
 
-If a skill tells you another skill is missing, run `skills:sync` and restart. Substituted package managers: run the same script through `npm`, `pnpm`, or `yarn`.
+If a skill tells you another skill is missing, run `npx skills add sassywares/sassy-skills` (or `npx skills experimental_install` to restore exactly what the lock pins) and restart.
 
 ## Config
 

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

@@ -0,0 +1,97 @@
+# 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
+
+```bash
+bash .agents/skills/sassy-setup/scripts/detect.sh --branch [--policy current|new]
+```
+
+`--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.
+
+Output:
+
+| Key | Meaning |
+|---|---|
+| `topology` | `repo`, `workspace`, or `none` |
+| `configured` | `commit.branch` from the config, or `none` |
+| `policy` | what actually applies: the token, else the config, else `new` |
+| `head` | the checked-out branch, or `none` when detached |
+| `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>` |
+| `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 |
+
+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.
+
+## 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.
+
+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. `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,
+   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`;
+   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`.
+
+### `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.
+
+### `refuse`
+
+Detached HEAD with `policy: current`, or `topology: none`. Report 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.
+
+## 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,15 @@ 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.
+
 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.
@@ -76,7 +85,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 +152,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 +224,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,19 @@
 # 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.
 set -euo pipefail
 
 ROOT_ARG=""
 HEAD_ARG=""
+POLICY_ARG=""
 CHECK=0
+BRANCH=0
 
 while (( $# )); do
   case "$1" in
@@ -20,8 +27,11 @@ 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#*=}" ;;
+    --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,14p' "${BASH_SOURCE[0]}" | sed 's|^# \{0,1\}||'; exit 0 ;;
     *) echo "unknown argument: $1" >&2; exit 2 ;;
   esac
   shift
@@ -414,6 +424,136 @@ if (( CHECK )); then
   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)"
+  [[ "$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)"
+      [[ -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)"
+    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() {
+    local want="$1" b
+    while IFS= read -r b; do
+      [[ "$b" == "$want" ]] && return 0
+    done < <(base_heads)
+    return 1
+  }
+
+  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'
+    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.
+    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
+      own=""
+      if [[ -f "$ROOT/$dir/.sassywares/config.yaml" ]]; then
+        own="$(yflat_in "$ROOT/$dir/.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)}"
+  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
+  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
+  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"
+  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 +672,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. Stop and ask, naming the branch and the 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. Finding the run's head on a base branch with unpublished commits is a stop-and-ask. |
 | 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-skill/SKILL.md

@@ -37,7 +37,7 @@ Ask which one, unless the request already made it obvious. The answer changes th
 
 | Location | Path | Who gets it | Extra work |
 |---|---|---|---|
-| **Internal** — part of this suite | `skills/<name>/` in the sassy-skills repo | Everyone, once pushed to `main` | Name it `sassy-<name>`, run `scripts/sync.sh`; the npm package follows the next tag |
+| **Internal** — part of this suite | `skills/<name>/` in the sassy-skills repo | Everyone, once pushed to `main` | Name it `sassy-<name>`, run `scripts/sync.sh` — it bumps the patch version, tags, and publishes |
 | **Project** — team workflow | `<repo>/.agents/skills/<name>/` | Everyone who clones that repo | Commit it; prefix the project (`tap2-…`) so it can't collide with a suite skill or a harness built-in |
 | **User** — personal workflow | `~/.agents/skills/<name>/` | Only this person, every repo on this machine | None — but nothing gates it either; never put something a teammate needs here |
 

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 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.
+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 `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. |