feat(install): serve several sources instead of displacing them

~/.agents/skills was a single link straight at this checkout. That encoded an assumption nobody had stated — that this checkout is the only source of skills on the host. On flamingo it was not: Crush's directory held Anthropic's official set, and the only way to install this library was to move that set aside. A capability loss dressed up as a tidy-up. The canonical location becomes a real directory of per-skill symlinks, fed by the checkout plus anything in SKILLS_EXTRA_SOURCES. Harnesses keep their one directory link, so the count is N + one per harness rather than N x harnesses, which is what #23 was actually about. The three requirements #27 named, each with a test: - collisions are logged with both paths and the checkout wins, never resolved in silence; - removing a skill from a source prunes its link; - anything in the managed directory that is not our symlink is reported and left in place — the installer does not delete content it did not create. doctor learns the same model: sources are recorded at ~/.agents/skills-sources, a link into a configured source is healthy, a link into an unknown one is not, and the old count check becomes a per-skill check because a per-skill layout can lose one skill without changing any total. The pre-#27 wiring is named as legacy rather than reported as damage. count_skills needed find -L; without it symlinked skill directories count as zero. Verified live on koala: migrated in place to 42 per-skill links, then a second source added a 43rd alongside them, then a re-run without that source pruned it back to 42. Only doctor finding throughout was the genuine stale plugin. Closes #27 Bump-Type: minor
chore(release): plugin.json version 0.9.0
2026-08-29 10:05:46 +02:00 · 2026-08-29 08:01:01 +00:00 · 2026-08-29 10:00:11 +02:00 · 2026-08-29 07:56:02 +00:00 · 2026-08-29 09:55:53 +02:00 · 2026-08-29 07:54:53 +00:00
19 changed files with 1141 additions and 805 deletions
@@ -1,7 +1,7 @@
 {
  "name": "skills",
  "description": "Mathias's engineering skills library, plus the hooks and MCP servers that make it enforceable: TDD, clean code, debugging, specs, discovery, CI, and secret hygiene.",
-  "version": "0.6.1",
+  "version": "0.9.0",
  "author": {
    "name": "Mathias",
    "url": "https://git.d-ma.be/mathias"
@@ -1,23 +1,52 @@
-name: release
+name: CI
-# Auto-tag every push to main with a semver bump derived from the latest
+# Two jobs, in order:
 #
 #   gate — `task check` (structure, frontmatter, manifest/tag parity) plus
 #          `task test` (hooks, doctor, release-skip). Runs on every push and
 #          every PR. Before this existed the suite ran nowhere: CI reported
 #          green having tested nothing (#22).
 #
 #   tag  — auto-tags a push to main with a semver bump derived from the latest
 #          commit footer:
 #            Bump-Type: major  → vX.0.0
 #            Bump-Type: minor  → v0.Y.0
 #            (default)         → v0.0.Z (patch)
-#
+#          Skips when the commit carries the `Skip-Release: true` trailer (the
-# Skips when the latest commit is itself the auto-tagger (commit message
+#          tagger's own manifest bump) to prevent recursion. Gated on `gate`,
-# contains "[skip-release]") to prevent recursion. Tag is pushed back
+#          so a red check cannot ship a tag.
 # to the repo using the GITEA_TOKEN provided by act_runner.
-on:
+"on":
  push:
-    branches:
+    branches: ["**"]
-      - main
+  pull_request:
    branches: [main]
 jobs:
-  tag:
+  gate:
    name: Check / Test
    runs-on: self-hosted
    steps:
      - uses: actions/checkout@v4
        with:
          # `task check` compares plugin.json's version to `git describe`;
          # a shallow checkout has no tags and would skip that assertion.
          fetch-depth: 0
      - name: Verify toolchain
        run: task --version
      - name: Structure gate
        run: task check
      - name: Shell test suite
        run: task test
  tag:
    name: Tag release
    needs: gate
    runs-on: self-hosted
    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
    steps:
      - name: checkout
        uses: actions/checkout@v4
@@ -72,16 +101,19 @@ jobs:
          manifest=.claude-plugin/plugin.json
          version="${TAG#v}"
          current=$(sed -n 's/.*"version"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' "$manifest" | head -1)
          git tag -a "$TAG" -m "release $TAG"
          if [ "$current" != "$version" ]; then
            sed -i "s/\"version\"[[:space:]]*:[[:space:]]*\"$current\"/\"version\": \"$version\"/" "$manifest"
            git add "$manifest"
            # The trailer below stops this push from re-triggering the tagger.
            git commit -m "chore(release): plugin.json version $version" -m "Skip-Release: true"
-            git push origin HEAD:main
+            # Commit and tag go up in ONE push: the gate job runs `task check`
            # on the bump commit, and that asserts manifest == latest tag. Two
            # separate pushes leave a window where it legitimately fails.
            git push origin HEAD:main "$TAG"
            echo "bumped $manifest to $version"
-          fi
+          else
          git tag -a "$TAG" -m "release $TAG"
          # gitea-actions checkout uses an x-access-token URL; reuse it.
            git push origin "$TAG"
          fi
          echo "pushed $TAG"
@@ -40,16 +40,42 @@ moves — CI bumps it on every release.
 curl -fsSL https://git.d-ma.be/mathias/skills/raw/branch/main/install.sh | bash
 ```
-Idempotent. It clones or fast-forwards the checkout, then creates **three**
+Idempotent. It clones or fast-forwards the checkout, then populates one
-symlinks — one directory link per harness, never one per skill:
+**managed directory** and gives each harness a single link to it:
-| Link | Target |
+| Path | Target |
 |---|---|
-| `~/.agents/skills` | `$SKILLS_CHECKOUT_DIR/skills` (Pi reads this path directly) |
+| `~/.agents/skills/` | a real directory, one symlink per skill (Pi reads this path directly) |
 | `~/.agents/skills/<skill>` | `$SKILLS_CHECKOUT_DIR/skills/<skill>`, or another configured source |
 | `~/.config/crush/skills` | `~/.agents/skills` |
 | `~/.config/opencode/skills` | `~/.agents/skills` |
-Adding a skill wires it everywhere with no re-run.
+Total links are N + one per harness — not N x harnesses, which is what #23 was
 actually about.
 ### More than one source of skills
 `~/.agents/skills` used to be a single link straight at this checkout. That
 encoded an assumption nobody had stated — that this checkout is the only source
 of skills on the host — and on flamingo the only way to install this library
 was to displace Anthropic's official set, which lived in Crush's directory.
 Real capability loss dressed up as a tidy-up (#27).
 Point `SKILLS_EXTRA_SOURCES` at any number of extra directories, colon
 separated, each holding `<skill>/SKILL.md`:
 ```
 SKILLS_EXTRA_SOURCES=~/.config/crush/skills.anthropic bash install.sh
 ```
 - The checkout is always first and always wins a name collision — but the
  collision is **logged**, never resolved in silence. Quietly picking one is
  how stale content wins.
 - Removing a skill from a source removes its link on the next run.
 - Anything in the managed directory that is not a symlink is reported and left
  alone. install.sh does not delete content it did not create.
 - The source list is recorded at `~/.agents/skills-sources` so `bin/doctor`
  can tell a link into a known source from a link into a forgotten one.
 ### Where the checkout must live
@@ -74,6 +100,7 @@ default to point into `~/dev`.
 | `AGENTS_SKILLS_DIR` | `$HOME/.agents/skills` |
 | `CRUSH_SKILLS_DIR` | `$HOME/.config/crush/skills` |
 | `OPENCODE_SKILLS_DIR` | `$HOME/.config/opencode/skills` |
 | `SKILLS_EXTRA_SOURCES` | unset (colon-separated extra source directories) |
 Antigravity and Mistral Vibe targets were removed — unused.
@@ -19,9 +19,11 @@ This index lists all available engineering skills. Load the full SKILL.md on dem
 | `gitea-ci` | Gitea CI/CD pipeline with act_runner, buildah, k3s, GitHub mirror | Setting up or debugging CI on this infra |
 | `debug` | Hypothesis-first debugging discipline | Any test failure or bug whose cause is not immediately obvious |
 | `feature-spec` | Implementation-level feature spec (tighter than spec-driven-dev) | Scoping one feature inside an already-specced project |
 | `experiment-spec` | Rigorous experiment spec — falsifiable hypothesis, quantitative acceptance, null-result protocol | Scoping a research/ML phase instead of a feature |
 | `playwright` | Playwright E2E testing — setup, HTMX patterns, SSE streams, CI wiring | Adding browser tests to any project with a web UI |
 | `session-retrospective` | Surface non-obvious learnings from a session log | After a coding session ends, before context is lost |
 | `trainer` | Two-phase brain curation (score candidates, write past quality gate) | Periodic brain pruning and curation |
 | `dream` | Reflective consolidation pass over an agent's memory directory | Pruning/merging memory files, rebuilding a memory index |
 | `grill-me` | Structured plan interrogation — Quick Poke, Full Grill, Pre-mortem | Stress-testing a plan before committing; end of Diamond 1; before promoting to pre-prod |
 | `own-the-task` | Delegation ownership — Intake → Brief → Plan → Execute | A task is handed over open-ended; "take this off my plate"; before a plan exists |
 | `telos-load` | Load TELOS intention substrate at session start | Starting any koala session; before architectural decisions; CAD pipeline entry |
@@ -30,13 +32,13 @@ This index lists all available engineering skills. Load the full SKILL.md on dem
 | `discovery-framing` | Problem-before-solution discovery/framing method | Framing/validating a problem before any solution; opportunity sizing |
 | `stage-gate-review` | Stage-gate product governance (go/no-go council) | Preparing a Product Council ask; building a go/no-go checklist; gate review |
 | `web-shot` | Screenshot a running web UI via a koala k3s Playwright job | Visual verification of a running UI when no local browser exists |
 | `cad-babysit` | Focused human-in-the-loop session working CAD's stuck queue (read-only) | Picking up whatever `cad stuck` flags, with a human present |
 | `superpowers-brainstorming` | Structured divergent brainstorming | Generating or expanding a set of ideas |
 | `superpowers-writing-plans` | Writing implementation plans | Planning substantial work before coding |
 | `superpowers-executing-plans` | Executing a written plan step by step | Running an approved plan to completion |
 | `superpowers-dispatching-parallel-agents` | Fan work out across parallel subagents | Decomposing work for concurrent agents |
 | `superpowers-subagent-driven-development` | Subagent-driven development workflow | Building via orchestrated subagents |
 | `superpowers-systematic-debugging` | Hypothesis-first systematic debugging | Diagnosing a failure methodically |
 | `superpowers-test-driven-development` | TDD discipline (superpowers variant) | Red → green → refactor on a change |
 | `superpowers-verification-before-completion` | Verify behavior before claiming done | Before marking any task complete |
 | `superpowers-requesting-code-review` | Requesting a code review well | Asking another agent/human to review |
 | `superpowers-receiving-code-review` | Acting on received review feedback | Responding to review comments |
@@ -68,17 +70,21 @@ everything load twice.
 ### Crush, Pi, OpenCode — run `install.sh`
-These have no plugin system, so they get symlinks — but **one directory link
+These have no plugin system, so they get symlinks — but through one managed
-each**, never one per skill:
+directory, never one link per skill per harness:
 ```
-~/.agents/skills           -> $SKILLS_CHECKOUT_DIR/skills   (Pi reads this directly)
+~/.agents/skills/          (real directory; Pi reads it directly)
 ~/.agents/skills/tdd       -> $SKILLS_CHECKOUT_DIR/skills/tdd
 ~/.agents/skills/xlsx      -> $SKILLS_EXTRA_SOURCES entry
 ~/.config/crush/skills     -> ~/.agents/skills
 ~/.config/opencode/skills  -> ~/.agents/skills
 ```
-Adding a skill therefore wires it everywhere with no re-run, and a broken link
+Total links are N + one per harness. `SKILLS_EXTRA_SOURCES` (colon-separated
-is one broken link instead of 42.
+directories) lets a second library — Anthropic's official set, for instance —
 live alongside this one instead of being displaced by it; name collisions are
 logged rather than silently resolved, and the checkout wins (#27).
 ```
 curl -fsSL https://git.d-ma.be/mathias/skills/raw/branch/main/install.sh | bash
@@ -92,10 +98,11 @@ absolute link stored there is broken on one side by construction. See #23.
 ### Check a host
-`task doctor` (or `bin/doctor`) reports dangling links, links resolving into a
+`task doctor` (or `bin/doctor`) reports dangling links, links into a source
-foreign checkout, count mismatches, stray entries, and leftover Claude
+nobody configured, skills in the checkout with no link, stray entries, leftover
-symlinks. It also runs automatically at session start via the plugin, so drift
+Claude symlinks, and a Claude Code plugin sitting on an older generation than
-announces itself instead of waiting to be found.
+the host already has. It also runs automatically at session start via the
 plugin, so drift announces itself instead of waiting to be found.
 ## Skill Relationships
@@ -106,14 +113,16 @@ problem-analysis
            │
            ├── spec-driven-dev (PM-kickoff lifecycle)
            │       │
-            │       └── feature-spec (per-feature, mid-implementation)
+            │       ├── feature-spec (per-feature, mid-implementation)
            │       │       │
            │       │       └── planning
            │       │               │
            │       │               └── atdd ──→ tdd (foundation)
            │       │                        ├──→ debug (when tests fail)
            │       │                        ├──→ clean-code (REFACTOR phase)
            │       │                        └──→ test-design (review)
            │       │
-            │               └── planning
+            │       └── experiment-spec (research/ML phase, instead of feature-spec)
            │                       │
            │                       └── atdd ──→ tdd (foundation)
            │                                ├──→ debug (when tests fail)
            │                                ├──→ clean-code (REFACTOR phase)
            │                                └──→ test-design (review)
            │
            └── planning
@@ -94,7 +94,12 @@ tasks:
          count=$((count + 1))
        done
-        # 3. Plugin manifest version must match the latest tag, or installers
+        # 3. SKILLS_INDEX.md lists exactly the skills that exist. Delegated
        #    to bin/check-index so the rule is covered by
        #    tests/check_index_test.sh rather than living untested here.
        sh '{{.TASKFILE_DIR}}/bin/check-index' '{{.TASKFILE_DIR}}' || fail=1
        # 4. Plugin manifest version must match the latest tag, or installers
        #    never see the update (Claude Code gates updates on this field).
        if [ -f '{{.PLUGIN_MANIFEST}}' ]; then
          manifest_v=$(sed -n 's/.*"version"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' '{{.PLUGIN_MANIFEST}}' | head -1)
@@ -0,0 +1,42 @@
 #!/bin/sh
 # check-index — asserts SKILLS_INDEX.md lists exactly the skills that exist.
 #
 # The index is hand-maintained and drifts silently in both directions: a skill
 # ships with no row (`dream` and `experiment-spec` did — their rows lived on
 # branches squash-merged after a directory reorg, so the SKILL.md landed and
 # the row did not, #15), or a row outlives the skill it names. Neither errors
 # anywhere; the library just misreports itself to every harness that reads it.
 #
 # Usage: check-index [checkout-root]   (defaults to this script's repo root)
 set -u
 ROOT=${1:-$(CDPATH= cd -- "$(dirname -- "$0")/.." && pwd)}
 INDEX="$ROOT/SKILLS_INDEX.md"
 fail=0
 if [ ! -f "$INDEX" ]; then
  echo "ERROR: missing SKILLS_INDEX.md" >&2
  exit 1
 fi
 # A row is a table line whose first cell is the skill name in backticks.
 listed=$(sed -n 's/^|[[:space:]]*`\([^`]*\)`.*/\1/p' "$INDEX" | sort -u)
 for dir in "$ROOT"/skills/*/; do
  name=$(basename "$dir")
  [ -f "$dir/SKILL.md" ] || continue
  printf '%s\n' "$listed" | grep -qx "$name" || {
    echo "ERROR: skills/$name has no row in SKILLS_INDEX.md" >&2
    fail=1
  }
 done
 for name in $listed; do
  [ -f "$ROOT/skills/$name/SKILL.md" ] || {
    echo "ERROR: SKILLS_INDEX.md lists '$name', which has no skills/$name/SKILL.md" >&2
    fail=1
  }
 done
 exit $fail
@@ -39,12 +39,21 @@ SELF_CHECKOUT=$(CDPATH= cd -- "$SELF_DIR/.." && pwd)
 # copy doctor happens to be running from. When invoked as a plugin hook, $0
 # lives in the plugin cache, which is legitimately a second copy: judging the
 # harness links against it would flag every one of them as "outside".
 AGENTS_DIR="$HOME/.agents/skills"
 SOURCES_FILE="$(dirname -- "$AGENTS_DIR")/$(basename -- "$AGENTS_DIR")-sources"
 if [ -n "${DOCTOR_CHECKOUT:-}" ]; then
  CHECKOUT="$DOCTOR_CHECKOUT"
-elif [ -d "$HOME/.agents/skills" ]; then
+elif [ -f "$SOURCES_FILE" ]; then
-  # Resolve the link FIRST, then take the parent. "cd X/.." resolves ".."
+  # Since #27 the canonical location is a real directory fed by several
-  # lexically against the link path, which lands back in ~/.agents.
+  # sources, so it can no longer be resolved to a checkout. install.sh records
-  _resolved=$(CDPATH= cd -- "$HOME/.agents/skills" 2>/dev/null && pwd -P)
+  # the list; the first line is always this repo's skills/ directory.
  CHECKOUT=$(dirname -- "$(head -n 1 "$SOURCES_FILE")")
 elif [ -L "$AGENTS_DIR" ]; then
  # Pre-#27 wiring: one link straight at the checkout. Resolve the link FIRST,
  # then take the parent. "cd X/.." resolves ".." lexically against the link
  # path, which lands back in ~/.agents.
  _resolved=$(CDPATH= cd -- "$AGENTS_DIR" 2>/dev/null && pwd -P)
  CHECKOUT=$(dirname -- "$_resolved")
 else
  CHECKOUT="$SELF_CHECKOUT"
@@ -66,9 +75,26 @@ add() {
 }
 # count_skills <dir> — directories containing a SKILL.md, one level down.
 # -L on purpose: since #27 the entries are per-skill symlinks, and find does
 # not descend into a symlinked directory without it.
 count_skills() {
  [ -d "$1" ] || { printf '0'; return; }
-  find "$1"/ -mindepth 2 -maxdepth 2 -name SKILL.md 2>/dev/null | wc -l | tr -d ' '
+  find -L "$1"/ -mindepth 2 -maxdepth 2 -name SKILL.md 2>/dev/null | wc -l | tr -d ' '
 }
 # under_known_source <physical-path> — 0 when the path lies inside a source
 # install.sh recorded, or inside the active checkout.
 under_known_source() {
  _path=$1
  _list="$SKILLS_DIR"
  [ -f "$SOURCES_FILE" ] && _list="$_list
 $(cat "$SOURCES_FILE")"
  printf '%s\n' "$_list" | while IFS= read -r _src; do
    [ -n "$_src" ] || continue
    _real=$(CDPATH= cd -- "$_src" 2>/dev/null && pwd -P) || continue
    [ -n "$_real" ] || continue
    case "$_path" in "$_real"/*|"$_real") printf 'yes'; break ;; esac
  done | grep -q yes
 }
 # --- the checkout itself ----------------------------------------------------
@@ -95,10 +121,47 @@ for entry in "$SKILLS_DIR"/*; do
  fi
 done
 # --- the canonical directory --------------------------------------------------
 # Pre-#27 this was a symlink at the checkout. It is a real directory now, one
 # per-skill link per skill, fed by every configured source — that is what lets
 # a second library (Anthropic's official set on flamingo) coexist instead of
 # being displaced.
 if [ -L "$AGENTS_DIR" ]; then
  add WARN legacy "$AGENTS_DIR is the pre-#27 single-link wiring — re-run install.sh to adopt the multi-source layout"
 elif [ -d "$AGENTS_DIR" ]; then
  for entry in "$AGENTS_DIR"/*; do
    [ -e "$entry" ] || [ -L "$entry" ] || continue
    name=$(basename "$entry")
    if [ ! -L "$entry" ]; then
      add FAIL unmanaged "$AGENTS_DIR/$name is not a link into any source — nothing manages it and nothing updates it"
      continue
    fi
    if [ ! -e "$entry" ]; then
      add FAIL dangling "$entry -> $(readlink "$entry") (target does not exist)"
      continue
    fi
    resolved=$(CDPATH= cd -- "$entry" 2>/dev/null && pwd -P)
    if [ -n "$resolved" ] && ! under_known_source "$resolved"; then
      add FAIL outside "$entry resolves to $resolved, an unknown source — it works, so nothing complains, while serving content nobody updates"
    fi
  done
  # A per-skill layout can lose one skill without changing any total, so the
  # invariant is per skill, not a count.
  for dir in "$SKILLS_DIR"/*/; do
    [ -f "$dir/SKILL.md" ] || continue
    name=$(basename "$dir")
    [ -L "$AGENTS_DIR/$name" ] \
      || add FAIL missing "$name is in the checkout but has no link in $AGENTS_DIR — re-run install.sh"
  done
 fi
 # --- harness wiring ---------------------------------------------------------
-# Canonical location first; Pi reads it directly and the others link to it.
+# Crush and OpenCode keep their single directory link at the canonical dir;
 # Pi reads it directly and needs no link of its own.
 for dir in \
  "$HOME/.agents/skills" \
  "$HOME/.config/crush/skills" \
  "$HOME/.config/opencode/skills"
 do
@@ -109,24 +172,24 @@ do
    continue
  fi
-  # Resolve to a physical path and confirm it lands inside THIS checkout.
+  # A real directory where a link belongs holds content nothing manages: it
-  # A link that resolves to a different checkout is the dangerous case: it
+  # cannot receive new skills and silently shadows the canonical dir. Since
-  # works, so nothing complains, while serving stale content.
+  # #27 the fix is not only "move it aside" — it can be added as an extra
-  resolved=$(CDPATH= cd -- "$dir" 2>/dev/null && pwd -P)
+  # source instead, which is how flamingo keeps the official Anthropic set.
-  canonical=$(CDPATH= cd -- "$SKILLS_DIR" 2>/dev/null && pwd -P)
+  if [ ! -L "$dir" ] && [ -d "$dir" ]; then
-  if [ -n "$resolved" ] && [ "$resolved" != "$canonical" ]; then
+    add FAIL unmanaged "$dir is a real directory, not a link into the canonical dir — it holds $(count_skills "$dir") unmanaged skill(s); add it to SKILLS_EXTRA_SOURCES and re-run install.sh, or move it aside"
    add FAIL outside "$dir resolves to $resolved, outside the active checkout $canonical"
    continue
  fi
-  got=$(count_skills "$dir")
+  resolved=$(CDPATH= cd -- "$dir" 2>/dev/null && pwd -P)
-  if [ "$got" != "$EXPECTED" ]; then
+  canonical=$(CDPATH= cd -- "$AGENTS_DIR" 2>/dev/null && pwd -P)
-    add FAIL count "$dir sees $got skills, checkout has $EXPECTED"
+  if [ -n "$resolved" ] && [ -n "$canonical" ] && [ "$resolved" != "$canonical" ]; then
    add FAIL outside "$dir resolves to $resolved, not the canonical $canonical"
  fi
 done
 # --- dangling links anywhere under the harness dirs -------------------------
-for dir in "$HOME/.agents/skills" "$HOME/.config/crush/skills" \
+for dir in "$HOME/.config/crush/skills" \
           "$HOME/.config/opencode/skills" "$HOME/.claude/skills"
 do
  [ -d "$dir" ] || continue
@@ -171,10 +234,63 @@ if [ -f "$INSTALLED" ]; then
    || add WARN plugin "skills@mathias is not installed for Claude Code — /plugin marketplace add https://git.d-ma.be/mathias/skills.git"
 fi
 # --- Claude Code: which GENERATION of the plugin is installed ---------------
 # Every check above is about symlink paths, which is the wrong shape for the
 # plugin: it is the only channel Claude Code has, and Claude Code gates updates
 # on plugin.json's version. A host that never picked up a release loads all the
 # skills successfully and is simply a generation behind — silently. Found on
 # koala 2026-08-29: installed 0.6.0, marketplace clone 0.7.0, repo 0.8.5,
 # doctor said "clean" (#30).
 #
 # Offline by construction, like the rest of doctor: "available" means the
 # newest manifest already on this host — the active checkout and any
 # marketplace clone — never a fetch.
 manifest_version() {
  [ -f "$1" ] || return 1
  grep -q '"name"[[:space:]]*:[[:space:]]*"skills"' "$1" || return 1
  sed -n 's/.*"version"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' "$1" | head -1
 }
 # newer_version a b — echoes whichever sorts higher on major.minor.patch.
 newer_version() {
  printf '%s\n%s\n' "$1" "$2" | awk -F. '
    { raw[NR] = $0; for (i = 1; i <= 3; i++) n[NR, i] = ($i == "" ? 0 : $i + 0) }
    END {
      for (i = 1; i <= 3; i++) {
        if (n[1, i] > n[2, i]) { print raw[1]; exit }
        if (n[1, i] < n[2, i]) { print raw[2]; exit }
      }
      print raw[1]
    }'
 }
 installed_v=''
 if [ -f "$INSTALLED" ]; then
  installed_v=$(sed -n '/"skills@mathias"/,/\]/p' "$INSTALLED" \
    | sed -n 's/.*"version"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' | head -1)
 fi
 available_v=''
 for manifest in "$CHECKOUT/.claude-plugin/plugin.json" \
                "$HOME"/.claude/plugins/marketplaces/*/.claude-plugin/plugin.json
 do
  v=$(manifest_version "$manifest") || continue
  [ -n "$v" ] || continue
  if [ -z "$available_v" ]; then
    available_v=$v
  else
    available_v=$(newer_version "$available_v" "$v")
  fi
 done
 if [ -n "$installed_v" ] && [ -n "$available_v" ] && [ "$installed_v" != "$available_v" ]; then
  add FAIL plugin-version "Claude Code has skills@mathias $installed_v installed but $available_v is available on this host — /plugin update skills@mathias (a host stale enough to matter is running the old doctor, so the first detection may need this run by hand)"
 fi
 # --- output -----------------------------------------------------------------
 if [ "$JSON" -eq 1 ]; then
-  printf '{"checkout":"%s","expected":%s,"findings":[%s]}\n' \
+  printf '{"checkout":"%s","expected":%s,"plugin":{"installed":"%s","available":"%s"},"findings":[%s]}\n' \
-    "$CHECKOUT" "$EXPECTED" "${report%,}"
+    "$CHECKOUT" "$EXPECTED" "$installed_v" "$available_v" "${report%,}"
 elif [ "$findings" -gt 0 ]; then
  printf 'skills doctor — %s finding(s), checkout %s\n\n%s\n' \
    "$findings" "$CHECKOUT" "$report"
@@ -50,11 +50,18 @@ if printf '%s' "$CMD" | grep -Eqi '(^|[;&|]|\s)op\s+document\s+get\b'; then
 fi
 # Raw env/secret-file dumps (infra#228/#229 root cause).
-if printf '%s' "$CMD" | grep -Eqi '(^|[;&|]|\s)env(\s|$).*\|.*grep'; then
+#
-  deny "Blocked: 'env | grep' prints matching values in full. Use an existence-only check: [ -n \"\$VAR\" ] && echo set"
+# `env` is a dump only when nothing but options and VAR=value assignments
-fi
+# follow it. `env -u VAR cmd` and `env FOO=bar cmd` EXEC a command with a
-if printf '%s' "$CMD" | grep -Eq '(^|[;&|])[[:space:]]*env[[:space:]]*($|[;&|])'; then
+# modified environment and print nothing themselves — piping those into grep
-  deny "Blocked: bare 'env' prints every variable's value, including secrets. Use an existence-only check: [ -n \"\$VAR\" ] && echo set"
+# filters the command's own output, not the environment (#25). The earlier
 # pattern matched any `env` token followed anywhere later by a pipe into
 # grep, which blocked the documented 1Password write path
 # (`env -u OP_SERVICE_ACCOUNT_TOKEN op item create`) and cost a workaround.
 # Denying only the "no command word follows" shape also catches `env FOO=bar`
 # with no command, which the two previous rules let through.
 if printf '%s' "$CMD" | grep -Eqi '(^|[;&|]|[[:space:]])env([[:space:]]+-[iu][[:space:]]*[A-Za-z_][A-Za-z0-9_]*|[[:space:]]+-[iu]|[[:space:]]+[A-Za-z_][A-Za-z0-9_]*=[^[:space:]]*)*[[:space:]]*($|[|;&])'; then
  deny "Blocked: this 'env' prints every variable's value, including secrets (no command word follows it, so it dumps rather than execs). Use an existence-only check: [ -n \"\$VAR\" ] && echo set. Note 'env -u VAR cmd' and 'env FOO=bar cmd' are allowed — they run a command."
 fi
 if printf '%s' "$CMD" | grep -Eqi '(^|[;&|]|\s)printenv\b'; then
  deny "Blocked: printenv dumps all env values. Use: [ -n \"\$VAR\" ] && echo set"
@@ -20,14 +20,24 @@
 # cannot. This script covers the harnesses with no plugin system: Crush, Pi
 # and OpenCode.
 #
-# Wiring model — one directory link per harness, never one per skill:
+# Wiring model — one managed directory, one link per harness:
 #
-#   ~/.agents/skills            -> $CHECKOUT_DIR/skills   (canonical; Pi reads it directly)
+#   ~/.agents/skills/tdd        -> $CHECKOUT_DIR/skills/tdd   (canonical; Pi reads the dir directly)
 #   ~/.agents/skills/xlsx       -> $OTHER_SOURCE/xlsx
 #   ~/.config/crush/skills      -> ~/.agents/skills
 #   ~/.config/opencode/skills   -> ~/.agents/skills
 #
-# Adding a skill to the repo therefore wires it everywhere with no re-run,
+# ~/.agents/skills was itself a link to this checkout until #27. That encoded
-# and a broken link is one broken link rather than 42.
+# an assumption nobody had stated — that this checkout is the ONLY source of
 # skills on the host — and on flamingo the only way to install this library
 # was to displace Anthropic's official set, which lived in Crush's directory.
 # A real directory of per-skill links serves several sources at once: total
 # links are N + one per harness, still not N x harnesses (#23's actual point).
 #
 # Extra sources come from SKILLS_EXTRA_SOURCES, a colon-separated list of
 # directories each holding <skill>/SKILL.md. The checkout is always first and
 # always wins a name collision — but the collision is logged, never resolved
 # in silence, because quietly picking one is how stale content wins.
 #
 # CHECKOUT_DIR deliberately defaults OUTSIDE any file-synced or
 # cross-platform-shared directory. Do not "fix" it to point into ~/dev: on a
@@ -43,6 +53,10 @@ CHECKOUT_DIR="${SKILLS_CHECKOUT_DIR:-$HOME/.local/share/skills}"
 AGENTS_DIR="${AGENTS_SKILLS_DIR:-$HOME/.agents/skills}"
 CRUSH_DIR="${CRUSH_SKILLS_DIR:-$HOME/.config/crush/skills}"
 OPENCODE_DIR="${OPENCODE_SKILLS_DIR:-$HOME/.config/opencode/skills}"
 EXTRA_SOURCES="${SKILLS_EXTRA_SOURCES:-}"
 # Recorded beside the managed directory rather than inside it: a stray file in
 # there would look like a skill to every harness reading the dir.
 SOURCES_MANIFEST="$(dirname "$AGENTS_DIR")/$(basename "$AGENTS_DIR")-sources"
 log() { printf '[skills] %s\n' "$*"; }
@@ -74,6 +88,95 @@ count_skills() {
  find "$CHECKOUT_DIR/skills" -mindepth 2 -maxdepth 2 -name SKILL.md 2>/dev/null | wc -l | tr -d ' '
 }
 # sources — every configured source directory, primary first, one per line.
 sources() {
  printf '%s\n' "$CHECKOUT_DIR/skills"
  [ -n "$EXTRA_SOURCES" ] || return 0
  # printf '%s\n' deliberately: without the trailing newline `read` hits EOF
  # on the final entry and the loop body never runs for it.
  printf '%s\n' "$EXTRA_SOURCES" | tr ':' '\n' | while IFS= read -r src; do
    [ -n "$src" ] || continue
    if [ -d "$src" ]; then
      printf '%s\n' "$src"
    else
      log "extra source $src does not exist — skipping"
    fi
  done
 }
 # prepare_agents_dir — the canonical location is a real directory now. A host
 # still on the single-link wiring is migrated in place.
 prepare_agents_dir() {
  if [ -L "$AGENTS_DIR" ]; then
    log "migrating $AGENTS_DIR from the single-link wiring to a per-skill directory"
    rm -f "$AGENTS_DIR"
  elif [ -e "$AGENTS_DIR" ] && [ ! -d "$AGENTS_DIR" ]; then
    log "REFUSING to replace $AGENTS_DIR — it exists and is not a directory"
    return 1
  fi
  mkdir -p "$AGENTS_DIR"
 }
 # wire_skills — one symlink per skill, from every configured source.
 wire_skills() {
  local src_list desired name src dir link target
  src_list="$(mktemp)"
  sources > "$src_list"
  desired=""
  while IFS= read -r src; do
    [ -d "$src" ] || continue
    for dir in "$src"/*/; do
      [ -f "$dir/SKILL.md" ] || continue
      name="$(basename "$dir")"
      target="${dir%/}"
      if printf '%s' "$desired" | grep -qx -- "$name"; then
        log "COLLISION: $name is offered by $target too; keeping $AGENTS_DIR/$name -> $(readlink "$AGENTS_DIR/$name" 2>/dev/null || echo '?')"
        continue
      fi
      link="$AGENTS_DIR/$name"
      if [ -L "$link" ]; then
        if [ "$(readlink "$link")" = "$target" ]; then
          desired="$desired$name
 "
          continue
        fi
        rm -f "$link"
      elif [ -e "$link" ]; then
        log "unmanaged: $link is not a symlink — left in place; move it aside to let $target take the name"
        continue
      fi
      ln -s "$target" "$link"
      desired="$desired$name
 "
    done
  done < "$src_list"
  rm -f "$src_list"
  # Removing a skill from a source must remove its link, or the previous
  # generation's problem (links resolving to nothing, invisible to git)
  # returns in a new shape.
  for link in "$AGENTS_DIR"/*; do
    [ -e "$link" ] || [ -L "$link" ] || continue
    name="$(basename "$link")"
    if [ ! -L "$link" ]; then
      log "unmanaged: $link is not a symlink and no source offers it — left in place"
      continue
    fi
    printf '%s' "$desired" | grep -qx -- "$name" && continue
    rm -f "$link"
    log "pruned $name — no configured source offers it any more"
  done
  sources > "$SOURCES_MANIFEST"
  # Reported through a global, not stdout: wire_skills logs collisions and
  # unmanaged entries as it goes, and capturing its stdout for a count would
  # swallow exactly the warnings this change exists to surface.
  LINKED_COUNT=$(printf '%s' "$desired" | grep -c . || true)
 }
 # link_dir <link_path> <target_path>
 # Replaces whatever is there — including a directory left behind by the old
 # per-skill wiring — with a single symlink.
@@ -104,12 +207,14 @@ main() {
  # Canonical location. Pi reads ~/.agents/skills directly, so it needs no
  # harness-specific link of its own.
-  link_dir "$AGENTS_DIR" "$CHECKOUT_DIR/skills"
+  prepare_agents_dir
  LINKED_COUNT=0
  wire_skills
  link_dir "$CRUSH_DIR" "$AGENTS_DIR"
  link_dir "$OPENCODE_DIR" "$AGENTS_DIR"
-  log "done — $(count_skills) skill(s) at ref=$REF, 3 links total"
+  log "done — $LINKED_COUNT skill(s) linked from $(sources | wc -l | tr -d ' ') source(s), ref=$REF"
  log "Claude Code: install the plugin instead — /plugin marketplace add $REPO_URL"
 }
@@ -0,0 +1,263 @@
 ---
 name: cad-babysit
 description: Focused human-in-the-loop session working CAD's stuck queue (cad-stuck output). Read-only — diagnoses, never dispatches, arms a label, or closes an issue. Use when picking up whatever CAD has run into trouble on, with a human present.
 ---
 # CAD Babysit
 ## Overview
 A deliberately narrow session: pick up whatever CAD has run into trouble on, work it with a
 human present, and stop. This is not an autonomous supervisor — it is a babysitter with a
 person in the room, and that is the point, not a limitation to route around later.
 **Core principle:** an unattended supervisor reproduces the exact failure it exists to catch.
 `dispatch` ran dead for eight weeks because it exited 0 and nobody noticed (`dispatch#33`); a
 long-running watcher process that dies quietly has the same property one level up, and
 manufactures false confidence while doing it. With a human present, **the human is the
 liveness check** — that removes the objection entirely and needs no new machinery.
 This skill is the ritual around `cad stuck` (`mathias/cad#14`), not a replacement for it.
 Without that query it would be a checklist with no input; the query without this skill is
 data nobody reads carefully. Neither closes the loop alone.
 ## When to Use
 - Picking up CAD's stuck queue with a human present and time set aside to work it
 - After `dispatch` (or any executor) reports a failure and it is not immediately obvious
  whether it is an infrastructure fault or a real task outcome
 - Reviewing the "awaiting human" queue (issues CI has verified but nobody has closed)
 **Do not use for:**
 - Unattended/scheduled runs. This skill assumes a human is present for its entire duration —
  if nobody is watching, its central safety property (human-as-liveness-check) does not hold.
 - Dispatching, arming a redispatch label, or closing an issue. This skill only ever diagnoses;
  see Iron Laws.
 ## Iron Laws
 1. **Read-only, always.** No dispatching, no arming labels (including `status:redispatch`), no
   closing or reopening an issue. A reviewer that can act on its own findings has no
   independent check — control stays where it already is.
 2. **Every finding cites a locator.** A run id, commit sha, comment permalink, or a specific
   log line. A finding without one is an unfalsifiable opinion about a machine — do not emit
   it, and do not soften this into "probably" language instead of dropping it.
 3. **Re-derive, never recall.** State lives in Gitea and Actions, not in this session. Start
   cold every time: run `cad stuck` fresh, do not carry forward a prior session's worklist.
   Sessions get compacted and lose exactly the cross-run history that makes a stale worklist
   dangerous to trust.
 4. **Distinguish "blocked" from "awaiting human".** `cad stuck` already makes this split
   (`stuck` vs `awaiting_human`); preserve it in every summary. The `awaiting_human` class is
   the human gate working, not a bottleneck — do not report it as one.
 5. **Anything that is the operator's call surfaces as `DECISION NEEDED`, never gets decided
   for them.** See Output Format.
 ## Process
 ### Phase 1 — Query (re-derive the worklist)
 Run `cad stuck` against the estate (the `dispatch-repos.txt` scope, or whatever repo set the
 operator names). This is the only input. Do not substitute a memory of a prior run, a brain
 note, or this issue's own worked examples — all three can be stale within the same day (a
 taxonomy row's cited live example can stop reproducing between when it was written and when
 you run the query, because the underlying state genuinely changed; that is the design working,
 not a bug to paper over).
 Group the output by class exactly as `cad stuck` returns it: `stuck` first, `awaiting_human`
 second. Pick ONE row to work per pass — this skill is deliberately narrow, not a full-estate
 sweep.
 ### Phase 2 — Read the issue's own comments FIRST
 Before anything else, before touching Actions or pod logs: read every comment on the issue,
 oldest first. This step exists because it was skipped once and it cost a session — a confident
 wrong root cause was produced from pod logs while the correct diagnosis sat in the issue's own
 comment thread from nine days earlier (`cad-atlas#10`). The rule "read issue comments before
 working" was already written down elsewhere and was not followed; it is written down again
 here because that is exactly the kind of already-known thing a rushed session skips.
 What to look for: the bot's own report comments (routing decision, ground-truth verdict,
 attempt count), and any human comment that already contains the diagnosis.
 ### Phase 3 — THEN the Actions job logs
 Only after Phase 2 turns up nothing conclusive, read the CI job logs:
 ```
 GET /repos/{owner}/{repo}/actions/runs           # find the run, match on .run_number
 GET /repos/{owner}/{repo}/actions/jobs/{job_id}/logs   # returns 200, full text, secrets masked
 ```
 This endpoint works. A prior note claiming it 404s was wrong and cost a diagnosis the day this
 skill was written — do not rediscover that. Get the run id from `/actions/runs`, not from the
 `run_number` shown in a comment (they are different fields; match on `.run_number` to find the
 internal `id` the jobs endpoint needs).
 This is where the two most valuable findings of the day this skill is drawn from lived: an
 agent issuing the identical refused command five times and stopping (never trying the tools it
 was actually permitted to use), and a different model, same denial, writing a Go program to
 route around it. Neither is visible from the issue comments alone — no metric produces either
 of them. They need a reader of the raw transcript.
 ### Phase 4 — Separate infrastructure fault from task outcome
 A run that died before turn 1 says nothing about the issue itself. Before concluding anything
 about the WORK, check whether the run reached the model at all:
 - Zero turns, a 2-3 record transcript, a "could not start" comment, or a claim label with no
  attempt comment behind it → infrastructure fault. This is not evidence the issue is hard, ill
  specified, or that the assigned model is unsuitable — it is evidence something upstream
  (credit, a key, MCP connectivity, the executor binary) is broken.
 - A run that reached the model, drove tools, and stopped on a ceiling, a denial loop, or a
  genuine task failure → a real task outcome, worth diagnosing on its own terms.
 Four claim labels were burned this exact way in one estate sweep and the tracker read them as
 four handled issues (`dispatch#33`). Get this distinction wrong and everything downstream is
 about the wrong thing.
 ### Phase 5 — Decide, or say `DECISION NEEDED`
 For each row worked, produce one of:
 - **A closed diagnosis** — cause identified, cited to a locator, no operator judgment call
  required (e.g. "infrastructure fault, credit exhausted, see comment #N — retry is automatic
  on the next cycle, no action needed").
 - **A `DECISION NEEDED`** — anything that is genuinely the operator's call: whether to close a
  verified-but-open issue, whether to raise a ceiling, whether to abandon an issue that keeps
  hitting the same denial. Never make this call on the operator's behalf.
 This skill's OWN last act, every time, is to stop — not to dispatch, not to redispatch, not to
 close. Ending a pass is itself the enforcement of Iron Law 1.
 ## Output Format
 For a closed diagnosis:
 ```
 DIAGNOSIS: <repo>#<issue> — <category from cad stuck, e.g. ceiling_hit>
 CAUSE: <one sentence, cites the mechanism>
 LOCATOR: <url or run id / log line>
 ACTION: <what happens automatically, or "none — informational">
 ```
 For anything requiring a human call:
 ```
 DECISION NEEDED: <repo>#<issue>
 QUESTION: <the exact thing only the operator can decide>
 OPTIONS:
  1. <option> — <consequence>
  2. <option> — <consequence>
 RECOMMENDATION: <your pick, with reasoning — but the operator decides>
 BLOCKS: <what stays stuck until this is answered, if anything>
 ```
 End every pass with a one-line summary: `N diagnosed, M decisions needed, stopping.`
 ## Worked Example
 `cad stuck` returns `mathias/cad-atlas#10 [near_attempt_cap] 4 dispatch attempts recorded, at
 or above the near-cap threshold (4 of MaxAttempts=5).`
 Phase 2 (issue comments): the issue's own thread already explains the pattern — repeated
 `status:redispatch` re-arming without the label being cleared after a completed attempt.
 Phase 3: not needed — Phase 2 was conclusive.
 Phase 4: each of the 4 attempts reached the model and ran (not an infrastructure fault) — a
 real re-fire pattern, not a claim-label artifact.
 Phase 5 output:
 ```
 DECISION NEEDED: mathias/cad-atlas#10
 QUESTION: one more automatic attempt remains before MaxAttempts=5 gives up permanently. Let
  it fire, or intervene now (fix the underlying cause, or manually close/redirect the issue)?
 OPTIONS:
  1. Let it fire — costs one more headless run; if it fails the same way, dispatch gives up
     automatically and posts a terminal comment. No action needed until then.
  2. Intervene now — diagnose why redispatch keeps re-arming (likely: the watcher isn't
     clearing RedispatchLabel after a serviced run) and fix that before the cap is spent on
     a symptom rather than the cause.
 RECOMMENDATION: option 2. The pattern (redispatch not self-clearing after a completed run) is
  already documented as a known operational hazard (dispatch#54) — spending the last attempt
  on it again teaches nothing new.
 BLOCKS: nothing else; this issue's own progress.
 ```
 `1 diagnosed, 1 decision needed, stopping.`
 ## Anti-Patterns
 | Anti-Pattern | Why It Fails |
 |---|---|
 | Diagnosing from pod/Actions logs before reading issue comments | The exact mistake that cost a session — the answer was already written down nine days earlier. |
 | Reporting `awaiting_human` rows as a backlog or bottleneck | It is the human gate working. Misreporting it manufactures urgency that isn't there and trains the operator to distrust the queue. |
 | Treating a zero-turn, could-not-start run as evidence about the issue | It is an infrastructure fault. Four claim labels were burned exactly this way and read as four handled issues. |
 | Deciding a `DECISION NEEDED` case on the operator's behalf "to save time" | Removes the one property that makes this skill safe to run unattended-adjacent: the human decides, this skill only prepares the decision. |
 | Applying `status:redispatch`, closing an issue, or adding any label from this skill | Control stays where it is. This skill has no write path and should never be given one. |
 | Carrying forward a worklist from an earlier session instead of re-running `cad stuck` | State changes between sessions (see the worked note on `brain-gardener#190` in `cad#14`'s own acceptance run — its trigger label was gone hours later). A stale worklist gives false confidence, which is the specific failure mode this whole skill exists to avoid. |
 ## Honest Limitation
 This skill encodes the *repeatable* diagnostic sequence: read comments, then logs, separate
 fault from outcome, verify by exit code, re-derive rather than recall. It reliably catches the
 taxonomy `cad stuck` already knows about. It will not, by itself, produce a genuinely novel
 finding the way an unhurried human-plus-agent reading session did the day this skill was
 written — that came from noticing things (an agent editing the file that authorizes it, an
 issue body recommending a command the policy forbids) that no checklist anticipates. Expect
 this skill to be reliable on known failure modes and to miss the next new one. That is an
 acceptable trade as long as nobody mistakes a clean pass through this skill for "nothing is
 wrong" — it means "nothing on the known list is wrong."
 ## Brain MCP Integration
 **At session start:**
 - Run `brain_query` for the domain (`cad`, `dispatch`, the specific repo) to check whether a
  finding this session is about to produce has already been diagnosed and written up. Do not
  re-diagnose a known pattern from scratch every session.
 **After a genuinely novel finding (not already in the taxonomy or the brain):**
 - `brain_write` the pattern, generalized beyond the specific issue — the failure mode, not the
  issue number. Do not write routine, already-known-taxonomy findings; that is what `cad
  stuck`'s own output already records, durably, in Gitea.
 **Never:**
 - Write a `DECISION NEEDED` outcome to the brain before the operator has actually decided —
  that would record a guess as a resolution.
 ### Logging
 Call `session_log` once at the end of every phase to record the outcome.
 **At end of each phase:**
 - `session_log` with `{skill: "cad-babysit", phase: "<phase-name>", final_status: "pass" |
  "fail" | "skip", message: "<one-line summary>", duration_ms: <wall-clock>, project_root:
  "<absolute path>"}`
 **Phases for this skill:** query, read-comments, read-actions-logs, classify-fault-vs-outcome,
 decide
 **Status semantics:**
 - `pass` — the phase's intended outcome was reached (worklist re-derived; comments read;
  fault/outcome separated; a diagnosis or `DECISION NEEDED` was produced).
 - `fail` — the phase could not be completed (e.g. `cad stuck` errored, Gitea was unreachable).
 - `skip` — phase intentionally skipped (e.g. Phase 3 skipped because Phase 2 was conclusive).
 ## Mode 2 Routing Note
 Phases 2-4 (reading comments/logs, classifying fault vs outcome) are judgment-heavy and should
 stay Mode 1. Phase 1 (running `cad stuck` and grouping its output) is mechanical and a Mode 2
 routing candidate once Plan 6 ships the routing pod.
 ## Cross-References
 - Depends on `mathias/cad#14`'s `cad stuck` query — this skill is the ritual around it, not a
  replacement.
 - Load `debug` for the hypothesis-generation discipline if Phase 4's fault/outcome split is
  itself ambiguous.
 - Load `secret-hygiene` before reading raw Actions job logs if the repo is client-tagged —
  logs are secret-masked by Gitea but a pasted excerpt into a summary is not.
 - `mathias/cad-atlas#11` renders the same `cad stuck` output as a pipeline overlay — read that
  instead of this skill's text output when a visual "where is everything stuck" view is wanted
  over working one row in depth.
@@ -1,6 +1,6 @@
 ---
 name: gitea-ci
-description: End-to-end Gitea CI/CD setup with self-hosted act_runner, quality gate pipeline, buildctl image build, k3s deploy, and GitHub mirror. Covers act_runner-specific gotchas that are not documented anywhere.
+description: End-to-end Gitea CI/CD setup with self-hosted act_runner, quality gate pipeline, shared buildctl image-build script, k3s deploy, and GitHub mirror. Covers act_runner-specific gotchas that are not documented anywhere.
 ---
 # Gitea CI/CD Pipeline Setup
@@ -133,44 +133,39 @@ jobs:
            echo "version-tag=${REF#refs/tags/}" >> "$GITHUB_OUTPUT"
          fi
      # infra#309: do NOT paste a build implementation here. The estate has
      # exactly one, mathias/infra's ci-templates/build-image.sh, and each
      # repo carries a byte-identical copy at .gitea/build-image.sh that a
      # drift gate keeps current.
      #
      # Copying the implementation is what made the buildah->buildctl
      # migration (infra#241) an eleven-repo sprint, and what left this very
      # skill handing out the broken version for weeks after the app repos
      # were fixed. Per-repo differences are INPUTS, not edits to the copy.
      #
      # To adopt in a new repo:
      #   1. add the repo to mathias/infra ci-templates/adopters.txt
      #   2. run `task ci:sync` in mathias/infra -- it writes the copy
      #   3. commit .gitea/build-image.sh in your repo
      #   4. call it as below
      #
      # Skipping step 1 leaves the copy unmanaged: it works today and falls
      # silently behind the next time the canonical file changes.
      #
      # Inputs: IMAGE (required, usually the workflow-level env), SHA_TAG,
      # VERSION_TAG, GIT_SHA, IMAGE_SOURCE, BUILD_ARGS, EXTRA_LABELS,
      # CONTEXT, DOCKERFILE_DIR, DOCKERFILE_NAME, PUSH_LATEST. Read the
      # canonical file's header for the full list.
      #
      # `bash <script>`, not a direct exec: a file written through the Gitea
      # API lands 0644, and CI that depends on a file mode is a trap.
      - name: Build and push to local registry
-        run: |
+        env:
-          set -e
+          SHA_TAG: ${{ steps.meta.outputs.sha-tag }}
-          # buildctl, NOT buildah (infra#241). The runner is a pod with
+          VERSION_TAG: ${{ steps.meta.outputs.version-tag }}
-          # `capabilities: drop [ALL]` and `allowPrivilegeEscalation: false`,
+          GIT_SHA: ${{ github.sha }}
-          # so rootless buildah cannot remap UID/GID for a fresh base-image
+          IMAGE_SOURCE: ${{ github.repositoryUrl }}
-          # pull and the pod has no OCI runtime -- every `RUN` step fails.
+        run: bash .gitea/build-image.sh
          # buildctl is a thin client: it hands the build to the host's
          # buildkitd over a socket, so the privileged work happens on the
          # host and the pod's securityContext is not in the picture.
          # The failure is LATENT -- warm base-image layers mask it, so a
          # buildah step can look fine for weeks and then fail on a cold pull.
          BUILDKIT_HOST="unix:///run/buildkit/buildkitd.sock"
          REGISTRY="localhost:5000"
          REF="${REGISTRY}/${{ env.IMAGE }}:${{ steps.meta.outputs.sha-tag }}"
          TAR_FILE="$(mktemp)"
          trap 'rm -f "$TAR_FILE"' EXIT
          buildctl --addr "$BUILDKIT_HOST" build \
            --frontend dockerfile.v0 \
            --local context=. \
            --local dockerfile=. \
            --opt label:org.opencontainers.image.revision="${{ github.sha }}" \
            --opt label:org.opencontainers.image.source="${{ github.repositoryUrl }}" \
            --output type=oci,dest="$TAR_FILE"
          # buildctl has no registry-push equivalent to `buildah push`; skopeo
          # copies the OCI archive up, once per tag.
          skopeo copy --dest-tls-verify=false \
            oci-archive:"$TAR_FILE" docker://${REF}
          skopeo copy --dest-tls-verify=false \
            oci-archive:"$TAR_FILE" docker://${REGISTRY}/${{ env.IMAGE }}:latest
          if [ -n "${{ steps.meta.outputs.version-tag }}" ]; then
            skopeo copy --dest-tls-verify=false \
              oci-archive:"$TAR_FILE" \
              docker://${REGISTRY}/${{ env.IMAGE }}:${{ steps.meta.outputs.version-tag }}
          fi
          echo "✓ Image pushed to ${REF}"
      # No smoke test step. The one this skill used to recommend ran
      # `sudo k3s ctr run` against the host's containerd -- that worked when
@@ -1,371 +0,0 @@
 ---
 name: test-driven-development
 description: Use when implementing any feature or bugfix, before writing implementation code
 ---
 # Test-Driven Development (TDD)
 ## Overview
 Write the test first. Watch it fail. Write minimal code to pass.
 **Core principle:** If you didn't watch the test fail, you don't know if it tests the right thing.
 **Violating the letter of the rules is violating the spirit of the rules.**
 ## When to Use
 **Always:**
 - New features
 - Bug fixes
 - Refactoring
 - Behavior changes
 **Exceptions (ask your human partner):**
 - Throwaway prototypes
 - Generated code
 - Configuration files
 Thinking "skip TDD just this once"? Stop. That's rationalization.
 ## The Iron Law
 ```
 NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST
 ```
 Write code before the test? Delete it. Start over.
 **No exceptions:**
 - Don't keep it as "reference"
 - Don't "adapt" it while writing tests
 - Don't look at it
 - Delete means delete
 Implement fresh from tests. Period.
 ## Red-Green-Refactor
 ```dot
 digraph tdd_cycle {
    rankdir=LR;
    red [label="RED\nWrite failing test", shape=box, style=filled, fillcolor="#ffcccc"];
    verify_red [label="Verify fails\ncorrectly", shape=diamond];
    green [label="GREEN\nMinimal code", shape=box, style=filled, fillcolor="#ccffcc"];
    verify_green [label="Verify passes\nAll green", shape=diamond];
    refactor [label="REFACTOR\nClean up", shape=box, style=filled, fillcolor="#ccccff"];
    next [label="Next", shape=ellipse];
    red -> verify_red;
    verify_red -> green [label="yes"];
    verify_red -> red [label="wrong\nfailure"];
    green -> verify_green;
    verify_green -> refactor [label="yes"];
    verify_green -> green [label="no"];
    refactor -> verify_green [label="stay\ngreen"];
    verify_green -> next;
    next -> red;
 }
 ```
 ### RED - Write Failing Test
 Write one minimal test showing what should happen.
 <Good>
 ```typescript
 test('retries failed operations 3 times', async () => {
  let attempts = 0;
  const operation = () => {
    attempts++;
    if (attempts < 3) throw new Error('fail');
    return 'success';
  };
  const result = await retryOperation(operation);
  expect(result).toBe('success');
  expect(attempts).toBe(3);
 });
 ```
 Clear name, tests real behavior, one thing
 </Good>
 <Bad>
 ```typescript
 test('retry works', async () => {
  const mock = jest.fn()
    .mockRejectedValueOnce(new Error())
    .mockRejectedValueOnce(new Error())
    .mockResolvedValueOnce('success');
  await retryOperation(mock);
  expect(mock).toHaveBeenCalledTimes(3);
 });
 ```
 Vague name, tests mock not code
 </Bad>
 **Requirements:**
 - One behavior
 - Clear name
 - Real code (no mocks unless unavoidable)
 ### Verify RED - Watch It Fail
 **MANDATORY. Never skip.**
 ```bash
 npm test path/to/test.test.ts
 ```
 Confirm:
 - Test fails (not errors)
 - Failure message is expected
 - Fails because feature missing (not typos)
 **Test passes?** You're testing existing behavior. Fix test.
 **Test errors?** Fix error, re-run until it fails correctly.
 ### GREEN - Minimal Code
 Write simplest code to pass the test.
 <Good>
 ```typescript
 async function retryOperation<T>(fn: () => Promise<T>): Promise<T> {
  for (let i = 0; i < 3; i++) {
    try {
      return await fn();
    } catch (e) {
      if (i === 2) throw e;
    }
  }
  throw new Error('unreachable');
 }
 ```
 Just enough to pass
 </Good>
 <Bad>
 ```typescript
 async function retryOperation<T>(
  fn: () => Promise<T>,
  options?: {
    maxRetries?: number;
    backoff?: 'linear' | 'exponential';
    onRetry?: (attempt: number) => void;
  }
 ): Promise<T> {
  // YAGNI
 }
 ```
 Over-engineered
 </Bad>
 Don't add features, refactor other code, or "improve" beyond the test.
 ### Verify GREEN - Watch It Pass
 **MANDATORY.**
 ```bash
 npm test path/to/test.test.ts
 ```
 Confirm:
 - Test passes
 - Other tests still pass
 - Output pristine (no errors, warnings)
 **Test fails?** Fix code, not test.
 **Other tests fail?** Fix now.
 ### REFACTOR - Clean Up
 After green only:
 - Remove duplication
 - Improve names
 - Extract helpers
 Keep tests green. Don't add behavior.
 ### Repeat
 Next failing test for next feature.
 ## Good Tests
 | Quality | Good | Bad |
 |---------|------|-----|
 | **Minimal** | One thing. "and" in name? Split it. | `test('validates email and domain and whitespace')` |
 | **Clear** | Name describes behavior | `test('test1')` |
 | **Shows intent** | Demonstrates desired API | Obscures what code should do |
 ## Why Order Matters
 **"I'll write tests after to verify it works"**
 Tests written after code pass immediately. Passing immediately proves nothing:
 - Might test wrong thing
 - Might test implementation, not behavior
 - Might miss edge cases you forgot
 - You never saw it catch the bug
 Test-first forces you to see the test fail, proving it actually tests something.
 **"I already manually tested all the edge cases"**
 Manual testing is ad-hoc. You think you tested everything but:
 - No record of what you tested
 - Can't re-run when code changes
 - Easy to forget cases under pressure
 - "It worked when I tried it" ≠ comprehensive
 Automated tests are systematic. They run the same way every time.
 **"Deleting X hours of work is wasteful"**
 Sunk cost fallacy. The time is already gone. Your choice now:
 - Delete and rewrite with TDD (X more hours, high confidence)
 - Keep it and add tests after (30 min, low confidence, likely bugs)
 The "waste" is keeping code you can't trust. Working code without real tests is technical debt.
 **"TDD is dogmatic, being pragmatic means adapting"**
 TDD IS pragmatic:
 - Finds bugs before commit (faster than debugging after)
 - Prevents regressions (tests catch breaks immediately)
 - Documents behavior (tests show how to use code)
 - Enables refactoring (change freely, tests catch breaks)
 "Pragmatic" shortcuts = debugging in production = slower.
 **"Tests after achieve the same goals - it's spirit not ritual"**
 No. Tests-after answer "What does this do?" Tests-first answer "What should this do?"
 Tests-after are biased by your implementation. You test what you built, not what's required. You verify remembered edge cases, not discovered ones.
 Tests-first force edge case discovery before implementing. Tests-after verify you remembered everything (you didn't).
 30 minutes of tests after ≠ TDD. You get coverage, lose proof tests work.
 ## Common Rationalizations
 | Excuse | Reality |
 |--------|---------|
 | "Too simple to test" | Simple code breaks. Test takes 30 seconds. |
 | "I'll test after" | Tests passing immediately prove nothing. |
 | "Tests after achieve same goals" | Tests-after = "what does this do?" Tests-first = "what should this do?" |
 | "Already manually tested" | Ad-hoc ≠ systematic. No record, can't re-run. |
 | "Deleting X hours is wasteful" | Sunk cost fallacy. Keeping unverified code is technical debt. |
 | "Keep as reference, write tests first" | You'll adapt it. That's testing after. Delete means delete. |
 | "Need to explore first" | Fine. Throw away exploration, start with TDD. |
 | "Test hard = design unclear" | Listen to test. Hard to test = hard to use. |
 | "TDD will slow me down" | TDD faster than debugging. Pragmatic = test-first. |
 | "Manual test faster" | Manual doesn't prove edge cases. You'll re-test every change. |
 | "Existing code has no tests" | You're improving it. Add tests for existing code. |
 ## Red Flags - STOP and Start Over
 - Code before test
 - Test after implementation
 - Test passes immediately
 - Can't explain why test failed
 - Tests added "later"
 - Rationalizing "just this once"
 - "I already manually tested it"
 - "Tests after achieve the same purpose"
 - "It's about spirit not ritual"
 - "Keep as reference" or "adapt existing code"
 - "Already spent X hours, deleting is wasteful"
 - "TDD is dogmatic, I'm being pragmatic"
 - "This is different because..."
 **All of these mean: Delete code. Start over with TDD.**
 ## Example: Bug Fix
 **Bug:** Empty email accepted
 **RED**
 ```typescript
 test('rejects empty email', async () => {
  const result = await submitForm({ email: '' });
  expect(result.error).toBe('Email required');
 });
 ```
 **Verify RED**
 ```bash
 $ npm test
 FAIL: expected 'Email required', got undefined
 ```
 **GREEN**
 ```typescript
 function submitForm(data: FormData) {
  if (!data.email?.trim()) {
    return { error: 'Email required' };
  }
  // ...
 }
 ```
 **Verify GREEN**
 ```bash
 $ npm test
 PASS
 ```
 **REFACTOR**
 Extract validation for multiple fields if needed.
 ## Verification Checklist
 Before marking work complete:
 - [ ] Every new function/method has a test
 - [ ] Watched each test fail before implementing
 - [ ] Each test failed for expected reason (feature missing, not typo)
 - [ ] Wrote minimal code to pass each test
 - [ ] All tests pass
 - [ ] Output pristine (no errors, warnings)
 - [ ] Tests use real code (mocks only if unavoidable)
 - [ ] Edge cases and errors covered
 Can't check all boxes? You skipped TDD. Start over.
 ## When Stuck
 | Problem | Solution |
 |---------|----------|
 | Don't know how to test | Write wished-for API. Write assertion first. Ask your human partner. |
 | Test too complicated | Design too complicated. Simplify interface. |
 | Must mock everything | Code too coupled. Use dependency injection. |
 | Test setup huge | Extract helpers. Still complex? Simplify design. |
 ## Debugging Integration
 Bug found? Write failing test reproducing it. Follow TDD cycle. Test proves fix and prevents regression.
 Never fix bugs without a test.
 ## Testing Anti-Patterns
 When adding mocks or test utilities, read @testing-anti-patterns.md to avoid common pitfalls:
 - Testing mock behavior instead of real behavior
 - Adding test-only methods to production classes
 - Mocking without understanding dependencies
 ## Final Rule
 ```
 Production code → test exists and failed first
 Otherwise → not TDD
 ```
 No exceptions without your human partner's permission.
@@ -1,299 +0,0 @@
 # Testing Anti-Patterns
 **Load this reference when:** writing or changing tests, adding mocks, or tempted to add test-only methods to production code.
 ## Overview
 Tests must verify real behavior, not mock behavior. Mocks are a means to isolate, not the thing being tested.
 **Core principle:** Test what the code does, not what the mocks do.
 **Following strict TDD prevents these anti-patterns.**
 ## The Iron Laws
 ```
 1. NEVER test mock behavior
 2. NEVER add test-only methods to production classes
 3. NEVER mock without understanding dependencies
 ```
 ## Anti-Pattern 1: Testing Mock Behavior
 **The violation:**
 ```typescript
 // ❌ BAD: Testing that the mock exists
 test('renders sidebar', () => {
  render(<Page />);
  expect(screen.getByTestId('sidebar-mock')).toBeInTheDocument();
 });
 ```
 **Why this is wrong:**
 - You're verifying the mock works, not that the component works
 - Test passes when mock is present, fails when it's not
 - Tells you nothing about real behavior
 **your human partner's correction:** "Are we testing the behavior of a mock?"
 **The fix:**
 ```typescript
 // ✅ GOOD: Test real component or don't mock it
 test('renders sidebar', () => {
  render(<Page />);  // Don't mock sidebar
  expect(screen.getByRole('navigation')).toBeInTheDocument();
 });
 // OR if sidebar must be mocked for isolation:
 // Don't assert on the mock - test Page's behavior with sidebar present
 ```
 ### Gate Function
 ```
 BEFORE asserting on any mock element:
  Ask: "Am I testing real component behavior or just mock existence?"
  IF testing mock existence:
    STOP - Delete the assertion or unmock the component
  Test real behavior instead
 ```
 ## Anti-Pattern 2: Test-Only Methods in Production
 **The violation:**
 ```typescript
 // ❌ BAD: destroy() only used in tests
 class Session {
  async destroy() {  // Looks like production API!
    await this._workspaceManager?.destroyWorkspace(this.id);
    // ... cleanup
  }
 }
 // In tests
 afterEach(() => session.destroy());
 ```
 **Why this is wrong:**
 - Production class polluted with test-only code
 - Dangerous if accidentally called in production
 - Violates YAGNI and separation of concerns
 - Confuses object lifecycle with entity lifecycle
 **The fix:**
 ```typescript
 // ✅ GOOD: Test utilities handle test cleanup
 // Session has no destroy() - it's stateless in production
 // In test-utils/
 export async function cleanupSession(session: Session) {
  const workspace = session.getWorkspaceInfo();
  if (workspace) {
    await workspaceManager.destroyWorkspace(workspace.id);
  }
 }
 // In tests
 afterEach(() => cleanupSession(session));
 ```
 ### Gate Function
 ```
 BEFORE adding any method to production class:
  Ask: "Is this only used by tests?"
  IF yes:
    STOP - Don't add it
    Put it in test utilities instead
  Ask: "Does this class own this resource's lifecycle?"
  IF no:
    STOP - Wrong class for this method
 ```
 ## Anti-Pattern 3: Mocking Without Understanding
 **The violation:**
 ```typescript
 // ❌ BAD: Mock breaks test logic
 test('detects duplicate server', () => {
  // Mock prevents config write that test depends on!
  vi.mock('ToolCatalog', () => ({
    discoverAndCacheTools: vi.fn().mockResolvedValue(undefined)
  }));
  await addServer(config);
  await addServer(config);  // Should throw - but won't!
 });
 ```
 **Why this is wrong:**
 - Mocked method had side effect test depended on (writing config)
 - Over-mocking to "be safe" breaks actual behavior
 - Test passes for wrong reason or fails mysteriously
 **The fix:**
 ```typescript
 // ✅ GOOD: Mock at correct level
 test('detects duplicate server', () => {
  // Mock the slow part, preserve behavior test needs
  vi.mock('MCPServerManager'); // Just mock slow server startup
  await addServer(config);  // Config written
  await addServer(config);  // Duplicate detected ✓
 });
 ```
 ### Gate Function
 ```
 BEFORE mocking any method:
  STOP - Don't mock yet
  1. Ask: "What side effects does the real method have?"
  2. Ask: "Does this test depend on any of those side effects?"
  3. Ask: "Do I fully understand what this test needs?"
  IF depends on side effects:
    Mock at lower level (the actual slow/external operation)
    OR use test doubles that preserve necessary behavior
    NOT the high-level method the test depends on
  IF unsure what test depends on:
    Run test with real implementation FIRST
    Observe what actually needs to happen
    THEN add minimal mocking at the right level
  Red flags:
    - "I'll mock this to be safe"
    - "This might be slow, better mock it"
    - Mocking without understanding the dependency chain
 ```
 ## Anti-Pattern 4: Incomplete Mocks
 **The violation:**
 ```typescript
 // ❌ BAD: Partial mock - only fields you think you need
 const mockResponse = {
  status: 'success',
  data: { userId: '123', name: 'Alice' }
  // Missing: metadata that downstream code uses
 };
 // Later: breaks when code accesses response.metadata.requestId
 ```
 **Why this is wrong:**
 - **Partial mocks hide structural assumptions** - You only mocked fields you know about
 - **Downstream code may depend on fields you didn't include** - Silent failures
 - **Tests pass but integration fails** - Mock incomplete, real API complete
 - **False confidence** - Test proves nothing about real behavior
 **The Iron Rule:** Mock the COMPLETE data structure as it exists in reality, not just fields your immediate test uses.
 **The fix:**
 ```typescript
 // ✅ GOOD: Mirror real API completeness
 const mockResponse = {
  status: 'success',
  data: { userId: '123', name: 'Alice' },
  metadata: { requestId: 'req-789', timestamp: 1234567890 }
  // All fields real API returns
 };
 ```
 ### Gate Function
 ```
 BEFORE creating mock responses:
  Check: "What fields does the real API response contain?"
  Actions:
    1. Examine actual API response from docs/examples
    2. Include ALL fields system might consume downstream
    3. Verify mock matches real response schema completely
  Critical:
    If you're creating a mock, you must understand the ENTIRE structure
    Partial mocks fail silently when code depends on omitted fields
  If uncertain: Include all documented fields
 ```
 ## Anti-Pattern 5: Integration Tests as Afterthought
 **The violation:**
 ```
 ✅ Implementation complete
 ❌ No tests written
 "Ready for testing"
 ```
 **Why this is wrong:**
 - Testing is part of implementation, not optional follow-up
 - TDD would have caught this
 - Can't claim complete without tests
 **The fix:**
 ```
 TDD cycle:
 1. Write failing test
 2. Implement to pass
 3. Refactor
 4. THEN claim complete
 ```
 ## When Mocks Become Too Complex
 **Warning signs:**
 - Mock setup longer than test logic
 - Mocking everything to make test pass
 - Mocks missing methods real components have
 - Test breaks when mock changes
 **your human partner's question:** "Do we need to be using a mock here?"
 **Consider:** Integration tests with real components often simpler than complex mocks
 ## TDD Prevents These Anti-Patterns
 **Why TDD helps:**
 1. **Write test first** → Forces you to think about what you're actually testing
 2. **Watch it fail** → Confirms test tests real behavior, not mocks
 3. **Minimal implementation** → No test-only methods creep in
 4. **Real dependencies** → You see what the test actually needs before mocking
 **If you're testing mock behavior, you violated TDD** - you added mocks without watching test fail against real code first.
 ## Quick Reference
 | Anti-Pattern | Fix |
 |--------------|-----|
 | Assert on mock elements | Test real component or unmock it |
 | Test-only methods in production | Move to test utilities |
 | Mock without understanding | Understand dependencies first, mock minimally |
 | Incomplete mocks | Mirror real API completely |
 | Tests as afterthought | TDD - tests first |
 | Over-complex mocks | Consider integration tests |
 ## Red Flags
 - Assertion checks for `*-mock` test IDs
 - Methods only called in test files
 - Mock setup is >50% of test
 - Test fails when you remove mock
 - Can't explain why mock is needed
 - Mocking "just to be safe"
 ## The Bottom Line
 **Mocks are tools to isolate, not things to test.**
 If TDD reveals you're testing mock behavior, you've gone wrong.
 Fix: Test real behavior or question why you're mocking at all.
@@ -22,18 +22,28 @@ Screenshot a locally-running web UI without installing a browser on the agent's
 ## Usage
 `shot.sh` ships beside this SKILL.md, so resolve it from wherever the harness
 installed the skill rather than from a checkout path — an absolute `~/dev/...`
 went stale the first time the repo moved and cost a caller three hand-rolled
 Job attempts before they found the working script (#26).
 ```bash
 # Claude Code installs the plugin; Crush/Pi/OpenCode get ~/.agents/skills.
 SHOT=$(ls ~/.claude/plugins/marketplaces/*/skills/web-shot/shot.sh \
          ~/.agents/skills/web-shot/shot.sh 2>/dev/null | head -1 || true)
 [ -n "$SHOT" ] || { echo "web-shot not installed on this host: run install.sh or the plugin install" >&2; exit 1; }
 # auto-detect Tailscale hostname, screenshot port 8099 root
-~/dev/.skills/web-shot/shot.sh --port 8099
+"$SHOT" --port 8099
 # explicit URL
-~/dev/.skills/web-shot/shot.sh --url http://flamingo:5173
+"$SHOT" --url http://flamingo:5173
 # capture a search state too (types into input[name=q])
-~/dev/.skills/web-shot/shot.sh --port 8181 --search agentsquad
+"$SHOT" --port 8181 --search agentsquad
 # different output dir
-~/dev/.skills/web-shot/shot.sh --port 3000 --out /tmp/shots
+"$SHOT" --port 3000 --out /tmp/shots
 ```
 ## Flags
@@ -0,0 +1,70 @@
 #!/bin/sh
 # Tests for bin/check-index.
 #
 # The regression these exist for: SKILLS_INDEX.md is maintained by hand, and
 # two skills (`dream`, `experiment-spec`) shipped without a row — the index
 # rows lived on feature branches that were squash-merged after a directory
 # reorg, so the SKILL.md landed and the row did not (#15, #22). Nothing
 # errored; the index just quietly under-reported the library.
 set -u
 ROOT=$(CDPATH= cd -- "$(dirname -- "$0")/.." && pwd)
 SUT="$ROOT/bin/check-index"
 pass=0
 fail=0
 WORK=${TMPDIR:-/tmp}/check_index_test.$$
 if [ ! -f "$SUT" ]; then
  printf 'FAIL: %s does not exist\n' "$SUT"
  exit 1
 fi
 cleanup() { rm -rf "$WORK"; }
 trap cleanup EXIT INT TERM
 # new_fixture <name> — a checkout with skills/alpha and skills/beta.
 new_fixture() {
  _f="$WORK/$1"
  mkdir -p "$_f/skills/alpha" "$_f/skills/beta"
  printf -- '---\nname: alpha\ndescription: a\n---\n' > "$_f/skills/alpha/SKILL.md"
  printf -- '---\nname: beta\ndescription: b\n---\n' > "$_f/skills/beta/SKILL.md"
  printf '%s' "$_f"
 }
 index() {
  _dir=$1; shift
  printf '# Engineering Skills Index\n\n| Skill | Description | Use when |\n|---|---|---|\n' > "$_dir/SKILLS_INDEX.md"
  for _n in "$@"; do
    printf '| `%s` | desc | when |\n' "$_n" >> "$_dir/SKILLS_INDEX.md"
  done
 }
 # expect <0|1> <label> <fixture> [grep-for]
 expect() {
  _want=$1; _label=$2; _fx=$3; _needle=${4:-}
  _out=$(sh "$SUT" "$_fx" 2>&1); _rc=$?
  if [ "$_rc" -ne "$_want" ]; then
    fail=$((fail + 1)); printf '  FAIL %s (want rc=%s got %s)\n%s\n' "$_label" "$_want" "$_rc" "$_out"; return
  fi
  if [ -n "$_needle" ] && ! printf '%s' "$_out" | grep -q "$_needle"; then
    fail=$((fail + 1)); printf '  FAIL %s (rc ok, but report never names %s)\n%s\n' "$_label" "$_needle" "$_out"; return
  fi
  pass=$((pass + 1)); printf '  ok   %s\n' "$_label"
 }
 fx=$(new_fixture complete); index "$fx" alpha beta
 expect 0 'every skill has a row' "$fx"
 fx=$(new_fixture missing); index "$fx" alpha
 expect 1 'a skill with no row is reported' "$fx" beta
 fx=$(new_fixture stale); index "$fx" alpha beta gamma
 expect 1 'a row for a skill that does not exist is reported' "$fx" gamma
 fx=$(new_fixture noindex)
 expect 1 'a missing index is reported' "$fx" SKILLS_INDEX.md
 printf '\ncheck_index: %d passed, %d failed\n' "$pass" "$fail"
 [ "$fail" -eq 0 ]
@@ -0,0 +1,57 @@
 #!/bin/sh
 # Tests for the CI gate workflow.
 #
 # The regression these exist for: this repo had a release workflow that
 # auto-tagged every push to main, and a `task check` / `task test` suite that
 # nothing ever ran. CI reported green having tested nothing — a gate that
 # fails *open*. These assertions pin the wiring so it cannot silently regress.
 set -u
 ROOT=$(CDPATH= cd -- "$(dirname -- "$0")/.." && pwd)
 SUT="$ROOT/.gitea/workflows/ci.yml"
 pass=0
 fail=0
 ok() { pass=$((pass + 1)); printf '  ok   %s\n' "$1"; }
 no() { fail=$((fail + 1)); printf '  FAIL %s\n' "$1"; }
 if [ ! -f "$SUT" ]; then
  printf 'FAIL: %s does not exist\n' "$SUT"
  exit 1
 fi
 ok 'ci.yml exists'
 # A pull_request trigger is what gives tbd_ship a CI run to read on the head
 # commit of a branch; without one it fails closed and never merges (#22).
 grep -qE '^  pull_request:' "$SUT" \
  && ok 'runs on pull_request' \
  || no 'runs on pull_request'
 grep -qE '^ +push:' "$SUT" \
  && ok 'runs on push' \
  || no 'runs on push'
 grep -qE '^ +- *(run: *)?task check$|task check' "$SUT" \
  && ok 'gate runs task check' \
  || no 'gate runs task check'
 grep -qE 'task test' "$SUT" \
  && ok 'gate runs task test' \
  || no 'gate runs task test'
 # The point of the gate: tagging must not happen on a red check.
 tag_job=$(awk '/^  tag:/{f=1} f&&/^  [a-z][a-z_-]*:/&&!/^  tag:/{f=0} f' "$SUT")
 printf '%s' "$tag_job" | grep -qE '^ +needs: *gate' \
  && ok 'tag job needs the gate' \
  || no 'tag job needs the gate'
 # The old workflow file must be gone, or two workflows race on the same push
 # and the ungated one still tags.
 [ ! -f "$ROOT/.gitea/workflows/release.yml" ] \
  && ok 'ungated release.yml removed' \
  || no 'ungated release.yml removed'
 printf '\nci_gate: %d passed, %d failed\n' "$pass" "$fail"
 [ "$fail" -eq 0 ]
@@ -37,11 +37,21 @@ new_fixture() {
  printf '%s' "$_f"
 }
-# wire_clean <fixture> — the correct wiring: one canonical link, harnesses
+# wire_clean <fixture> [extra-source-dir] — the correct wiring since #27: the
-# pointing at it.
+# canonical location is a REAL directory of per-skill links, fed by one or more
 # sources, with each harness keeping its single directory link to it.
 wire_clean() {
-  mkdir -p "$1/home/.agents" "$1/home/.config/crush" "$1/home/.config/opencode"
+  mkdir -p "$1/home/.agents/skills" "$1/home/.config/crush" "$1/home/.config/opencode"
-  ln -sfn "$1/ck/skills" "$1/home/.agents/skills"
+  for _d in "$1"/ck/skills/*/; do
    ln -sfn "${_d%/}" "$1/home/.agents/skills/$(basename "$_d")"
  done
  printf '%s\n' "$1/ck/skills" > "$1/home/.agents/skills-sources"
  if [ -n "${2:-}" ]; then
    for _d in "$2"/*/; do
      ln -sfn "${_d%/}" "$1/home/.agents/skills/$(basename "$_d")"
    done
    printf '%s\n' "$2" >> "$1/home/.agents/skills-sources"
  fi
  ln -sfn "$1/home/.agents/skills" "$1/home/.config/crush/skills"
  ln -sfn "$1/home/.agents/skills" "$1/home/.config/opencode/skills"
 }
@@ -79,27 +89,43 @@ assert_clean "$f" 'clean fixture exits 0'
 # --- 2. dangling link (the 243-link case, gitignored and invisible) ----------
 f=$(new_fixture dangling); wire_clean "$f"
-ln -sfn "$f/ck/skills-that-moved" "$f/home/.agents/skills"
+ln -sfn "$f/ck/skills/vanished" "$f/home/.agents/skills/alpha"
-assert_fails "$f" 'dangling' 'dangling canonical link is reported'
+assert_fails "$f" 'dangling' 'dangling per-skill link is reported'
-# --- 3. resolves, but to a DIFFERENT checkout (the silent-stale case) --------
+# --- 3. resolves, but into a source nobody configured (silent-stale case) ----
 # Worse than dangling: it works, so nothing complains, while serving content
-# from a checkout that is months behind.
+# from a checkout that is months behind. Since #27 a link may legitimately
 # point outside the checkout — but only into a source the installer recorded.
 f=$(new_fixture stale)
-mkdir -p "$f/other/skills/alpha" "$f/other/skills/beta"
+mkdir -p "$f/other/alpha"
-printf -- '---\nname: alpha\ndescription: a\n---\n' > "$f/other/skills/alpha/SKILL.md"
+printf -- '---\nname: alpha\ndescription: a\n---\n' > "$f/other/alpha/SKILL.md"
 printf -- '---\nname: beta\ndescription: b\n---\n' > "$f/other/skills/beta/SKILL.md"
 wire_clean "$f"
-ln -sfn "$f/other/skills" "$f/home/.agents/skills"
+ln -sfn "$f/other/alpha" "$f/home/.agents/skills/alpha"
-assert_fails "$f" 'outside' 'link into a foreign checkout is reported'
+assert_fails "$f" 'unknown source' 'link into an unconfigured source is reported'
-# --- 4. count mismatch (a harness seeing fewer skills than the checkout) -----
+# --- 3b. a link into a CONFIGURED extra source is healthy -------------------
-f=$(new_fixture count)
+# The whole point of #27: Anthropic's official set alongside this library.
-mkdir -p "$f/home/.config/crush/skills/alpha"
+f=$(new_fixture multisource)
-printf -- '---\nname: alpha\ndescription: a\n---\n' > "$f/home/.config/crush/skills/alpha/SKILL.md"
+mkdir -p "$f/other/xlsx"
-mkdir -p "$f/home/.agents"
+printf -- '---\nname: xlsx\ndescription: x\n---\n' > "$f/other/xlsx/SKILL.md"
 wire_clean "$f" "$f/other"
 assert_clean "$f" 'a link into a configured extra source is healthy'
 # --- 3c. the pre-#27 single-link wiring is named, not mistaken for damage ----
 f=$(new_fixture legacy)
 mkdir -p "$f/home/.agents" "$f/home/.config/crush" "$f/home/.config/opencode"
 ln -sfn "$f/ck/skills" "$f/home/.agents/skills"
-assert_fails "$f" 'count' 'skill-count mismatch is reported'
+ln -sfn "$f/home/.agents/skills" "$f/home/.config/crush/skills"
 ln -sfn "$f/home/.agents/skills" "$f/home/.config/opencode/skills"
 assert_fails "$f" 'single-link' 'legacy single-link wiring is reported as such'
 # --- 4. a skill in the checkout with no link anywhere ------------------------
 # The multi-source replacement for the old count check: with per-skill links a
 # skill can be missing individually, which a total count would hide if an extra
 # source happened to supply the same number.
 f=$(new_fixture missing); wire_clean "$f"
 rm -f "$f/home/.agents/skills/beta"
 assert_fails "$f" 'beta' 'a checkout skill with no link is reported'
 # --- 5. stray entry (the loose secret-hygiene.md that loaded nowhere) --------
 f=$(new_fixture stray); wire_clean "$f"
@@ -112,6 +138,19 @@ mkdir -p "$f/home/.claude/skills"
 ln -sfn "$f/ck/skills/alpha" "$f/home/.claude/skills/alpha"
 assert_fails "$f" 'legacy' 'leftover per-skill Claude symlinks are reported'
 # --- 7b. harness dir is a REAL directory, not a link into the checkout -------
 # Found on flamingo 2026-08-26: ~/.config/crush/skills held real directories
 # from a pre-plugin install. The old message read "resolves to
 # <path>, outside the active checkout" — naming the directory as its own
 # resolution target, which is true but useless. It must say the dir is not a
 # link at all, because the fix (move it aside, re-run install.sh) is different
 # from the fix for a link into a foreign checkout.
 f=$(new_fixture realdir); wire_clean "$f"
 rm -f "$f/home/.config/crush/skills"
 mkdir -p "$f/home/.config/crush/skills/alpha"
 printf -- '---\nname: alpha\ndescription: a\n---\n' > "$f/home/.config/crush/skills/alpha/SKILL.md"
 assert_fails "$f" 'not a link' 'real directory is reported as unmanaged, not as "outside"'
 # --- 7. dangling link inside a harness dir (not the canonical link itself) --
 # Exercises the per-entry scan rather than the canonical-link check: this is
 # the shape the 243 dead links actually had.
@@ -120,5 +159,63 @@ mkdir -p "$f/home/.claude/skills"
 ln -sfn "$f/ck/skills/vanished" "$f/home/.claude/skills/vanished"
 assert_fails "$f" 'dangling' 'dangling link inside a harness dir is reported'
 # --- 8. Claude Code plugin pinned to an older version than is available -----
 # The plugin is the ONLY delivery channel for Claude Code, and Claude Code
 # gates updates on plugin.json's version field. A host that never picked the
 # new one up loads every skill successfully — just the wrong generation. Found
 # live on koala 2026-08-29: installed 0.6.0, marketplace 0.7.0, repo 0.8.5,
 # and doctor said "clean" (#30).
 # installed_state <fixture> <version> — the Claude Code install record.
 installed_state() {
  mkdir -p "$1/home/.claude/plugins"
  cat > "$1/home/.claude/plugins/installed_plugins.json" <<JSON
 {
  "version": 2,
  "plugins": {
    "skills@mathias": [
      {
        "scope": "user",
        "installPath": "/somewhere/$2",
        "version": "$2"
      }
    ]
  }
 }
 JSON
 }
 # manifest <dir> <version> — a .claude-plugin/plugin.json under <dir>.
 manifest() {
  mkdir -p "$1/.claude-plugin"
  printf '{\n  "name": "skills",\n  "version": "%s"\n}\n' "$2" > "$1/.claude-plugin/plugin.json"
 }
 f=$(new_fixture pluginmatch); wire_clean "$f"
 installed_state "$f" 0.8.0
 manifest "$f/ck" 0.8.0
 assert_clean "$f" 'plugin on the current version stays silent'
 f=$(new_fixture pluginstale); wire_clean "$f"
 installed_state "$f" 0.7.0
 manifest "$f/ck" 0.8.0
 assert_fails "$f" '0.7.0' 'stale plugin version is reported'
 assert_fails "$f" '0.8.0' 'stale plugin report names the available version'
 # A host that only uses the symlink path has no install record at all. That is
 # a valid configuration and must not fail.
 f=$(new_fixture pluginabsent); wire_clean "$f"
 manifest "$f/ck" 0.8.0
 assert_clean "$f" 'no Claude Code install record is not a fault'
 # The marketplace clone is what Claude Code compares against, so a newer
 # version there means an update is waiting even when the local checkout agrees
 # with what is installed.
 f=$(new_fixture pluginmarket); wire_clean "$f"
 installed_state "$f" 0.7.0
 manifest "$f/ck" 0.7.0
 manifest "$f/home/.claude/plugins/marketplaces/mathias" 0.9.0
 assert_fails "$f" '0.9.0' 'a newer marketplace clone is reported'
 printf '\ndoctor: %d passed, %d failed\n' "$pass" "$fail"
 [ "$fail" -eq 0 ]
@@ -0,0 +1,160 @@
 #!/bin/sh
 # Tests for install.sh's wiring model.
 #
 # The regression these exist for: install.sh wired each harness with ONE
 # directory symlink to this checkout, which quietly encoded "this checkout is
 # the only source of skills on the host". On flamingo the Crush directory held
 # Anthropic's official skill set, and the only way to install this library was
 # to displace it — a real capability loss dressed up as a tidy-up (#27).
 #
 # Fixtures drive install.sh entirely through env seams, so no test touches the
 # real host wiring.
 set -u
 ROOT=$(CDPATH= cd -- "$(dirname -- "$0")/.." && pwd)
 SUT="$ROOT/install.sh"
 pass=0
 fail=0
 WORK=${TMPDIR:-/tmp}/install_test.$$
 if [ ! -f "$SUT" ]; then
  printf 'FAIL: %s does not exist\n' "$SUT"
  exit 1
 fi
 cleanup() { rm -rf "$WORK"; }
 trap cleanup EXIT INT TERM
 ok() { pass=$((pass + 1)); printf '  ok   %s\n' "$1"; }
 no() { fail=$((fail + 1)); printf '  FAIL %s\n%s\n' "$1" "${2:-}"; }
 # skill <dir> <name> — a minimal valid skill.
 skill() {
  mkdir -p "$1/$2"
  printf -- '---\nname: %s\ndescription: d\n---\n' "$2" > "$1/$2/SKILL.md"
 }
 # new_fixture <name> [extra-source-names...] — checkout with alpha+beta.
 new_fixture() {
  _f="$WORK/$1"
  mkdir -p "$_f/ck/skills" "$_f/home"
  skill "$_f/ck/skills" alpha
  skill "$_f/ck/skills" beta
  printf '%s' "$_f"
 }
 # run_install <fixture> [extra-sources] — echoes output, sets $rc.
 run_install() {
  _f=$1
  _extra=${2:-}
  _out=$(HOME="$_f/home" \
    SKILLS_SKIP_FETCH=1 \
    SKILLS_CHECKOUT_DIR="$_f/ck" \
    AGENTS_SKILLS_DIR="$_f/home/.agents/skills" \
    CRUSH_SKILLS_DIR="$_f/home/.config/crush/skills" \
    OPENCODE_SKILLS_DIR="$_f/home/.config/opencode/skills" \
    SKILLS_EXTRA_SOURCES="$_extra" \
    bash "$SUT" 2>&1)
  rc=$?
  printf '%s' "$_out"
 }
 # --- 1. the new shape: a real directory of per-skill links -------------------
 f=$(new_fixture fresh)
 out=$(run_install "$f")
 A="$f/home/.agents/skills"
 if [ ! -d "$A" ] || [ -L "$A" ]; then
  no 'agents dir is a real directory' "$out"
 elif [ ! -L "$A/alpha" ] || [ ! -L "$A/beta" ]; then
  no 'each skill is its own link' "$out"
 elif [ ! -L "$f/home/.config/crush/skills" ] || [ ! -L "$f/home/.config/opencode/skills" ]; then
  no 'harnesses keep one directory link each' "$out"
 else
  ok 'fresh install builds per-skill links under a real agents dir'
 fi
 # --- 2. a second source is served WITHOUT displacing the first --------------
 f=$(new_fixture twosource)
 mkdir -p "$f/other"
 skill "$f/other" xlsx
 out=$(run_install "$f" "$f/other")
 if [ -L "$f/home/.agents/skills/xlsx" ] && [ -L "$f/home/.agents/skills/alpha" ]; then
  ok 'a second source is linked alongside the checkout'
 else
  no 'a second source is linked alongside the checkout' "$out"
 fi
 # --- 3. name collisions are REPORTED, never silently resolved ---------------
 # Two sources offering `code-review` is a real possibility, and picking one
 # quietly is how stale content wins.
 f=$(new_fixture collide)
 mkdir -p "$f/other"
 skill "$f/other" alpha
 out=$(run_install "$f" "$f/other")
 if printf '%s' "$out" | grep -qi 'collision' \
   && printf '%s' "$out" | grep -q "$f/other/alpha"; then
  target=$(readlink "$f/home/.agents/skills/alpha")
  if [ "$target" = "$f/ck/skills/alpha" ]; then
    ok 'a name collision is reported and the checkout wins'
  else
    no 'a name collision is reported and the checkout wins' "resolved to $target"
  fi
 else
  no 'a name collision is reported and the checkout wins' "$out"
 fi
 # --- 4. removing a skill from a source removes its link ---------------------
 # Without this the previous generation's problem returns in a new shape: links
 # that resolve to nothing, invisible to git.
 f=$(new_fixture prune)
 out=$(run_install "$f")
 rm -rf "$f/ck/skills/beta"
 out=$(run_install "$f")
 if [ -e "$f/home/.agents/skills/beta" ] || [ -L "$f/home/.agents/skills/beta" ]; then
  no 'a removed skill loses its link' "$out"
 else
  ok 'a removed skill loses its link'
 fi
 # --- 5. migration from the old single-link shape ----------------------------
 f=$(new_fixture migrate)
 mkdir -p "$f/home/.agents"
 ln -s "$f/ck/skills" "$f/home/.agents/skills"
 out=$(run_install "$f")
 if [ -L "$f/home/.agents/skills" ]; then
  no 'the old single-link wiring is migrated in place' "$out"
 elif [ -L "$f/home/.agents/skills/alpha" ]; then
  ok 'the old single-link wiring is migrated in place'
 else
  no 'the old single-link wiring is migrated in place' "$out"
 fi
 # --- 6. unmanaged real content in the agents dir is never deleted -----------
 f=$(new_fixture protect)
 mkdir -p "$f/home/.agents/skills"
 skill "$f/home/.agents/skills" handwritten
 out=$(run_install "$f")
 if [ -f "$f/home/.agents/skills/handwritten/SKILL.md" ] \
   && printf '%s' "$out" | grep -qi 'unmanaged'; then
  ok 'unmanaged content is reported and left in place'
 else
  no 'unmanaged content is reported and left in place' "$out"
 fi
 # --- 7. the source list is recorded for doctor ------------------------------
 f=$(new_fixture manifest)
 mkdir -p "$f/other"
 skill "$f/other" xlsx
 out=$(run_install "$f" "$f/other")
 if [ -f "$f/home/.agents/skills-sources" ] \
   && grep -q "$f/other" "$f/home/.agents/skills-sources" \
   && grep -q "$f/ck/skills" "$f/home/.agents/skills-sources"; then
  ok 'configured sources are recorded for doctor'
 else
  no 'configured sources are recorded for doctor' "$out"
 fi
 printf '\ninstall: %d passed, %d failed\n' "$pass" "$fail"
 [ "$fail" -eq 0 ]
@@ -61,6 +61,17 @@ expect deny 'op read "op://vault/item/field"' 'op read'
 expect deny 'env | grep -i gitea' 'env piped to grep'
 expect deny 'env' 'bare env'
 expect deny 'printenv' 'printenv'
 expect deny 'env -i | grep -i token' 'env -i with no command is still a dump'
 expect deny 'env FOO=bar' 'env with only assignments and no command is a dump'
 # --- allow: `env VAR=x cmd` / `env -u VAR cmd` RUN a command (#25) ---
 # These print nothing themselves; a pipe into grep filters the command's own
 # output, not the environment. Blocking them cost a documented workaround
 # ((unset VAR; cmd)) on the 1Password write path, which is the shape below.
 expect allow 'env -u ANTHROPIC_API_KEY claude --debug -p "ok" 2>&1 | grep -i plugin' 'env -u VAR runs a command'
 expect allow 'env FOO=bar ./script.sh | grep x' 'env VAR=x runs a command'
 expect allow 'env -u OP_SERVICE_ACCOUNT_TOKEN op item create - < item.json' 'env -u on the 1P write path'
 expect deny 'env -u FOO ./run.sh; env | grep -i secret' 'a real dump later in the same line still denies'
 # --- deny: kubernetes secret material ---
 expect deny 'kubectl get secret brain-app -o yaml' 'kubectl get secret -o yaml'
Author	SHA1	Message	Date
mathias	025f01aa80	feat(install): serve several sources instead of displacing them CI / Check / Test (push) Successful in 0s Details CI / Tag release (push) Failing after 1s Details ~/.agents/skills was a single link straight at this checkout. That encoded an assumption nobody had stated — that this checkout is the only source of skills on the host. On flamingo it was not: Crush's directory held Anthropic's official set, and the only way to install this library was to move that set aside. A capability loss dressed up as a tidy-up. The canonical location becomes a real directory of per-skill symlinks, fed by the checkout plus anything in SKILLS_EXTRA_SOURCES. Harnesses keep their one directory link, so the count is N + one per harness rather than N x harnesses, which is what #23 was actually about. The three requirements #27 named, each with a test: - collisions are logged with both paths and the checkout wins, never resolved in silence; - removing a skill from a source prunes its link; - anything in the managed directory that is not our symlink is reported and left in place — the installer does not delete content it did not create. doctor learns the same model: sources are recorded at ~/.agents/skills-sources, a link into a configured source is healthy, a link into an unknown one is not, and the old count check becomes a per-skill check because a per-skill layout can lose one skill without changing any total. The pre-#27 wiring is named as legacy rather than reported as damage. count_skills needed find -L; without it symlinked skill directories count as zero. Verified live on koala: migrated in place to 42 per-skill links, then a second source added a 43rd alongside them, then a re-run without that source pruned it back to 42. Only doctor finding throughout was the genuine stale plugin. Closes #27 Bump-Type: minor	2026-08-29 10:05:46 +02:00
mathias	eee62e4fc0	chore(release): plugin.json version 0.9.0 Skip-Release: true	2026-08-29 08:01:01 +00:00
mathias	a2afb35d1d	feat(doctor): report the installed plugin generation, not just its presence CI / Tag release (push) Successful in 0s Details CI / Check / Test (push) Successful in 1s Details Every other check in doctor is about symlink paths. That is the wrong shape for Claude Code, which has no symlinks — it has the plugin, and it gates updates on plugin.json's version. A host that never picked up a release loads every skill successfully and is simply a generation behind, silently. Found live while writing this: koala had skills@mathias 0.6.0 installed, a marketplace clone at 0.7.0 and a checkout at 0.8.4, and doctor said "clean". doctor now compares the version recorded in installed_plugins.json against the newest manifest already on the host — the active checkout and any marketplace clone, filtered to plugin.json files that actually name this plugin — and fails naming both versions. Offline, like the rest of doctor: "available" never means a fetch. A host with no install record is a valid symlink-only configuration and stays clean. --json grows a "plugin":{"installed","available"} object so per-host results can be collected without parsing prose. Four new fixture cases: match, stale, absent record, newer marketplace clone. Live output on koala: FAIL plugin-version: Claude Code has skills@mathias 0.6.0 installed but 0.8.4 is available on this host Closes #30 Bump-Type: minor	2026-08-29 10:00:11 +02:00
mathias	ad17a7c6c0	chore(release): plugin.json version 0.8.5 Skip-Release: true	2026-08-29 07:56:02 +00:00
mathias	21dbb35526	chore(skills): delete superpowers-test-driven-development CI / Check / Test (push) Successful in 1s Details CI / Tag release (push) Successful in 0s Details Verified duplicate rather than assumed one. Section for section it is the same skill as `tdd` — Overview, When to Use, Iron Law, Red-Green-Refactor with the same dot graph, Good Tests, Common Rationalizations, Red Flags, Verification Checklist, When Stuck, Final Rule — with TypeScript examples and obra's "your human partner" phrasing instead of ours. `tdd` carries all of it plus the Go-specific material (table-driven tests, t.Run, testify, go test -race), the brain MCP integration and the Mode 2 routing note. Its one non-SKILL.md file, testing-anti-patterns.md, is byte-identical to skills/tdd/references/testing-anti-patterns.md, which `tdd` already points at. Nothing was salvageable because nothing was different. No references anywhere outside its own directory except the index row, removed here. `atdd` is untouched — acceptance-level is a genuinely different altitude and it already cross-refs `tdd` correctly. Incidentally the first live catch by bin/check-index (#15): deleting the directory turned `task check` red with "SKILLS_INDEX.md lists 'superpowers-test-driven-development', which has no ...SKILL.md" before I got to the row. 42 skills now. Closes #13 Bump-Type: patch	2026-08-29 09:55:53 +02:00
mathias	8ad2079f86	chore(release): plugin.json version 0.8.4 Skip-Release: true	2026-08-29 07:54:53 +00:00
mathias	b188965161	docs(index): place experiment-spec in the relationships diagram CI / Check / Test (push) Successful in 1s Details CI / Tag release (push) Successful in 1s Details Missed in `83b069a`. #15 asked for three things and the table row was only two of them: experiment-spec also belongs in the Skill Relationships tree, parallel to feature-spec and downstream of spec-driven-dev, since it is the research/ML substitute for feature-spec rather than a separate lifecycle. dream needs no edge, same as trainer and session-retrospective — the issue said so and that part was right. Refs #15 Bump-Type: patch	2026-08-29 09:54:23 +02:00
mathias	ae66840a03	chore(release): plugin.json version 0.8.3 Skip-Release: true	2026-08-29 07:53:48 +00:00
mathias	e7e514390b	docs(web-shot): resolve shot.sh from the install, not a checkout path CI / Check / Test (push) Successful in 1s Details CI / Tag release (push) Successful in 1s Details The usage block pointed at ~/dev/.skills/web-shot/shot.sh four times. That directory has not existed since the skills moved into this repo, and the failure mode is worse than a broken link: web-shot exists for agents with no local browser, so a 404 sends them to hand-roll the Job instead of looking harder. One caller burned three attempts on playwright module resolution before finding the script that documents that exact gotcha. Replaced with a resolution line covering both delivery paths — the Claude Code plugin and the ~/.agents/skills symlink — so no absolute checkout path is left to rot. Verified on koala: resolves to the .agents link, and degrades to an empty string plus a clear message where the skill is not installed. The brain entry headless-browser-via-k3s-playwright-job carried the same stale path in three places and referenced the retired wire-skills.sh wiring; updated to match. Closes #26 Bump-Type: patch	2026-08-29 09:53:33 +02:00
mathias	087685f2e3	chore(release): plugin.json version 0.8.2 Skip-Release: true	2026-08-29 07:52:16 +00:00
mathias	83b069afba	docs(index): add dream + experiment-spec rows, and gate the index CI / Check / Test (push) Successful in 0s Details CI / Tag release (push) Successful in 1s Details Both skills shipped without an index row. The rows existed — on the feature branches deleted in #22 — and were dropped by the squash-merge that followed a directory reorg: the SKILL.md landed under skills/, the row did not. Nothing errored, the index just under-reported the library to every harness reading it. Adding two rows by hand fixes today and not tomorrow, so the assertion goes in `task check` via bin/check-index, following the same pattern as bin/should-skip-release: a real script with a real test, not untested logic buried in a Taskfile. It checks both directions — a skill with no row, and a row naming a skill that no longer exists. Verified by mutation: deleting the `dream` row turns `task check` red and the report names it. Closes #15 Bump-Type: patch	2026-08-29 09:52:03 +02:00
mathias	a699ad8cbd	chore(release): plugin.json version 0.8.1 Skip-Release: true	2026-08-29 07:50:52 +00:00
mathias	a42ec18f40	fix(secret-guard): treat `env` as a dump only when no command follows CI / Tag release (push) Successful in 1s Details CI / Check / Test (push) Successful in 1s Details `env -u VAR cmd` and `env FOO=bar cmd` exec a command with a modified environment and print nothing themselves. The old rule matched any `env` token followed anywhere later by a pipe into a filter, so it blocked the documented 1Password write path and forced a `(unset VAR; cmd)` workaround. False positives only — never a leak — but a guard people route around is a guard on its way out. The rule now denies only when everything after `env` is exhausted by options and VAR=value assignments. That is strictly the dumping shape, and it also closes a hole the two previous rules left open: `env FOO=bar` with no command word prints the whole environment and was allowed. Three new deny/allow pairs pin it, including the 1Password write shape that motivated the report. 20 cases now, up from 14, all passing. Closes #25 Bump-Type: patch	2026-08-29 09:50:08 +02:00
mathias	46ff1acdfe	chore(release): plugin.json version 0.8.0 Skip-Release: true	2026-08-29 07:47:07 +00:00
mathias	3112b4ce92	chore(ci): gate the release tagger on check + test CI / Check / Test (push) Successful in 0s Details CI / Tag release (push) Successful in 0s Details The repo had a `task check` structure gate and a 28-case shell test suite that nothing ever ran. The only workflow auto-tagged every push to main, so CI reported green having tested nothing — a gate that fails open, and the reason `mathias/skills` shows up as repository-blocked in the estate backlog classification. release.yml becomes ci.yml with two jobs: `gate` runs check + test on every push and PR; `tag` keeps the existing semver-from-trailer logic but declares `needs: gate`, so a red check cannot ship a tag. The pull_request trigger also gives `tbd_ship` a CI run to read on a branch head — without one it fails closed and never merges (#22). The tagger now pushes the manifest bump commit and the tag in a single `git push`. Two pushes left a window where the gate ran `task check` on the bump commit before the tag existed, and the manifest/tag parity assertion would fail on a commit that was in fact correct. tests/ci_gate_test.sh pins the wiring: PR trigger present, both tasks run, tag needs gate, no second ungated workflow file. Refs: #22 Bump-Type: minor	2026-08-29 09:46:10 +02:00
mathias	51a8c25b4d	chore(release): plugin.json version 0.7.0 Skip-Release: true	2026-08-28 11:09:50 +00:00
mathiasandClaude Sonnet 5	d40169f2b7	feat(skill): cad-babysit — human-in-the-loop session over cad-stuck (skills#31) release / tag (push) Successful in 1s Details Wraps mathias/cad#14's `cad stuck` query surface: five-phase diagnostic order (re-derive the worklist, read issue comments FIRST, then Actions job logs, separate infrastructure fault from task outcome, decide-or-say DECISION-NEEDED), read-only by Iron Law — no dispatch, no label writes, no issue close. Every diagnosis cites a locator; every operator-only call surfaces as a structured DECISION NEEDED block instead of being decided for them. Built after cad#14 passed its live-estate acceptance test (7 real findings, locators verified) — the skill is the ritual around a query already proven to produce actionable rows, not a checklist with no input. Bump-Type: minor Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>	2026-08-28 13:09:31 +02:00
mathias	d4f0416dc5	chore(release): plugin.json version 0.6.3 Skip-Release: true	2026-08-26 05:54:12 +00:00
mathiasandClaude Opus 5	abd81f939a	fix(doctor): report a real harness directory as unmanaged, not as "outside" release / tag (push) Successful in 1s Details Found on flamingo during the first Mac install. ~/.config/crush/skills held real directories from a pre-plugin install, and doctor said: FAIL outside: ~/.config/crush/skills resolves to ~/.config/crush/skills, outside the active checkout ~/.local/share/skills/skills Naming a directory as its own resolution target is true and useless. Worse, it pointed at the wrong fix: "outside" means a link into a foreign checkout, which you repair by re-pointing the link. A real directory is repaired by moving it aside and re-running install.sh — install.sh already refuses to delete it, correctly, since it did not create it and cannot know what is in there. Now reported as its own class, with the skill count so it is obvious whether the directory holds a stale copy of the library or something unique that belongs in the repo: FAIL unmanaged: <dir> is a real directory, not a link into the checkout — it holds N unmanaged skill(s); move it aside and re-run install.sh The distinction matters because content in that directory reaches exactly one harness and cannot receive new skills — the failure mode is silent divergence, which is the same family as everything else this tool exists to catch. Bump-Type: patch Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01BeAp5LTscnz2W7Ubt4eJ6m	2026-08-26 07:53:14 +02:00
mathias	e42d2ba9cb	chore(release): plugin.json version 0.6.2 Skip-Release: true	2026-08-25 08:54:05 +00:00
mathiasandClaude Opus 5	68cebc0bbb	fix(gitea-ci): hand out the call, not a copy of the build implementation (infra#309) release / tag (push) Successful in 1s Details This skill is the third factory. Two repo templates were fixed when the buildah->buildctl migration went through, and this one kept handing out the broken step for weeks afterwards -- because it is what gets consulted when adding CI to an EXISTING repo, which the templates never touch. Pasting an implementation is the actual defect. The estate now has one (mathias/infra ci-templates/build-image.sh) with byte-identical copies held in place by a drift gate, so the skill teaches the four adoption steps and the input list instead of a block to copy. Step 1 of those four -- registering in adopters.txt -- is called out explicitly, because a copy nobody registered works today and falls silently behind on the next canonical change. That is the failure this whole issue exists to end. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_011PL5XcG68SvQqz3vGVbWbf	2026-08-25 10:54:02 +02:00