@sassywares/skills 0.3.0 → 0.3.2

package/README.md

@@ -276,33 +276,26 @@ The suite ships as the npm package **`@sassywares/skills`**. Pin it, don't symli
 ### As a project dependency (recommended for teams)
 
 ```bash
-bun add -d @sassywares/skills
+bun add --dev --exact @sassywares/skills@0.3.2
 ```
 
-Nothing scans `node_modules` on its own, so give your harness the directory it does read:
+Nothing scans `node_modules` on its own, so link it where harnesses look — the package does that itself:
 
 ```bash
-mkdir -p .agents/skills
-for d in node_modules/@sassywares/skills/skills/*/; do
-  ln -sfn "../../$d" ".agents/skills/$(basename "$d")"
-done
+bunx sassy-skills sync
 ```
 
-`.agents/skills/` is read by Cursor and pi. Claude Code reads `.claude/skills/` only, so add one directory symlink:
+That writes `.agents/skills/sassy-*` (read by pi and Cursor) and the `.claude/skills` link Claude Code needs. Add it as `"postinstall": "sassy-skills sync"` and teammates need nothing beyond `bun install`.
 
-```bash
-mkdir -p .claude && ln -sfn ../.agents/skills .claude/skills
-```
-
-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.
+Ignore both paths — they're derived from the lockfile, like any build output. `sassy-setup` does all of this for you, including the gitignore lines and the pinned version.
 
 ### As a pi package
 
 pi resolves packages directly, so no links are needed:
 
 ```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 install npm:@sassywares/skills@0.3.2            # user-level, all projects
+pi install npm:@sassywares/skills@0.3.2 --local     # project-level → commit .pi/settings.json
 ```
 
 ### While editing the suite

package/bin/sassy-skills.mjs

@@ -8,9 +8,10 @@
 //   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
+//   sassy-skills outdated        one-line nudge when a newer version is published
 //
-// Options: --root <dir>  --quiet  --help
-import { existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, readlinkSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
+// Options: --root <dir>  --quiet  --force  --help
+import { existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, readlinkSync, rmSync, statSync, symlinkSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { execFileSync } from "node:child_process";
 import { dirname, join, resolve } from "node:path";
@@ -27,7 +28,17 @@ 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();
+const rootArg = rootFlag >= 0 ? args[rootFlag + 1] : undefined;
+if (rootFlag >= 0 && (!rootArg || rootArg.startsWith("-"))) {
+  console.error("  ✗ --root needs a directory");
+  process.exit(2);
+}
+const ROOT = rootArg ? resolve(rootArg) : process.cwd();
+if (rootFlag >= 0) {
+  let ok = false;
+  try { ok = statSync(ROOT).isDirectory(); } catch { ok = false; }
+  if (!ok) { console.error(`  ✗ --root ${ROOT} is not an existing directory`); process.exit(2); }
+}
 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);
@@ -50,13 +61,22 @@ function linkedSkills() {
     .sort();
 }
 
+// Returns "linked", "kept", or "blocked". A blocked path is a real directory the
+// user owns: never replaced, and always a failure, because the wiring is then
+// incomplete and nothing the tool can do will fix it.
 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; }
+    const st = lstatSync(linkPath);
+    if (st.isSymbolicLink()) {
+      if (resolve(dirname(linkPath), readlinkSync(linkPath)) === target) return "kept";
+      rmSync(linkPath);
+    } else {
+      warn(`${linkPath} is a real directory, not a link — move it aside; nothing was replaced`);
+      return "blocked";
+    }
   } catch { /* does not exist */ }
   symlinkSync(target, linkPath, IS_WIN ? "junction" : "dir");
-  return true;
+  return "linked";
 }
 
 function sync() {
@@ -64,12 +84,21 @@ function sync() {
   const agents = join(ROOT, ".agents", "skills");
   mkdirSync(agents, { recursive: true });
 
-  let made = 0;
+  let linked = 0;
+  let blocked = 0;
   for (const name of skills) {
     const target = resolve(SKILLS_DIR, name);
-    if (makeLink(target, join(agents, name))) made++;
+    const result = makeLink(target, join(agents, name));
+    if (result === "linked") linked++;
+    else if (result === "blocked") blocked++;
+  }
+  if (blocked) {
+    console.error(`  ✗ ${blocked} of ${skills.length} skills could not be linked — see above`);
+    return 1;
   }
-  ok(`${skills.length} skills linked into .agents/skills (${NAME}@${VERSION})`);
+  ok(linked
+    ? `${skills.length} skills linked into .agents/skills (${NAME}@${VERSION})`
+    : `${skills.length} skills already linked (${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.
@@ -77,7 +106,13 @@ function sync() {
   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");
+      warn(".claude/skills is a real directory — Claude Code will not see the project skills until you link them");
+      return 1;
+    }
+    const points = resolve(dirname(claude), readlinkSync(claude));
+    if (points !== resolve(agents)) {
+      warn(`.claude/skills points at ${points}, not .agents/skills — relink it`);
+      return 1;
     }
   } catch {
     mkdirSync(dirname(claude), { recursive: true });
@@ -85,7 +120,7 @@ function sync() {
     ok("linked .claude/skills → .agents/skills");
   }
 
-  if (made) log(`\nRestart or /reload your harness to pick up the new skills.`);
+  if (linked) log(`\nRestart or /reload your harness to pick up the new skills.`);
   return 0;
 }
 
@@ -107,7 +142,14 @@ function check() {
       problems++;
     }
   }
-  if (!existsSync(join(ROOT, ".claude", "skills"))) warn(".claude/skills missing (Claude Code only)");
+  const claude = join(ROOT, ".claude", "skills");
+  try {
+    const st = lstatSync(claude);
+    if (!st.isSymbolicLink()) { warn(".claude/skills is a real directory, so Claude Code sees none of these"); problems++; }
+    else if (resolve(dirname(claude), readlinkSync(claude)) !== resolve(agents)) {
+      warn(".claude/skills points somewhere else"); problems++;
+    }
+  } catch { 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;
@@ -132,7 +174,22 @@ function update() {
     yarn: ["yarn", ["add", "--dev", "--exact", spec]],
   }[pm];
   log(`Updating ${NAME} with ${pm}…`);
-  execFileSync(cmd[0], cmd[1], { cwd: ROOT, stdio: "inherit" });
+  try {
+    execFileSync(cmd[0], cmd[1], { cwd: ROOT, stdio: "inherit" });
+  } catch {
+    die(`${pm} could not update ${NAME} — nothing was relinked`);
+  }
+  // The running copy is the old version; its skills directory may be gone. Hand
+  // over to the freshly installed binary so the linker matches the new package.
+  const fresh = join(ROOT, "node_modules", ".bin", "sassy-skills");
+  if (existsSync(fresh)) {
+    try {
+      execFileSync(fresh, ["sync", "--root", ROOT], { stdio: "inherit" });
+    } catch {
+      die("updated, but the new binary could not relink — run: sassy-skills sync");
+    }
+    return 0;
+  }
   return sync();
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sassywares/skills",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "description": "Lean, explicit-invocation Agent Skills for shipping fast: plan, work, review, validate, ship.",
   "type": "module",
   "license": "MIT",
@@ -39,5 +39,8 @@
   },
   "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,7 +25,7 @@ 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.
+**Update nudge.** Once per run, if `node_modules/.bin/sassy-skills` exists, run `node_modules/.bin/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
 

package/skills/sassy-lfg/SKILL.md

@@ -16,7 +16,7 @@ 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.
+**Update nudge.** Once per run, if `node_modules/.bin/sassy-skills` exists, run `node_modules/.bin/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
 

package/skills/sassy-plan/SKILL.md

@@ -17,7 +17,7 @@ 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.
+**Update nudge.** Once per run, if `node_modules/.bin/sassy-skills` exists, run `node_modules/.bin/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)
 

package/skills/sassy-review/SKILL.md

@@ -13,7 +13,7 @@ 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.
+**Update nudge.** Once per run, if `node_modules/.bin/sassy-skills` exists, run `node_modules/.bin/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.
 

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.
@@ -37,7 +37,7 @@ disable-model-invocation: true
    - **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.
+   - **Ignore the derived links — `repo` topology only.** Add `/.agents/skills/sassy-*` and `/.claude/skills` to `.gitignore` when missing, creating it only when there is none. In `workspace` topology never touch the project's root `.gitignore`; the snapshot's own ignore file covers that case.
    - **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.
 
@@ -57,7 +57,7 @@ disable-model-invocation: true
 | 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. |
 | 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 `package.json` scripts and devDependency, the lockfile, and — in `repo` topology — two `.gitignore` lines. Never skill content, and 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/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,7 +18,7 @@ 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.
+**Update nudge.** Once per run, if `node_modules/.bin/sassy-skills` exists, run `node_modules/.bin/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.
 
@@ -31,7 +31,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-skill/SKILL.md

@@ -1,17 +1,20 @@
 ---
 name: sassy-skill
 description: >-
-  Create, retune, or improve an Agent Skill for pi. Use when asked to create a
-  skill, turn a workflow into a skill, fix a skill's description or triggering,
-  restructure a bloated skill, or retune an existing one. Writes to the user or
-  project skill directory and follows pi's Agent Skills rules.
+  Create, retune, or improve an Agent Skill. Asks where the skill should live —
+  inside this suite, in a project, or for one user — then writes it there with
+  the rules and release steps that location requires. Use when asked to create a
+  skill, turn a workflow into a skill, fix a description or triggering,
+  restructure a bloated skill, or retune an existing one.
 argument-hint: "[create|retune] [name, idea, or skill path]"
 disable-model-invocation: true
 ---
 
 # Sassy Skill
 
-**Outcome:** a well-formed Agent Skill directory installed at the user or project location, or an existing skill improved and re-verified. Pi's loader accepts it with no diagnostics.
+**Outcome:** a well-formed Agent Skill at a location the user chose, or an existing skill improved and re-verified. The harness loads it with no diagnostics.
+
+**Locations are not interchangeable** — they decide who gets the skill, how it ships, and what it may be called. Ask before writing.
 
 **Scope:** skills only — not extensions, packages, or prompt templates.
 
@@ -22,11 +25,26 @@ disable-model-invocation: true
 - **Description:** required, ≤1024 chars. Pi advertises name + description at startup; the body loads only when the skill is used. The description decides whether the skill ever fires — write **what it does and when to use it**.
 - **Frontmatter fields:** `name`, `description` (required); optional `license`, `compatibility`, `metadata`, `allowed-tools`, `disable-model-invocation`.
 - Use `disable-model-invocation: true` for skills that should run only via explicit `/skill:name`.
-- **Locations:** user `~/.agents/skills/<name>/`; project `<repo>/.agents/skills/<name>/` (discovered from cwd up to the repo root). Also the `skills` array in settings and pi packages.
 - **Reference other skills by name, never by absolute path.** The suite can live in `~/.agents/skills/`, a project `.agents/skills/`, or inside `node_modules/`, so "load the sassy-commit skill" is portable where a `~/…` path is not. Name a bundled file as "the sassy-setup skill's `references/config.md`".
 - Pi **validates at startup**; malformed or descriptionless skills warn. `/reload` applies changes.
 - Pi implements the **Agent Skills specification** (agentskills.io). For the full spec, pi's own `docs/skills.md` is authoritative — read it when the rules here are not enough.
 
+## Where the skill lives
+
+Ask which one, unless the request already made it obvious. The answer changes the name, the sharing, and whether a release is needed.
+
+| Location | Path | Who gets it | Extra work |
+|---|---|---|---|
+| **Internal** — part of this suite | `skills/<name>/` in the sassy-skills repo | Everyone, after a release | Name it `sassy-<name>`, bump `package.json`, run `scripts/sync.sh`, then tag to publish |
+| **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 |
+
+Recommend by audience: the team needs it → **project**; only the requester → **user**; it belongs to every project using this suite → **internal**.
+
+Internal is the only one that implies a release. Never choose it silently: from the moment it lands, consumers see it only when they bump their pin. Say that out loud when you do.
+
+Paths in the table are the defaults. Harnesses also read `skills` arrays in settings and installed packages, so a skill may live elsewhere — write down where it actually went.
+
 ## Shape rule — the lean rule
 
 - **Default to one `SKILL.md`.**
@@ -36,7 +54,7 @@ disable-model-invocation: true
 
 ## Workflow
 
-1. **Intake.** What the skill does, when it should trigger, and whether it is **user-level** or **project-level**. For a retune, read the existing skill and name the specific failure (won't trigger, too long, wrong steps, stale).
+1. **Intake.** What the skill does, when it should trigger, and **where it lives** — internal, project, or user (see above). Ask; do not infer from the cwd. For a retune, read the existing skill and name the specific failure (won't trigger, too long, wrong steps, stale, wrong scope).
 2. **Choose the shape.** Single file, or `SKILL.md` + `references/` per the rule above.
 3. **Write the frontmatter.** A description that states both what and when.
 4. **Write the body.** Outcome, a hard-rules table, the workflow, and reference pointers. Plain English. Structured output where the skill returns a result. Match this setup's house style.
@@ -59,7 +77,7 @@ When asked to retune or improve a skill, change the **smallest** thing that fixe
 - **Won't trigger** → rewrite the description (what + when, concrete verbs).
 - **Too long / bloated** → extract conditional content to `references/`, or delete what never gets used.
 - **Wrong or stale steps** → correct the workflow against the current tree.
-- **Wrong scope** → move it between user and project locations.
+- **Wrong scope** → move it between internal, project, and user. Moving into the suite is a release; moving out of it means the next release drops the skill for everyone.
 
 Re-verify after any retune.
 

package/skills/sassy-validate/SKILL.md

@@ -13,7 +13,7 @@ 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.
+**Update nudge.** Once per run, if `node_modules/.bin/sassy-skills` exists, run `node_modules/.bin/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.
 

package/skills/sassy-work/SKILL.md

@@ -19,7 +19,7 @@ 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.
+**Update nudge.** Once per run, if `node_modules/.bin/sassy-skills` exists, run `node_modules/.bin/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
 

package/skills/sassy-plan/marker

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