@sassywares/skills 0.3.1 → 0.4.0

package/README.md

@@ -271,52 +271,40 @@ sassy-skills/
 
 ## Installation
 
-The suite ships as the npm package **`@sassywares/skills`**. Pin it, don't symlink it into a global directory — the version in your lockfile is the pin, and upgrading is one command.
-
-### As a project dependency (recommended for teams)
+The suite installs from this repository with the open `skills` CLI. That CLI vendors the skill files into your project and pins them, so a clone needs no network and every checkout runs the same skills.
 
 ```bash
-bun add -d @sassywares/skills
+npx skills add sassywares/sassy-skills
 ```
 
-Nothing scans `node_modules` on its own, so give your harness the directory it does read:
+That writes three things:
 
-```bash
-mkdir -p .agents/skills
-for d in node_modules/@sassywares/skills/skills/*/; do
-  ln -sfn "../../$d" ".agents/skills/$(basename "$d")"
-done
-```
+- `.agents/skills/sassy-*` — the skill files themselves, read by pi and Cursor
+- `.claude/skills/sassy-*` — links for Claude Code, which reads only its own directory
+- `skills-lock.json` — source and content hash per skill
 
-`.agents/skills/` is read by Cursor and pi. Claude Code reads `.claude/skills/` only, so add one directory symlink:
+Commit the vendored skills and the lock; ignore `.claude/skills`, which is a link created at install time.
 
 ```bash
-mkdir -p .claude && ln -sfn ../.agents/skills .claude/skills
+npx skills update -y              # pull the latest from this repo
+npx skills experimental_install   # restore exactly what the lock pins
+npx skills remove                 # take the suite out again
 ```
 
-Ignore both: they're derived from the lockfile, like any build output. A `postinstall` that runs the loop gives teammates zero setup beyond `bun install`; a preflight in the skills tells anyone who skipped it what to run.
+`sassy-setup` does all of this for you, including the ignore line and the two package scripts.
 
-### As a pi package
-
-pi resolves packages directly, so no links are needed:
+### While editing the suite
 
-```bash
-pi install npm:@sassywares/skills@0.1.0            # user-level, all projects
-pi install npm:@sassywares/skills@0.1.0 --local     # project-level → commit .pi/settings.json
-```
+`.pi/settings.json` in this repo declares `./skills`, so pi loads your working copy directly. Consumers see a change once it is pushed to `main` and they run `npx skills update` — no release step in between.
 
-### While editing the suite
+### Also published as a package
 
-Point a consumer at your checkout instead of a published version:
+`@sassywares/skills` is on npm for harnesses that install packages rather than skill directories:
 
 ```bash
-bun link @sassywares/skills
+pi install npm:@sassywares/skills@0.4.0
 ```
 
-Inside this repo, `.pi/settings.json` already declares `./skills`, so pi loads the working copy directly.
-
-Get the skills however they arrive — package, link, or vendored copy — and invoke them with your harness's skill syntax.
-
 ## 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 — a change reaches consumers when a version is released and they bump their pin. `AGENTS.md` documents the workflow for agents working on this repo.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sassywares/skills",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "Lean, explicit-invocation Agent Skills for shipping fast: plan, work, review, validate, ship.",
   "type": "module",
   "license": "MIT",
@@ -24,7 +24,6 @@
   ],
   "files": [
     "skills",
-    "bin",
     "README.md",
     "CONCEPTS.md",
     "LICENSE"
@@ -37,7 +36,7 @@
       "./skills"
     ]
   },
-  "bin": {
-    "sassy-skills": "./bin/sassy-skills.mjs"
+  "engines": {
+    "node": ">=18"
   }
 }

package/skills/sassy-babysit/SKILL.md

@@ -50,9 +50,11 @@ Stop when any holds:
 - **Terminal** — merged or closed.
 - **Looks ready** — `MERGEABLE`, `CLEAN`, all checks terminal, no open review threads, no currency blocker, zero `needs-human` items. With `merge:on`, run the merge (and `delete-branch:on` branch deletion if set) before treating this as a stop; the merge turns it into the **Terminal** stop.
 
-  **Merge hooks.** Immediately before merging, run `hooks.pr.before_merge` in declared order — one `worker` per hook, brief carrying the PR URL and head SHA. A missing skill or a `blocked` result means **do not merge**: report it and stop at Blocked. After a successful merge, run `hooks.pr.after_merge` the same way; these follow the merge, so they must leave the tree clean. In a workspace fan-out, everything is per PR.
+  **Merge hooks.** Immediately before merging, run `hooks.pr.before_merge` in declared order — one `worker` per hook, with the same brief every hook gets: plan path, changed files, artifact paths, base, branch, commit hash, and the PR URL plus head SHA. These run before the merge, so they must leave the tree clean. A missing skill or a `blocked` result means **do not merge**: report it and stop at Blocked. After a successful merge, run `hooks.pr.after_merge` the same way; these follow the merge, so they must leave the tree clean. In a workspace fan-out, everything is per PR.
 
-  **Inert hooks.** With merging off, `before_merge` and `after_merge` cannot fire. Say so in one line — "not merging this run, merge hooks skipped" — rather than letting a declared hook vanish silently.
+  **Which merge hook fires.** `before_merge` needs a merge this run will perform. `after_merge` fires whenever this run observes the PR merged, including one that was already merged when the run started — so it must be idempotent.
+
+  **Inert hooks.** With merging off, `before_merge` never fires; say so. Say so in one line — "not merging this run, merge hooks skipped" — rather than letting a declared hook vanish silently.
 - **Blocked** — a `needs-human` item or a blocked-external dependency remains.
 - **Budget** — the requested duration or a 3-day backstop has elapsed.
 

package/skills/sassy-commit/SKILL.md

@@ -30,7 +30,7 @@ Treat the reads as a snapshot; re-read branch and staged set right before commit
 
 **Config.** Resolve `.sassywares/config.yaml` (nearest, walking up) per the `sassy-setup` skill's `references/config.md`. Precedence: explicit token > session instruction > config > skill default. `commit.branch` supplies the default.
 
-**Branch option.** `branch:current|new [<name>]`. `current` commits on the checked-out branch. `new` cuts a branch from `origin/<base>` — `<base>` is `repos[<dir>]` in a workspace config, else `git.default_branch`, else the probed base — named `<name>` when given, else from the change. `sassy-commit-push-pr` forwards its own `branch` choice here.
+**Branch option.** `branch:current|new [<name>]`. `current` commits on the checked-out branch. `new` cuts a branch from `origin/<base>` — `<base>` is `repos[<dir>]` in a workspace config, else `git.default_branch`, else the probed base **confirmed with the user** — named `<name>` when given, else from the change. `sassy-commit-push-pr` forwards its own `branch` choice here.
 
 **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 +38,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 origin <base>`, then `git checkout -b <name> origin/<base>`, then confirm `git merge-base HEAD origin/<base>` is `origin/<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 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.
 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

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

package/skills/sassy-debug/SKILL.md

@@ -25,8 +25,6 @@ Trivial bugs whose cause is readable from the input may skip the scout, but stil
 
 **Search prior learnings first.** Resolve `.sassywares/config.yaml` (nearest, walking up) per the `sassy-setup` skill's `references/config.md`. For every existing path in `knowledge.read`, search the docs for the symptom's keywords, the module, and the failure type. A matching doc **seeds or confirms** a hypothesis — it never replaces the causal chain or the reproduction. Name the docs you consulted, and say plainly when none matched: no match is not evidence that nothing similar has happened.
 
-**Update nudge.** Once per run, if `node_modules/.bin/sassy-skills` exists, run `sassy-skills outdated`. It is throttled to once a day per machine and silently does nothing offline. Pass any newer version on in one line; never block, retry, or fail on it.
-
 ## Phase 1 — Diagnose inline, with `scout` as a helper
 
 You own the diagnosis. The causal reasoning happens here, in the main context, because that is where the full picture lives and where the fix gate is presented.

package/skills/sassy-lfg/SKILL.md

@@ -16,8 +16,6 @@ disable-model-invocation: true
 
 **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.
 
-**Update nudge.** Once per run, if `node_modules/.bin/sassy-skills` exists, run `sassy-skills outdated`. It is throttled to once a day per machine and silently does nothing offline. Pass any newer version on in one line; never block, retry, or fail on it.
-
 ## Input
 
 Detect the shape from the argument:

package/skills/sassy-plan/SKILL.md

@@ -17,8 +17,6 @@ disable-model-invocation: true
 
 **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 land in `artifacts.plans`.
 
-**Update nudge.** Once per run, if `node_modules/.bin/sassy-skills` exists, run `sassy-skills outdated`. It is throttled to once a day per machine and silently does nothing offline. Pass any newer version on in one line; never block, retry, or fail on it.
-
 ## Phase A — Discuss (brainstorm)
 
 Have one focused discussion to turn the idea into something plannable.

package/skills/sassy-review/SKILL.md

@@ -13,8 +13,6 @@ disable-model-invocation: true
 
 **Outcome:** the scope reviewed with concrete findings; the approved fixes applied; everything left uncommitted.
 
-**Update nudge.** Once per run, if `node_modules/.bin/sassy-skills` exists, run `sassy-skills outdated`. It is throttled to once a day per machine and silently does nothing offline. Pass any newer version on in one line; never block, retry, or fail on it.
-
 **Orchestrator only.** Never edit code yourself. The `reviewer` finds; the `worker` fixes.
 
 ## Review dimensions

package/skills/sassy-setup/SKILL.md

@@ -20,7 +20,7 @@ disable-model-invocation: true
 ## Steps
 
 1. **Resolve the start.** The argument's path, else the working directory. If a `.sassywares/config.yaml` is already found walking up, this is a **verify run**: run the checks in step 7 and report, without rewriting anything.
-2. **Detect.** Run `scripts/detect.sh --root <path>`. It prints a proposed config: topology (`repo`, `workspace`, `none`), the remote name, a probed base branch, nested repos with their bases, and which artifact paths exist.
+2. **Detect.** Run `scripts/detect.sh --root <path>`. It prints a proposed config: topology (`repo`, `workspace`, `none`), the remote name, a probed base branch, and nested repos with their bases.
 3. **Ask only what detection cannot answer.** Never re-ask what the tree already said.
    - **`workspace`** — the snapshot mirror: create a **private** GitHub repo, or connect an existing one? Creating it needs explicit approval and a named slug first.
    - **`none`** — confirm the intent: this folder is deliberately outside git, so commit, PR, and babysit refuse here.
@@ -30,16 +30,14 @@ disable-model-invocation: true
    - **`pr.*`** — default `babysit: true`, `merge: false`, `delete_branch: false`. Say plainly that `merge: true` authorizes merging every babysat PR in this project without asking.
    - **Hooks** — offer, do not impose. Ask whether the project wants steps injected at `before_create`, `after_create`, `before_merge`, or `after_merge`, and write the skills they name. Leave them `[]` when they have nothing to add. **Never write a hook skill yourself** — hooks are project skills, and copying one of ours into that role is the fork this mechanism exists to prevent.
 4. **Write the config.** Build the file from the proposal plus the answers. It is written **fully commented**: every key keeps a description and its allowed values, exactly as the detector emits them. Never strip those comments to save lines — for a teammate opening the file, the comments are the documentation. If a config already exists, show what changes and ask before writing — never silently overwrite. Keep every key; an unset key falls back to its documented default, so a short file is legal when nothing deviates.
-5. **Wire the skills.** The suite is the package `@sassywares/skills`, and its own CLI creates the links. Never copy skill files into a project.
+5. **Wire the skills.** The suite is installed from upstream with the open `skills` CLI, which vendors the skill files into the project and pins them. Never copy skill files in by hand, never add the suite as a dependency.
 
-   - **It needs a `package.json`.** With none, say so and ask whether to add a minimal manifest or skip the wiring. Do not create one unasked, and do not invent a second distribution mechanism for non-JS projects.
-   - **Detect the package manager** from the lockfile: `bun.lock`/`bun.lockb`, `pnpm-lock.yaml`, `yarn.lock`, `package-lock.json`. Ask when several disagree or none exists.
-   - **Add the dependency pinned exactly** — `bun add --dev --exact @sassywares/skills@<version>`, `npm install --save-dev --save-exact …`, `pnpm add --save-dev --save-exact …`, `yarn add --dev --exact …`. Exact, because one pinned version for every teammate and every harness is the entire point.
-   - **Scripts**, adding only what is missing: `"skills:sync": "sassy-skills sync"`, `"skills:update": "sassy-skills update"`, and `"postinstall": "sassy-skills sync"`. **Never overwrite an existing `postinstall`** — if one is there, leave it alone and tell the user to chain `&& sassy-skills sync`, so setup cannot erase someone's install steps.
-   - **Run `sassy-skills sync`.** The package's CLI is now in `node_modules/.bin`; it links `.agents/skills/sassy-*` and creates `.claude/skills → ../.agents/skills`. The linking rules travel with the lockfile, so they upgrade with the suite instead of drifting in the repo.
-   - **Ignore the derived links.** Add `/.agents/skills/sassy-*` and `/.claude/skills` to `.gitignore` when missing. Create `.gitignore` only when there is none.
+   - **Install it**: `npx -y skills add sassywares/sassy-skills -y`. That writes `.agents/skills/sassy-*` (real files), per-agent links such as `.claude/skills/sassy-*`, and `skills-lock.json`.
+   - **Scripts**, adding only what is missing: `"skills:sync": "npx -y skills experimental_install"` (restores exactly what the lock pins) and `"skills:update": "npx -y skills update -y"` (pulls the latest from upstream). **Never rewrite an existing `postinstall`** — leave it alone and tell the user to chain what they need.
+   - **Commit the vendored skills and the lock.** `.agents/skills/sassy-*` and `skills-lock.json` are the pin; a clone then needs no network.
+   - **Ignore `.claude/skills` only.** It is a link created at install time. Create `.gitignore` only when there is none — and in `workspace` topology never touch the project's root `.gitignore` at all.
    - **Write `.sassywares/README.md`** from `assets/sassywares-readme.md` when absent. Never overwrite it — it may carry project notes.
-   - **Tell the user to `/reload`.** The links are invisible to the harness until it rescans.
+   - **Tell the user to `/reload`.** The skills are invisible to the harness until it rescans.
 
 6. **Install the snapshot, `workspace` only.** Read `references/workspace.md` and follow it.
 
@@ -55,9 +53,9 @@ disable-model-invocation: true
 | No silent overwrite | An existing config or an existing `.sassywares/workspace/snapshot` is shown and asked about, never replaced blind. |
 | Version is reported | Setup names the snapshot version it installed; `--check` flags an installed copy older than the skill's. |
 | Never commit | Setup writes files and stops. Committing is `sassy-commit`. |
-| Skills are a dependency | Pin `@sassywares/skills`; never copy skill files into a project or maintain hand-made links. |
+| Skills come from upstream | Install with `npx skills add`; never hand-copy skill files or maintain the links yourself. |
 | Scripts are shared | Adding a missing script is fine; rewriting an existing `postinstall` or `skills:*` entry is not. |
-| Write boundary | Only `.sassywares/`, the `package.json` scripts and devDependency, the lockfile, and two `.gitignore` lines. Never skill content. |
+| Write boundary | Only `.sassywares/`, the vendored `.agents/skills/sassy-*`, `skills-lock.json`, two `package.json` scripts, and one `.gitignore` line. Never a root `.gitignore` in a workspace. |
 | Detect, don't guess | An unknown base branch stays unknown and gets asked about. A probed value is reported as probed. |
 | Comments are part of the file | Every key keeps its description and allowed values. A stripped config is an incomplete config. |
 | Hooks are named, not written | Setup records hook skill names. Creating those skills is the project's work. |

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

@@ -4,14 +4,16 @@ Project config and tooling for the Sassy Skills suite. Written by `sassy-setup`.
 
 ## Skills
 
-Installed as the npm package `@sassywares/skills`, pinned exactly in `package.json`. The entries in `.agents/skills/` and the `.claude/skills` symlink are **derived** from that package — never edit them by hand and never commit them.
+Installed from upstream with the open `skills` CLI, which vendors the skills into
+`.agents/skills/` and pins them in `skills-lock.json`:
 
 ```bash
-bun run skills:sync     # recreate the links after a fresh clone
-bun run skills:update   # bump to the latest published version, then relink
+npx skills add sassywares/sassy-skills   # first install
+bun run skills:sync                       # restore exactly what the lock pins
+bun run skills:update                     # pull the latest from upstream
 ```
 
-Skills print a one-line nudge when a newer version is published — once a day, and silently nothing when offline. It is never a blocker.
+The vendored skills and the lock are committed; `.claude/skills` is a link and is not.
 
 `.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.
 
@@ -22,7 +24,7 @@ If a skill tells you another skill is missing, run `skills:sync` and restart. Su
 `config.yaml` holds the project's paths, git topology, and PR defaults. Every key is documented inline, including its allowed values, and the full schema is in the `sassy-setup` skill's `references/config.md`. Verify the file still matches the tree:
 
 ```bash
-node_modules/@sassywares/skills/skills/sassy-setup/scripts/detect.sh --root . --check
+.agents/skills/sassy-setup/scripts/detect.sh --root . --check
 ```
 
 ## Hooks

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

@@ -168,9 +168,9 @@ first commit, then passed to every repo. Multi-repo runs pass
 Cut from the base, then verify:
 
 ```
-git fetch origin <base>
-git checkout -b <name> origin/<base>
-git merge-base HEAD origin/<base>   # must be origin/<base>
+git fetch <remote> <base>
+git checkout -b <name> <remote>/<base>
+git merge-base HEAD <remote>/<base>   # must be <remote>/<base>
 ```
 
 An ancestry check that fails means the branch was cut from the wrong base —

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

@@ -25,6 +25,8 @@ done
 
 START="${ROOT_ARG:-$PWD}"
 [[ -d "$START" ]] || { echo "not a directory: $START" >&2; exit 2; }
+# Absolute, or the walk-up loop below re-reads "." forever.
+START="$(cd "$START" && pwd -P)"
 
 SKILL_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
 ASSET_SNAPSHOT="$SKILL_DIR/assets/snapshot"
@@ -38,8 +40,24 @@ while :; do
   probe="$(dirname "$probe")"
 done
 
+# A --check run validates the config against the tree the CONFIG describes, which
+# is not the git toplevel when you are standing inside one of its nested repos.
+if [[ -n "$CONFIG" ]]; then
+  ROOT="${CONFIG%/.sassywares/config.yaml}"
+  if git -C "$ROOT" rev-parse --show-toplevel >/dev/null 2>&1; then
+    TOPOLOGY="repo"
+  else
+    TOPOLOGY="workspace"
+    shopt -s nullglob
+    NESTED_FOUND=0
+    for child in "$ROOT"/*/; do
+      [[ -d "$child/.git" ]] && { NESTED_FOUND=1; break; }
+    done
+    shopt -u nullglob
+    [[ "$NESTED_FOUND" -eq 1 ]] || TOPOLOGY="none"
+  fi
 # Topology root: the git toplevel when inside a work tree, else the start dir.
-if TOPLEVEL="$(git -C "$START" rev-parse --show-toplevel 2>/dev/null)"; then
+elif TOPLEVEL="$(git -C "$START" rev-parse --show-toplevel 2>/dev/null)"; then
   ROOT="$TOPLEVEL"
   TOPOLOGY="repo"
 else
@@ -96,8 +114,10 @@ detect_base() {
 }
 
 remote_name() {
-  local dir="$1"
-  git -C "$dir" remote 2>/dev/null | head -n 1
+  local dir="$1" remotes
+  remotes="$(git -C "$dir" remote 2>/dev/null)"
+  if printf '%s\n' "$remotes" | grep -qx origin; then printf 'origin'; return 0; fi
+  printf '%s\n' "$remotes" | head -n 1
 }
 
 nested_repos() {
@@ -131,7 +151,8 @@ case "$TOPOLOGY" in
   repo)
     REPO_NAME="$(remote_name "$ROOT")"
     REPO_NAME="${REPO_NAME:-origin}"
-    DEFAULT_BRANCH="$(detect_base "$ROOT")"
+    # A check run reads the base from the config; probing costs a network call.
+    (( CHECK )) || DEFAULT_BRANCH="$(detect_base "$ROOT")"
     ;;
   workspace)
     MIRROR_REMOTE="$(config_value remote 2>/dev/null || true)"
@@ -174,14 +195,13 @@ if (( CHECK )); then
 
   if [[ "$TOPOLOGY" == "repo" ]]; then
     configured_base="$(config_value default_branch 2>/dev/null || true)"
+    [[ -n "$configured_base" ]] || DEFAULT_BRANCH="$(detect_base "$ROOT")"
     if [[ -z "$configured_base" ]]; then
       bad "git.default_branch is unset — name the branch new work is cut from"
     elif [[ -n "$DEFAULT_BRANCH" && "$configured_base" != "$DEFAULT_BRANCH" ]]; then
       # A team base is a policy choice: staging, dev, or the release branch can
       # all differ from the remote default. Report it, do not call it drift.
       note "  default_branch '$configured_base' overrides the remote default '$DEFAULT_BRANCH' — expected when PRs target a team base"
-    elif [[ -z "$DEFAULT_BRANCH" ]]; then
-      note "  remote default undetectable — '$configured_base' taken as declared"
     fi
     configured_remote="$(config_value remote 2>/dev/null || true)"
     [[ -z "$configured_remote" ]] || bad "git.remote is set but git.repo is not workspace"

package/skills/sassy-ship/SKILL.md

@@ -6,7 +6,7 @@ description: >-
   delegated to subagents. Default `mode:manual` presents a shipping summary and
   waits before anything is written, committed, pushed, or opened. `mode:auto`
   runs the close-out with no review.
-argument-hint: "<plan path or topic> [steps:compound,handbook,commit,pr,babysit] [merge:on|off] [delete-branch:on|off] [mode:manual|auto]"
+argument-hint: "<plan path or topic> [steps:compound,handbook,commit,pr,babysit] [base:<branch>] [merge:on|off] [delete-branch:on|off] [mode:manual|auto]"
 disable-model-invocation: true
 ---
 
@@ -18,8 +18,6 @@ disable-model-invocation: true
 
 **Config.** Resolve `.sassywares/config.yaml` (nearest, walking up) per the `sassy-setup` skill's `references/config.md`. Precedence: explicit token > session instruction > config > skill default. `pr.babysit`, `pr.merge`, and `pr.delete_branch` seed the close-out; `git.repo` decides whether this run commits, snapshots, or refuses; `hooks.pr.*` adds project steps to the PR pipeline.
 
-**Update nudge.** Once per run, if `node_modules/.bin/sassy-skills` exists, run `sassy-skills outdated`. It is throttled to once a day per machine and silently does nothing offline. Pass any newer version on in one line; never block, retry, or fail on it.
-
 **Subagent-maximal by design.** The orchestrator delegates every heavy step (docs, tree reads, git, gh) to subagents and only receives compact summaries. It never reads diffs, file contents, or the tree itself.
 
 ## Steps (in order)
@@ -31,7 +29,7 @@ disable-model-invocation: true
    - **`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: 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`* (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 `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.
+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 `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.
 
    **The PR step owns the PR hooks.** `before_create` and `after_create` run inside `sassy-commit-push-pr`, once per PR; ship neither runs nor repeats them.
 6. **Babysit.** With `pr.babysit` (default `true`), dispatch a `worker`: *load the `sassy-babysit` skill and follow it for the PR just created, one checkpoint*, forwarding any `merge:on|off` and `delete-branch:on|off` the caller supplied, else `pr.merge` and `pr.delete_branch`. It reports looks-ready or blocked. For a continuous watch, tell the user to run `sassy-babysit` in-session.

package/skills/sassy-validate/SKILL.md

@@ -13,8 +13,6 @@ disable-model-invocation: true
 
 **Outcome:** a grounded conformance judgment against an intent; the approved gaps closed; everything left uncommitted.
 
-**Update nudge.** Once per run, if `node_modules/.bin/sassy-skills` exists, run `sassy-skills outdated`. It is throttled to once a day per machine and silently does nothing offline. Pass any newer version on in one line; never block, retry, or fail on it.
-
 **Orchestrator only.** Never edit code yourself. The `validator` finds gaps; the `worker` closes them.
 
 **This skill needs an intent.** Validation without something to validate against is meaningless. If the user gave no plan path or intent, ask for one before doing anything.

package/skills/sassy-work/SKILL.md

@@ -19,8 +19,6 @@ disable-model-invocation: true
 
 **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.
 
-**Update nudge.** Once per run, if `node_modules/.bin/sassy-skills` exists, run `sassy-skills outdated`. It is throttled to once a day per machine and silently does nothing offline. Pass any newer version on in one line; never block, retry, or fail on it.
-
 ## Input
 
 Detect the shape from the argument:

package/bin/sassy-skills.mjs

@@ -1,193 +0,0 @@
-#!/usr/bin/env node
-// sassy-skills — wire this package's skills into a project.
-//
-// Nothing scans node_modules on its own, so the harnesses that read a project
-// skills directory need links. This tool creates them, checks them, and updates
-// the pinned version.
-//
-//   sassy-skills sync            link skills into .agents/skills (and .claude/skills)
-//   sassy-skills check           exit 1 if the wiring is missing or stale
-//   sassy-skills update          bump to the latest published version, then sync
-//
-// Options: --root <dir>  --quiet  --help
-import { existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, readlinkSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { execFileSync } from "node:child_process";
-import { dirname, join, resolve } from "node:path";
-import { fileURLToPath } from "node:url";
-
-const HERE = dirname(fileURLToPath(import.meta.url));
-const SKILLS_DIR = resolve(HERE, "..", "skills");
-const PKG = JSON.parse(readFileSync(resolve(HERE, "..", "package.json"), "utf8"));
-const NAME = PKG.name;
-const VERSION = PKG.version;
-const REGISTRY = process.env.SASSY_SKILLS_REGISTRY ?? "https://registry.npmjs.org";
-
-const args = process.argv.slice(2);
-const quiet = args.includes("--quiet");
-const rootFlag = args.indexOf("--root");
-const rootValueIndex = rootFlag >= 0 ? rootFlag + 1 : -1;
-const ROOT = rootFlag >= 0 ? resolve(args[rootFlag + 1] ?? ".") : process.cwd();
-if (args.includes("--help") || args.includes("-h")) {
-  console.log(`sassy-skills@${VERSION}\n\n  sync     link skills into .agents/skills and .claude/skills\n  check    exit 1 when the wiring is missing or stale\n  update   bump ${NAME} to the latest version, then sync\n  outdated print a one-line nudge when a newer version is published (throttled, offline-safe)\n\nOptions: --root <dir>  --quiet  --force`);
-  process.exit(0);
-}
-
-const command = args.find((a, i) => !a.startsWith("-") && i !== rootValueIndex) ?? "sync";
-
-const log = (...a) => { if (!quiet) console.log(...a); };
-const ok = (m) => log(`  ✓ ${m}`);
-const warn = (m) => console.error(`  ! ${m}`);
-const die = (m) => { console.error(`  ✗ ${m}`); process.exit(1); };
-
-const IS_WIN = process.platform === "win32";
-
-function linkedSkills() {
-  if (!existsSync(SKILLS_DIR)) die(`package has no skills/ directory at ${SKILLS_DIR}`);
-  return readdirSync(SKILLS_DIR, { withFileTypes: true })
-    .filter((e) => e.isDirectory() && existsSync(join(SKILLS_DIR, e.name, "SKILL.md")))
-    .map((e) => e.name)
-    .sort();
-}
-
-function makeLink(target, linkPath) {
-  try {
-    if (lstatSync(linkPath).isSymbolicLink()) rmSync(linkPath);
-    else { warn(`${linkPath} exists and is not a symlink — leaving it alone`); return false; }
-  } catch { /* does not exist */ }
-  symlinkSync(target, linkPath, IS_WIN ? "junction" : "dir");
-  return true;
-}
-
-function sync() {
-  const skills = linkedSkills();
-  const agents = join(ROOT, ".agents", "skills");
-  mkdirSync(agents, { recursive: true });
-
-  let made = 0;
-  for (const name of skills) {
-    const target = resolve(SKILLS_DIR, name);
-    if (makeLink(target, join(agents, name))) made++;
-  }
-  ok(`${skills.length} skills linked into .agents/skills (${NAME}@${VERSION})`);
-
-  // Claude Code reads .claude/skills only. A directory symlink is enough, and it
-  // is the least invasive form when the directory does not already exist.
-  const claude = join(ROOT, ".claude", "skills");
-  try {
-    const st = lstatSync(claude);
-    if (!st.isSymbolicLink()) {
-      warn(".claude/skills exists and is not a symlink — Claude Code will not see the project skills unless you link them yourself");
-    }
-  } catch {
-    mkdirSync(dirname(claude), { recursive: true });
-    symlinkSync(IS_WIN ? join(ROOT, ".agents", "skills") : "../.agents/skills", claude, IS_WIN ? "junction" : "dir");
-    ok("linked .claude/skills → .agents/skills");
-  }
-
-  if (made) log(`\nRestart or /reload your harness to pick up the new skills.`);
-  return 0;
-}
-
-function check() {
-  const skills = linkedSkills();
-  const agents = join(ROOT, ".agents", "skills");
-  let problems = 0;
-
-  for (const name of skills) {
-    const link = join(agents, name);
-    const target = resolve(SKILLS_DIR, name);
-    try {
-      const st = lstatSync(link);
-      if (!st.isSymbolicLink()) { warn(`${name}: real directory, not a link`); problems++; continue; }
-      const points = resolve(agents, readlinkSync(link));
-      if (points !== target) { warn(`${name}: points at ${points}, expected ${target}`); problems++; }
-    } catch {
-      warn(`${name}: not linked`);
-      problems++;
-    }
-  }
-  if (!existsSync(join(ROOT, ".claude", "skills"))) warn(".claude/skills missing (Claude Code only)");
-  if (problems) { console.error(`  ✗ ${problems} skill link(s) need attention — run: sassy-skills sync`); return 1; }
-  ok(`${skills.length} skills correctly linked (${NAME}@${VERSION})`);
-  return 0;
-}
-
-function detectPM() {
-  if (existsSync(join(ROOT, "bun.lock")) || existsSync(join(ROOT, "bun.lockb"))) return "bun";
-  if (existsSync(join(ROOT, "pnpm-lock.yaml"))) return "pnpm";
-  if (existsSync(join(ROOT, "yarn.lock"))) return "yarn";
-  if (existsSync(join(ROOT, "package-lock.json"))) return "npm";
-  return null;
-}
-
-function update() {
-  const pm = detectPM();
-  if (!pm) die("no lockfile found — cannot tell which package manager to update with");
-  const spec = `${NAME}@latest`;
-  const cmd = {
-    bun: ["bun", ["add", "--dev", "--exact", spec]],
-    npm: ["npm", ["install", "--save-dev", "--save-exact", spec]],
-    pnpm: ["pnpm", ["add", "--save-dev", "--save-exact", spec]],
-    yarn: ["yarn", ["add", "--dev", "--exact", spec]],
-  }[pm];
-  log(`Updating ${NAME} with ${pm}…`);
-  execFileSync(cmd[0], cmd[1], { cwd: ROOT, stdio: "inherit" });
-  return sync();
-}
-
-function newerThan(a, b) {
-  const pa = String(a).split(/[.+-]/).map((x) => parseInt(x, 10) || 0);
-  const pb = String(b).split(/[.+-]/).map((x) => parseInt(x, 10) || 0);
-  for (let i = 0; i < 3; i++) {
-    if ((pa[i] ?? 0) !== (pb[i] ?? 0)) return (pa[i] ?? 0) > (pb[i] ?? 0);
-  }
-  return false;
-}
-
-function updateHint() {
-  const pm = detectPM();
-  const script = pm === "bun" ? "bun run skills:update"
-    : pm ? `${pm} run skills:update`
-    : "sassy-skills update";
-  return script;
-}
-
-// Non-blocking version nudge. Throttled to once a day per machine, silent when
-// offline, and it never fails a run — a stale pin is worth mentioning, not
-// worth blocking work over.
-async function outdated(force = false) {
-  const cacheFile = join(tmpdir(), "sassy-skills-version-check.json");
-  const TTL = 24 * 60 * 60 * 1000;
-  let cached = null;
-  try { cached = JSON.parse(readFileSync(cacheFile, "utf8")); } catch { /* first run */ }
-
-  let latest = null;
-  const fresh = cached && typeof cached.checkedAt === "number" && Date.now() - cached.checkedAt < TTL;
-  if (fresh && !force) {
-    latest = cached.latest ?? null;
-  } else {
-    try {
-      const res = await fetch(`${REGISTRY}/${encodeURIComponent(NAME)}/latest`, {
-        signal: AbortSignal.timeout(2000),
-        headers: { accept: "application/json" },
-      });
-      const body = await res.json();
-      latest = typeof body?.version === "string" ? body.version : null;
-    } catch { latest = null; }
-    try { writeFileSync(cacheFile, JSON.stringify({ checkedAt: Date.now(), latest })); } catch { /* read-only tmp */ }
-  }
-
-  if (!latest || !newerThan(latest, VERSION)) return 0;
-  console.log(`  ↑ ${NAME} ${VERSION} → ${latest} available — ${updateHint()}`);
-  return 0;
-}
-
-switch (command) {
-  case "outdated": process.exit(await outdated(args.includes("--force")));
-  case "sync": process.exit(sync());
-  case "check": process.exit(check());
-  case "update": process.exit(update());
-  default:
-    die(`unknown command: ${command} (try --help)`);
-}

package/skills/sassy-plan/marker

@@ -1 +0,0 @@
-keep