@sassywares/skills 0.5.8 → 0.5.10

package/README.md

@@ -115,7 +115,7 @@ Debugging:
 | Skill | What it does |
 |---|---|
 | **`sassy-skill`** | Creates, retunes, or restructures Agent Skills. |
-| **`sassy-setup`** | Detects the project topology and writes `.sassywares/config.yaml`; installs the snapshot tooling for a multi-repo workspace. |
+| **`sassy-setup`** | Detects the project topology and writes `.sassywares/config.yaml`; installs the snapshot tooling for a multi-repo workspace; commits the files it wrote. `mode:check` verifies an existing setup, including the vendored pin. |
 | **`sassy-compare`** | Runs one prompt against two models in isolated worktrees, with optional per-side thinking levels, and compares output, code changes, timing, tokens, and errors. |
 
 ## Project config
@@ -305,7 +305,9 @@ npx skills experimental_install   # restore exactly what the lock pins
 npx skills remove                 # take the suite out again
 ```
 
-`sassy-setup` does all of this for you, including the ignore line and the two package scripts.
+`npx skills check` is an alias for `update`: it moves the pin, it does not validate it. To check a project's setup without touching the pin, run `sassy-setup` with `mode:check`.
+
+`sassy-setup` does all of this for you — installing the suite, adding the ignore line, verifying the pin, and committing what it wrote.
 
 ### While editing the suite
 

package/package.json

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

package/skills/sassy-commit/SKILL.md

@@ -42,10 +42,11 @@ Treat the reads as a snapshot; re-read branch and staged set right before commit
 1. **Nothing to commit** — if there are no staged, modified, or untracked files, say so and stop.
 2. **Branch** — honor the `branch` option. With `branch:new`, cut from the base: `git fetch <remote> <base>`, then `git checkout -b <name> <remote>/<base>`, then confirm `git merge-base HEAD <remote>/<base>` is `<remote>/<base>`. If that ancestry check fails, the branch was cut from the wrong base — recreate it, never push it. If the name already exists, reuse it when it descends from the base; fork a suffix only when it has diverged, and never cut a second branch off the base for the same work.
 
-   With `branch:current`, commit on the checked-out branch — but check what it is first with the `sassy-setup` skill's `scripts/detect.sh --branch`. **Base means any `base_map` value, not just `origin/HEAD`.** Resolve the two facts before committing:
-   - `state: on-base` with `policy: new` means the caller skipped the branch decision. **Stop and report** — do not commit. A warning inside a subagent's summary has already failed to protect a shared branch once; this is a stop, not a notice.
-   - `commit-here` means the config or a token explicitly chose to commit here. Proceed, and name the branch in the summary you return.
-   - Any other state: commit on the checked-out branch.
+   With `branch:current`, commit on the checked-out branch — but check what it is first with the `sassy-setup` skill's `scripts/detect.sh --branch`, passing `--policy current` so the detector knows the caller chose this branch. **Base means any `base_map` value, not just `origin/HEAD`.** Read `action` before committing:
+   - `commit-here` — the caller's `branch:current` (or a config that says `current`) chose this branch. Commit, and name the branch in the summary you return.
+   - `reuse` — a branch that is not a base. Commit.
+   - `create` — you were told `current` but nothing chose it and this is a base: the caller skipped the branch decision. **Stop and report** — do not commit. A warning inside a subagent's summary has already failed to protect a shared branch once; this is a stop, not a notice.
+   - `stop-and-ask` or `refuse` — report the reason line and stop.
 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-setup/SKILL.md

@@ -4,22 +4,34 @@ description: >-
   Detect a project's topology and wire it for the Sassy Skills suite: write
   .sassywares/config.yaml, vendor the skills from upstream with the open
   `skills` CLI, and install the snapshot tooling in a multi-repo workspace.
-  Use when asked to set up, configure, or verify a project.
-argument-hint: "[path] [--check]"
+  Use when asked to set up or configure a project, or to check an existing
+  setup (`mode:check`).
+argument-hint: "[path] [mode:init|check]"
 disable-model-invocation: true
 ---
 
 # Sassy Setup
 
-**Outcome:** `.sassywares/config.yaml` at the project root matching the tree it describes, the skills vendored and pinned in `skills-lock.json` and visible to the harness, and — in `workspace` mode — the snapshot tooling installed.
+**Outcome:** `.sassywares/config.yaml` at the project root matching the tree it describes, the skills vendored and pinned in `skills-lock.json` and visible to the harness, the snapshot tooling installed in `workspace` mode, and every file setup wrote committed — so the project is wired and the user is good to go in one run.
 
 **Read `references/config.md` first.** It is the schema and the resolution rules; this skill only decides and writes.
 
 **Never a repo by force.** Setup records topology, it does not change it. No `git init`, ever.
 
+## Modes
+
+| Mode | What it does |
+|------|--------------|
+| `init` (default) | Detect, ask, write, wire, verify, commit, report |
+| `check` | Verify an existing setup against the tree and report |
+
+The argument names the mode: `mode:init`, `mode:check` (or `--check`, the older spelling). A run with no mode that finds a `.sassywares/config.yaml` walking up is a **check** run — a folder that is already wired is verified, never rebuilt from detection.
+
+A check run never edits the config and never rewrites the tree: it prints what `detect.sh --check` says, and its only possible write is step 8 committing setup-owned files that were already dirty. A fix is an `init` run, where each change is shown and approved first.
+
 ## 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.
+1. **Resolve the start and the mode.** The path argument, else the working directory; the mode per above. On `check`, run steps 7 → 8 → 9 and stop.
 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.
@@ -34,34 +46,47 @@ disable-model-invocation: true
 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.
 
    - **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`.
-   - **Do not wire updates.** How and when the project refreshes the suite is the project's decision, not setup's: no `skills:*` scripts, no `postinstall` edit. Mention the commands (`npx skills update`, `npx skills experimental_install`) and stop there.
-   - **Commit the vendored skills and the lock.** `.agents/skills/sassy-*` and `skills-lock.json` are the pin; a clone then needs no network.
+   - **Do not wire updates.** How and when the project refreshes the suite is the project's decision, not setup's: no `skills:*` scripts, no `postinstall` edit. Mention the commands (`npx skills update`, `npx skills experimental_install`) and stop there. Note for yourself that `npx skills check` is an alias of `update` — it is not a validator, and running it here would silently move the pin.
+   - **The pin is the commit.** `.agents/skills/sassy-*` and `skills-lock.json` are the pin, and step 8 commits them together so a clone 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 skills are invisible to the harness until it rescans.
 
 6. **Install the snapshot, `workspace` only.** Read `references/workspace.md` and follow it.
+7. **Verify.** Run `scripts/detect.sh --root <path> --check`. It validates the config against the tree — topology and remotes, `base_map` shape and cycles, `repos` against each nested repo, hooks, artifacts paths, `knowledge`, `pr.*` booleans, `commit.branch`, any unknown key, and in `workspace` mode the installed snapshot's version — plus the vendored pin: every `.agents/skills/sassy-*` folder hashed against `skills-lock.json`, the lock's coverage both ways, and whether git carries the lock. Report every `drift:` line verbatim, or that the config matches the tree. Drift blocks step 8.
+8. **Commit what setup owns.** `repo` topology only, and only when step 7 is clean. The file list is exactly what setup wrote or found unwritten:
+
+   `.sassywares/config.yaml`, `.sassywares/README.md`, `.agents/skills/sassy-*`, `skills-lock.json`, and `.gitignore` when step 5 created it. Named files only — never `git add -A`, never `git add .`.
 
-7. **Verify.** Run `scripts/detect.sh --root <path> --check`. Report every `drift:` line it prints — including an outdated `snapshot` version — or that the config matches the tree, plus that `skills-lock.json` is tracked and matches the vendored skills.
-8. **Report.** The config path, the topology, the resolved artifact and knowledge paths, that the vendored skills and lock are committed and `/reload` is needed, and in `workspace` mode what was installed. **Commit nothing.**
+   Dispatch `sassy-commit` with that list and `branch:current`. The token is explicit, not this skill's default: wiring is a one-time bootstrap commit, and cutting a branch would leave the project configured but uncommitted until someone ships it. Name the branch it landed on, base branch included.
+
+   **Nothing else** unless the user asks: a plan, a doc, a source file, or anything already dirty in the tree stays uncommitted, because setup's commit is not a place to launder work in progress. A user who says "commit my plan too" widens the list with the file they named — never with a sweep for it. On a `check` run this fires only when something setup owns is dirty: an uncommitted pin, a config edited since the last commit. Nothing dirty, nothing to commit.
+
+   - **`workspace`** — nothing to commit: the root is not a repo, and `references/workspace.md` forbids running the snapshot here. Say the root config and the pin land with the project's next snapshot.
+   - **`none`** — nothing to commit, deliberately.
+
+9. **Report.** The config path, the topology, the resolved artifact and knowledge paths, the commit (hash and branch) or why there is none, and in `workspace` mode what was installed. Remind: `/reload` so the harness rescans. Close with what is left over — at most dirt setup deliberately did not commit — and nothing else: a clean setup leaves the user good to go.
 
 ## Hard rules
 
 | Rule | Requirement |
 |------|-------------|
-| No `git init` | Setup never turns a folder into a repo, and never touches an existing repo's git state. |
+| No `git init` | Setup never turns a folder into a repo, and never does remote or ref surgery. The step 8 commit is its only git write. |
+| Commit only what setup owns | The config, the setup README, the vendored `sassy-*` folders, `skills-lock.json`, and a `.gitignore` setup created. Never a file the user wrote or the repo already had, unless they name it. |
+| Verify before commit | A config that fails `--check` is reported, never committed. |
 | Approval to create a remote | Creating the mirror repo needs an explicit yes and a named slug first. |
 | 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 come from upstream | Install with `npx skills add`; never hand-copy skill files or maintain the links yourself. |
 | Never edit the manifest | No dependencies, no scripts, no `postinstall`. Setup installs the suite; the project decides how it updates. |
-| Write boundary | Only `.sassywares/`, the vendored `.agents/skills/sassy-*`, `skills-lock.json`, and one `.gitignore` line. Never `package.json`, never a root `.gitignore` in a workspace. |
+| Write boundary | Only `.sassywares/`, the vendored `.agents/skills/sassy-*`, `skills-lock.json`, and one `.gitignore` line — and the same list is step 8's commit. Never `package.json`, 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. |
-| Repair is verify | Run against an existing config, setup reports drift — it does not rewrite the file without approval. |
+| Repair is `check` | Run against an existing config, setup reports drift — it does not rewrite the file without approval. |
 
 ## What setup is not
 
 Not a migration tool. A project already using another convention keeps its files; setup records where they already are. There is no rename step, and no fallback to `docs/` behind a configured path.
+
+Not an updater. `check` reports a pin that is stale or edited; it never moves it. Updating the suite is `npx skills update`, which is the project's decision and not setup's.

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

@@ -23,12 +23,14 @@ If a skill tells you another skill is missing, run `npx skills add sassywares/sa
 
 ## Config
 
-`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:
+`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 setup still matches the tree — the config, the hooks it names, and the vendored pin:
 
 ```bash
 .agents/skills/sassy-setup/scripts/detect.sh --root . --check
 ```
 
+Or ask for `mode:check` on the setup skill, which runs the same check and reports it. Neither moves the pin: `npx skills check` is an alias of `update`.
+
 ## Hooks
 
 `hooks.pr` names project skills that run inside the PR pipeline, keyed by the PR's **head** branch: `"*"` for every PR, an exact branch, or a family such as `release/*`, overriding per point (`before_create`, `after_create`, `before_merge`, `after_merge`). An entry is `<skill> <args…>`; the args mean whatever that skill says they mean — `mode:auto` pre-authorizes the step. Hooks are ordinary skills in `.agents/skills/`, which makes them **code**: review them like code, and never point a hook at a copy of a suite skill.

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

@@ -354,9 +354,21 @@ per-PR say-so, because one switch would merge N PRs nobody re-read.
   `concepts`), must resolve inside the project, and must not be the root itself.
 - `git.repo` is `workspace`, `none`, or one existing remote name.
 - `git.remote` is required when `git.repo: workspace`; forbidden otherwise.
-- `repos` is allowed only when `git.repo: workspace`.
+  `git.mirror_branch` and `repos` are workspace-only too.
 - `hooks` is allowed only with the four keys under `hooks.pr`, each a list of
   skill names that resolve to `.agents/skills/<name>/SKILL.md`.
 - `commit.branch` is `current` or `new`; `pr.*` are `true` or `false`. Write
   booleans as `true`/`false`, never `on`/`off` — bare `on`/`off` are YAML 1.1
   booleans and parse inconsistently.
+- `knowledge.read` is an inline list (`read: [a, b]`). A block list is not read
+  by the config reader, so it would silently scout nothing.
+- An unknown key is an error, not a fallback: a typo parses, is ignored, and the
+  run uses a default this project never chose.
+
+`scripts/detect.sh --check` enforces all of the above and reports each breach as
+a `drift:` line, exiting non-zero. It also verifies the vendored pin offline:
+every `.agents/skills/sassy-*` folder is hashed with the `skills` CLI's own
+definition and compared to `computedHash` in `skills-lock.json`, the lock is
+checked against the installed set in both directions, and git-tracked state of
+the lock is reported. A stale, hand-edited, or half-installed suite is drift
+even when the config itself matches the tree.

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

@@ -8,7 +8,8 @@
 #   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
+#   detect.sh [--root DIR] --check    compare the existing config, and the
+#                                    vendored pin, 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
@@ -242,6 +243,16 @@ nested_repos() {
 
 path_exists() { [[ -e "$ROOT/$1" ]]; }
 
+# A configured path that leaves the project is a document written somewhere the
+# project does not own, so it fails closed rather than being created.
+escapes_root() {
+  local p="${1#./}"
+  case "$p" in
+    ..|../*|*/..|*/../*|*"/../"*) return 0 ;;
+  esac
+  return 1
+}
+
 pick_artifact() {
   local candidate="$1" fallback="$2"
   if path_exists "$candidate"; then printf '%s' "$candidate"; else printf '%s' "$fallback"; fi
@@ -303,6 +314,27 @@ if (( CHECK )); then
     esac
   fi
 
+  # A typo'd key is the quietest failure in the file: it parses, it is ignored,
+  # and the run silently falls back to a default the project never chose. The
+  # whitelist is the schema in references/config.md; every key there has a
+  # validator of its own below, so anything landing here is unknown.
+  while IFS=$'\t' read -r kpath _; do
+    [[ -n "$kpath" ]] || continue
+    key="${kpath//$US/.}"
+    case "$key" in
+      artifacts.plans|artifacts.solutions|artifacts.handbooks|artifacts.concepts) ;;
+      knowledge.read|knowledge.write) ;;
+      git.repo|git.remote|git.mirror_branch) ;;
+      git.default_branch) ;;                    # has its own message below
+      git.base_map.*) ;;
+      repos.*) ;;
+      commit.branch) ;;
+      pr.babysit|pr.merge|pr.delete_branch) ;;
+      hooks.pr.*) ;;                            # shape checked with the hooks
+      *) bad "unknown key '$key' — it is ignored, so the run uses the default" ;;
+    esac
+  done < <(yaml_flat "$CONFIG")
+
   if [[ -n "$(yflat "git${US}default_branch")" ]]; then
     if [[ "$TOPOLOGY" == "workspace" ]]; then
       bad "git.default_branch is gone — the mirror's branch is git.mirror_branch"
@@ -315,6 +347,9 @@ if (( CHECK )); then
     if [[ -n "$(yflat "git${US}remote")" ]]; then
       bad "git.remote is workspace-only — a repo config names its remote in git.repo"
     fi
+    if [[ -n "$(yflat "git${US}mirror_branch")" ]]; then
+      bad "git.mirror_branch is workspace-only — a repo routes branches in git.base_map"
+    fi
     if [[ -z "$(yflat "git${US}base_map${US}*")" ]]; then
       bad "git.base_map has no \"*\" entry — it is the base for ordinary work"
     else
@@ -344,6 +379,17 @@ if (( CHECK )); then
     fi
   fi
 
+  # `repos` is the workspace inventory. In a repo config it is a dead map, and
+  # a reader would trust it over the base_map that actually applies.
+  if [[ "$configured_repo" != "workspace" ]]; then
+    while IFS= read -r rname; do
+      [[ -n "$rname" ]] || continue
+      bad "repos.$rname is workspace-only — git.repo is '${configured_repo:-unset}'"
+    done < <(yaml_flat "$CONFIG" \
+               | awk -F'\t' -v us="$US" '{n=split($1,a,us); if (n>=2 && a[1]=="repos") print a[2]}' \
+               | sort -u)
+  fi
+
   if [[ "$TOPOLOGY" == "workspace" ]]; then
     [[ -n "$MIRROR_REMOTE" ]] || bad "git.remote is required when git.repo is workspace"
     installed="$ROOT/.sassywares/workspace/snapshot"
@@ -411,6 +457,22 @@ if (( CHECK )); then
     done
   done < <(hook_patterns)
 
+  # `hooks.pr.<head>.<point>` is the only shape, and the four points are the
+  # only moments a skill asks for. A fifth point name is a step that never fires.
+  while IFS=$'\t' read -r depth hpath; do
+    [[ -n "$depth" ]] || continue
+    if [[ "$depth" != "4" ]]; then
+      bad "hooks entry '${hpath//$US/.}' is not head -> point -> list"
+      continue
+    fi
+    point="${hpath##*$US}"
+    case "$point" in
+      before_create|after_create|before_merge|after_merge) ;;
+      *) bad "hooks point '$point' is not one of before_create|after_create|before_merge|after_merge" ;;
+    esac
+  done < <(yaml_flat "$CONFIG" \
+             | awk -F'\t' -v us="$US" '{n=split($1,a,us); if (n>=2 && a[1]=="hooks") print n "\t" $1}')
+
   # Resolve for one head, so nobody has to merge maps in their head.
   if [[ -n "$HEAD_ARG" ]]; then
     if [[ "$TOPOLOGY" == "repo" ]]; then
@@ -422,9 +484,65 @@ if (( CHECK )); then
     done
   fi
 
+  # artifacts is the one block that fails closed everywhere it is read, so a
+  # bad value here is drift, not a note: a typo must not write docs outside the
+  # project. Existence is not drift — the directory is created on first write.
   for key in plans solutions handbooks concepts; do
     val="$(block_value artifacts "$key" || true)"
-    [[ -n "$val" ]] && note "  artifacts.$key: $val"
+    [[ -n "$val" ]] || continue
+    case "$val" in
+      /*|~*) bad "artifacts.$key '$val' is not relative to the config" ;;
+      .|./) bad "artifacts.$key is the project root itself" ;;
+      *)
+        if escapes_root "$val"; then
+          bad "artifacts.$key '$val' walks outside the project"
+        elif [[ "$key" == "concepts" && "$val" == */ ]]; then
+          bad "artifacts.concepts '$val' is a directory — concepts is one file"
+        elif path_exists "$val"; then
+          note "  artifacts.$key: $val (exists)"
+        else
+          note "  artifacts.$key: $val (created on first write)"
+        fi
+        ;;
+    esac
+  done
+
+  # knowledge.read fails soft at read time by design, which is exactly why a
+  # broken value has to be visible here: nothing else will ever complain.
+  while IFS= read -r kline; do
+    [[ -n "$kline" ]] || continue
+    bad "knowledge.read must be an inline list — write read: [docs/solutions, CONCEPTS.md]"
+  done < <(sed -n '/^knowledge:/,/^[a-z]/p' "$CONFIG" | grep -E '^[[:space:]]*-[[:space:]]' || true)
+  readv="$(yflat "knowledge${US}read" || true)"
+  while IFS= read -r kpath; do
+    [[ -n "$kpath" ]] || continue
+    case "$kpath" in
+      /*|~*) bad "knowledge.read '$kpath' is not a path relative to the config" ;;
+      *) if escapes_root "$kpath"; then
+           bad "knowledge.read '$kpath' walks outside the project"
+         elif ! path_exists "$kpath"; then
+           note "  knowledge.read '$kpath' does not exist — skipped, not fatal"
+         fi ;;
+    esac
+  done < <(list_items "$readv")
+  val="$(yflat "knowledge${US}write" || true)"
+  if [[ -n "$val" ]]; then
+    case "$val" in
+      true|false) note "  knowledge.write: $val" ;;
+      *) bad "knowledge.write '$val' must be true|false" ;;
+    esac
+  fi
+
+  # pr.* answers a policy question, so a value that is neither boolean is a
+  # policy nobody decided. Bare on/off are YAML 1.1 booleans and parse
+  # inconsistently across readers.
+  for key in babysit merge delete_branch; do
+    val="$(block_value pr "$key" || true)"
+    [[ -n "$val" ]] || continue
+    case "$val" in
+      true|false) note "  pr.$key: $val" ;;
+      *) bad "pr.$key '$val' must be true|false, never on/off" ;;
+    esac
   done
 
   # commit.branch steers whether a run may touch a base branch, so an invalid
@@ -437,6 +555,33 @@ if (( CHECK )); then
     esac
   fi
 
+  # The pin. A config can match the tree perfectly while the vendored suite is
+  # stale, edited, or half-installed, and every skill downstream then runs
+  # something other than what the lock says. Offline, no network.
+  if command -v node >/dev/null 2>&1; then
+    while IFS=$'\t' read -r kind msg; do
+      case "$kind" in
+        drift) bad "$msg" ;;
+        note)  note "  $msg" ;;
+      esac
+    done < <(node "$SKILL_DIR/scripts/lockcheck.mjs" --root "$ROOT" 2>/dev/null || true)
+  else
+    note "  node not found — the vendored pin is unverified (the skills CLI needs node)"
+  fi
+
+  if [[ "$TOPOLOGY" == "repo" ]]; then
+    # Tracked, not merely present: a clone has to get the pin without a network
+    # call, so an untracked lock is a setup that does not travel.
+    if [[ -n "$(git -C "$ROOT" ls-files -- skills-lock.json 2>/dev/null)" ]]; then
+      note "  skills-lock.json is tracked"
+    else
+      note "  skills-lock.json is not tracked yet — the setup commit carries it"
+    fi
+    if [[ -e "$ROOT/.claude/skills" ]] && ! git -C "$ROOT" check-ignore -q -- .claude/skills 2>/dev/null; then
+      note "  .claude/skills is not gitignored — install-time links may get committed"
+    fi
+  fi
+
   if (( drift )); then exit 1; fi
   note "  config matches the tree"
   exit 0

package/skills/sassy-setup/scripts/lockcheck.mjs

@@ -0,0 +1,129 @@
+#!/usr/bin/env node
+// Verify the vendored sassy-* folders against skills-lock.json.
+//
+// Read-only, offline. The folder hash is the `skills` CLI's own definition —
+// sha256 over each file's relative path then its bytes, files sorted by relative
+// path — so "identical to the pin" is a fact this script asserts, not a claim
+// the agent has to make in prose.
+//
+// Usage: lockcheck.mjs [--root DIR]
+// Prints "<drift|note>\t<message>" per finding and always exits 0: the caller
+// owns the verdict and the formatting.
+
+import { createHash } from "node:crypto";
+import { readdir, readFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { join, relative } from "node:path";
+
+const SUITE = "sassywares/sassy-skills";
+const SASSY = /^sassy-/;
+
+const argv = process.argv.slice(2);
+let root = process.cwd();
+for (let i = 0; i < argv.length; i += 1) {
+  if (argv[i] === "--root") {
+    root = argv[i + 1];
+    i += 1;
+  }
+}
+
+const lines = [];
+const drift = (message) => lines.push(`drift\t${message}`);
+const note = (message) => lines.push(`note\t${message}`);
+
+async function collect(base, dir, files) {
+  for (const entry of await readdir(dir, { withFileTypes: true })) {
+    const full = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      if (entry.name === ".git" || entry.name === "node_modules") continue;
+      await collect(base, full, files);
+    } else if (entry.isFile()) {
+      files.push({
+        path: relative(base, full).split("\\").join("/"),
+        body: await readFile(full),
+      });
+    }
+  }
+}
+
+async function folderHash(dir) {
+  const files = [];
+  await collect(dir, dir, files);
+  files.sort((a, b) => a.path.localeCompare(b.path));
+  const hash = createHash("sha256");
+  for (const file of files) {
+    hash.update(file.path);
+    hash.update(file.body);
+  }
+  return hash.digest("hex");
+}
+
+async function main() {
+  const lockPath = join(root, "skills-lock.json");
+  if (!existsSync(lockPath)) {
+    drift(`no skills-lock.json — the suite is not pinned; install with npx skills add ${SUITE}`);
+    return;
+  }
+
+  let lock;
+  try {
+    lock = JSON.parse(await readFile(lockPath, "utf8"));
+  } catch {
+    drift(`skills-lock.json is not valid JSON — re-install with npx skills add ${SUITE}`);
+    return;
+  }
+
+  const pinned = Object.entries(lock.skills ?? {}).filter(
+    ([name, entry]) => SASSY.test(name) || String(entry.source ?? "").includes("sassy-skills"),
+  );
+  if (pinned.length === 0) {
+    drift(`skills-lock.json pins no sassy-* skill — install with npx skills add ${SUITE}`);
+    return;
+  }
+
+  const suite = join(root, ".agents", "skills");
+  if (!existsSync(suite)) {
+    drift(`no .agents/skills — the vendored copies are missing; install with npx skills add ${SUITE}`);
+    return;
+  }
+
+  const installed = (await readdir(suite, { withFileTypes: true }))
+    .filter((entry) => entry.isDirectory() && SASSY.test(entry.name))
+    .map((entry) => entry.name);
+  const installedNames = new Set(installed);
+  const pinnedNames = new Set(pinned.map(([name]) => name));
+  let matched = 0;
+
+  for (const [name, entry] of pinned) {
+    if (!installedNames.has(name)) {
+      drift(`vendored ${name} is missing from .agents/skills — re-install with npx skills add ${SUITE}`);
+      continue;
+    }
+    if ((await folderHash(join(suite, name))) !== entry.computedHash) {
+      drift(`${name} does not match the pin — edited locally or half-installed; re-install, or re-pin with npx skills add ${SUITE}`);
+      continue;
+    }
+    matched += 1;
+  }
+
+  for (const name of installed) {
+    if (!pinnedNames.has(name)) {
+      drift(`${name} is installed but not pinned in skills-lock.json — npx skills add ${SUITE} pins it`);
+    }
+  }
+
+  if (matched > 0) {
+    note(`${matched}/${pinned.length} sassy-* skill folders match skills-lock.json byte for byte`);
+  }
+
+  const sources = [...new Set(pinned.map(([, entry]) => String(entry.source ?? "unknown")))];
+  if (sources.length === 1 && sources[0] !== SUITE) {
+    note(`pinned from ${sources[0]}, not ${SUITE}`);
+  }
+}
+
+main()
+  .catch((error) => drift(`could not verify the pin: ${error.message}`))
+  .finally(() => {
+    if (lines.length > 0) process.stdout.write(`${lines.join("\n")}\n`);
+  });