@spardutti/claude-skills 2.34.0 → 2.36.0

package/README.md

@@ -131,7 +131,7 @@ Portable slash commands installed to `.claude/commands/`. Some orchestrate paral
 
 | Command | What it does |
 |---------|--------------|
-| `/ship` | Unified delivery pipeline — commit → gate → PR → merge → release. The gate is the one enforcement moment: it checks the diff's file lengths, audits it against the skills installed in the project, and mutation-tests the changed lines to prove the tests would catch a break — **fixing what it finds** rather than handing you a list. It runs before the **PR**, not before every commit: its scope is the whole branch, so gating each commit re-mutated every file the branch had ever touched. `--force` skips it. No argument steps through interactively; `/ship pr` runs through PR creation; `/ship release` runs the full pipeline |
+| `/ship` | Unified delivery pipeline — commit → gate → PR → merge → release. The gate is the one enforcement moment: it checks the diff's file lengths and that new files sit in their kind folder, audits it against the skills installed in the project, and mutation-tests the changed lines to prove the tests would catch a break — **fixing what it finds** rather than handing you a list. It runs before the **PR**, not before every commit: its scope is the whole branch, so gating each commit re-mutated every file the branch had ever touched. `--force` skips it. No argument steps through interactively; `/ship pr` runs through PR creation; `/ship release` runs the full pipeline |
 | `/discover` | Find the right problem before deciding what to build — diverges first: generates competing framings through blind subagents under forced constraints, stress-tests the winner with a blind critic, and refuses to converge until every open question is answered or deferred, then drafts scope, non-goals, edge cases and success criteria for you to correct. Run before `/plan-feature` |
 | `/plan-feature` | Integration-first feature planning, then building — 3 parallel subagents scan for reusable code, patterns and touch points, grounded clarifying questions follow, and on your go the same agent builds the plan |
 | `/refactor` | Detect size / complexity / duplication / coupling issues via 4 parallel subagents, then refactor |
@@ -191,7 +191,7 @@ commands/      Slash commands installed to .claude/commands/
 agents/        Subagent definitions — commands declare which they need via requires-agents
 scripts/       validate-skills.mjs — checks skill length caps and reference integrity
                gauntlet.sh — the Stop-hook verification gates, embedded by the CLI
-               ship-gate.sh — /ship's file-length and mutation checks, behind an exit code
+               ship-gate.sh — /ship's file-length, folder-structure and mutation checks, behind an exit code
                ship-gate-hook.sh — refuses gh pr create/merge without a ship-gate receipt
                version-check.sh — SessionStart nudge when a newer catalog is published
                gauntlet-selftest.sh — behavioural tests for the hooks (runs on pre-push)

package/hooks/ship-gate-projects.sh

@@ -105,3 +105,17 @@ project_key() {  # project_key <owner> <tool>
       case "$(family_of "$f")" in "$fam"|any) printf '%s\n' "$f"; [ -f "$f" ] && cat "$f" ;; esac
     done; } | git hash-object --stdin
 }
+
+# A page test renders a whole screen, so it "kills" mutants in every util that screen calls.
+# Backoffice ran 23 minutes that way, and hid 104 mutants no logic test checked.
+stryker_page_tests() {  # stryker_page_tests <base> <label>
+  grep -qs configFile "$1"stryker.conf* && return 0
+  pages=$(git ls-files -co --exclude-standard -- "${1:-.}" | grep -E '\.test\.[jt]sx$' \
+          | grep -vE '/(hooks|queries)/|(^|/)\.stryker-tmp/' | head -3)
+  [ -n "$pages" ] || return 0
+  echo "  $2 stryker — UNPROVEN: page tests count as proof for logic, e.g."
+  printf '%s\n' "$pages" | sed 's/^/        /'
+  echo "      Give Stryker a Vitest config that runs logic tests only — see"
+  echo "      testing-best-practices/MUTATION-TESTING.md, \"Keep Page Tests Out Of The Run\"."
+  [ "$STATUS" = 0 ] && STATUS=2
+}

package/hooks/ship-gate-structure.sh

@@ -0,0 +1,103 @@
+#!/usr/bin/env bash
+# Sourced by ship-gate.sh: a new file must sit in the folder named for its kind.
+# Only ADDED files are judged, so a repo laid out the old way cannot get worse and need not move.
+
+STRUCTURE_JS_KINDS="components|hooks|api|queries|schemas|types|utils|stores|test"
+STRUCTURE_KIND_FILE='(^|[._])(router|routes|controller|service|schema|model)s?\.[cm]?[jt]s$|(Router|Routes|Controller|Service|Schema|Model)s?\.[cm]?[jt]s$'
+
+# --no-renames: a move must show up as an add, or renaming a misplaced file would slip through.
+added_files() {
+  { git diff --no-renames --diff-filter=A --name-only "$BASE"...HEAD 2>/dev/null
+    git diff --no-renames --diff-filter=A --name-only HEAD 2>/dev/null
+    git ls-files --others --exclude-standard 2>/dev/null; } | sort -u
+}
+
+has_subject() {  # has_subject <test path>: a file the test is named for, beside it or above its __tests__/
+  d=$(dirname "$1")
+  [ "${d##*/}" = __tests__ ] && d=$(dirname "$d")
+  stem=$(basename "$1" | sed -E 's/\.(test|spec)\.[^.]+$//')
+  while :; do
+    for e in ts tsx js jsx mjs cjs astro; do [ -f "$d/$stem.$e" ] && return 0; done
+    case "$stem" in *.*) stem=${stem%.*} ;; *) return 1 ;; esac
+  done
+}
+
+feature_misplaced() {  # feature_misplaced <path below features/<name>/>
+  case "$1" in
+    index.*) ;;
+    */*) printf '%s' "${1%%/*}" | grep -qxE "$STRUCTURE_JS_KINDS" \
+           || echo "${1%%/*}/ is not a kind folder ($STRUCTURE_JS_KINDS)" ;;
+    *) echo "loose at the feature root, where only index.* belongs" ;;
+  esac
+}
+
+js_misplaced() {  # js_misplaced <path> <owner>
+  f=$1; b=${f##*/}; parent=$(basename "$(dirname "$f")")
+  if printf '%s' "$b" | grep -qE '\.(test|spec)\.[^.]+$'; then
+    printf '%s' "/$f" | grep -qE '/(e2e|tests?)/' && return
+    has_subject "$f" || echo "a test sits beside the file it tests, and nothing here is named ${b%%.*}"
+    return
+  fi
+  rest=$(printf '%s' "/$f" | sed -nE 's#.*/features/[^/]+/##p')
+  if [ -n "$rest" ]; then feature_misplaced "$rest"; return; fi
+  kinds="components|hooks|queries|api|schemas|types|utils"
+  grep -qs '"express"' "$2/package.json" && kinds="$kinds|routes|controllers|services|middleware|models"
+  if printf '%s' "/$f" | grep -qE "/src/($kinds)/"; then
+    echo "sorted by kind first; it belongs in <domain>/<kind>/ or shared/<kind>/"
+  elif printf '%s' "$b" | grep -qE '^use[A-Z].*\.[jt]sx?$' && ! printf '%s' "/$f" | grep -qE '/(hooks|queries)/'; then
+    echo "a hook belongs in hooks/ or queries/"
+  elif printf '%s' "$b" | grep -qE "$STRUCTURE_KIND_FILE" \
+       && ! printf '%s' "$parent" | grep -qxE 'routes|controllers|services|schemas|models|api|queries|types'; then
+    echo "the kind is in the filename; it belongs in a kind folder"
+  fi
+}
+
+py_misplaced() {  # py_misplaced <path>
+  f=$1; b=${f##*/}; d=$(dirname "$f"); parent=${d##*/}
+  case "$b" in
+    test_*.py|*_test.py|conftest.py)
+      printf '%s' "/$f" | grep -qE '/tests/' || echo "tests live under tests/, mirroring the app"
+      return ;;
+  esac
+  k=$(printf '%s' "$b" | sed -nE 's/^(.*_)?(router|service|schema|model)s?\.py$/\2/p')
+  if [ -n "$k" ] && [ "$parent" != "${k}s" ]; then
+    echo "the kind is in the filename; it belongs in ${k}s/"
+  elif printf '%s' "$parent" | grep -qxE 'routers|services|schemas|models' && [ -f "$(dirname "$d")/main.py" ]; then
+    echo "sorted by kind first; it belongs in <domain>/$parent/"
+  fi
+}
+
+structure_check() {
+  bad=""; count=0
+  while IFS= read -r f; do
+    [ -f "$f" ] && ! is_ignored "$f" || continue
+    printf '%s' "/$f" | grep -qE '/(node_modules|\.stryker-tmp|mutants)/' && continue
+    o=$(owner_of "$f")
+    case "$f" in
+      *.ts|*.tsx|*.js|*.jsx|*.mjs|*.cjs|*.astro) why=$(js_misplaced "$f" "$o") ;;
+      *.py) grep -qis fastapi "$o/pyproject.toml" || continue; why=$(py_misplaced "$f") ;;
+      *) continue ;;
+    esac
+    count=$((count+1))
+    [ -n "$why" ] && bad="$bad  $f — $why
+"
+  done <<< "$(added_files)"
+  echo
+  if [ -n "$bad" ]; then
+    echo "STRUCTURE — new files outside their kind folder:"
+    printf '%s' "$bad"
+    echo "  Move them (Project Structure in the react, fastapi or express skill), or ship with --force."
+    echo
+    return 1
+  fi
+  echo "STRUCTURE — ok, $count new file(s) in their kind folder"
+  echo
+}
+
+# Called when nothing else in the diff is gated, so the gate would otherwise pass it.
+structure_fail() {
+  echo "ship-gate: FAIL — deal with the findings above, then run this again."
+  echo "           To ship anyway: bash .claude/hooks/ship-gate.sh --force"
+  rm -f "$RECEIPT"
+  exit 1
+}

package/hooks/ship-gate.sh

@@ -25,8 +25,8 @@
 # Exit codes:
 #   0  clean — nothing over the line limit, nothing survived, nothing uncovered
 #   1  findings that must be dealt with before shipping
-#   2  ran, but could not prove the tests (a mutation tool is missing) — report,
-#      don't block; the output names exactly what to install and where
+#   2  ran, but could not prove the tests (a mutation tool is missing, or page tests
+#      count as proof) — report, don't block; the output names the fix and where
 #
 # Config: the same .claude/gauntlet.conf as the Stop hook.
 #   GAUNTLET_MAX_LINES=200   the per-file limit; 0 turns the check off
@@ -46,7 +46,7 @@
 set -uo pipefail
 
 HERE=$(cd "$(dirname "$0")" && pwd)
-. "$HERE/ship-gate-projects.sh" || { echo "ship-gate: cannot read $HERE/ship-gate-projects.sh"; exit 1; }
+. "$HERE/ship-gate-projects.sh" && . "$HERE/ship-gate-structure.sh" || { echo "ship-gate: cannot read its helpers in $HERE"; exit 1; }
 
 MODE=""
 case "${1:-}" in
@@ -76,7 +76,7 @@ GAUNTLET_MAX_LINES=200
 GAUNTLET_MUTATE=""
 GAUNTLET_SOURCE_EXT="ts|tsx|js|jsx|mjs|cjs|py|go|rs|java|kt|rb|php|c|h|cpp|hpp|cs|swift|gd"
 GAUNTLET_IGNORE_EXT="md|mdx|txt|rst|adoc|jsonc?|ya?ml|toml|lock|cfg|ini|env|csv|tsv|sql|html|css|scss|svg|png|jpg|jpeg|gif|webp|ico|pdf|woff2?|ttf|otf|mp3|mp4|wav|zip|gz|tres|tscn|import|godot"
-GAUNTLET_IGNORE_FILES="*.gen.ts *.gen.tsx *.generated.* */migrations/*.py */alembic/versions/*.py */components/ui/*.tsx */*.config.*"
+GAUNTLET_IGNORE_FILES="*.gen.ts *.gen.tsx *.generated.* */migrations/*.py */alembic/versions/*.py */components/ui/*.tsx */hooks/use-mobile.ts */*.config.*"
 # Length-checked and skill-audited like everything else, but not mutated.
 # Mutation pays on logic and burns time on presentation: a component's mutants
 # are class names, copy and JSX shape, none of which is behaviour, and one
@@ -159,6 +159,8 @@ if [ -n "$IGNORED" ]; then
   printf '%s\n' "$IGNORED" | sed 's/^/  /'
 fi
 
+[ -n "$FILES" ] && echo "ship-gate: $(printf '%s\n' "$FILES" | wc -l) changed code file(s), base $(git rev-parse --short "$BASE")"
+STATUS=0; structure_check || { STATUS=1; [ -z "$FILES" ] && structure_fail; }
 if [ -z "$FILES" ]; then
   # "I recognised nothing" is not "there is nothing", and the gate used to report
   # both as a PASS. A Godot repo changed only .gd files, which no extension in
@@ -183,10 +185,6 @@ if [ -z "$FILES" ]; then
   exit 0
 fi
 
-echo "ship-gate: $(printf '%s\n' "$FILES" | wc -l) changed code file(s), base $(git rev-parse --short "$BASE")"
-echo
-STATUS=0
-
 # ------------------------------------------------- check 1: file length (hard)
 OVER=""
 LARGEST=0
@@ -273,7 +271,7 @@ for owner in $OWNERS; do
     # 8 of them on one commit, all long since killed. --mutate already scopes
     # the run to the changed hunks, so incremental buys nothing here and costs
     # a cache that goes stale exactly the way mutmut's did.
-    CMD="${RUN}npx --no-install stryker run --mutate '${FLAGS#,}'"
+    CMD="${RUN}npx --no-install stryker run --mutate '${FLAGS#,}'"; stryker_page_tests "$base" "$label"
   elif [ -f "$base"package.json ]; then
     MISSING="$MISSING  $label needs Stryker:
       npm --prefix ${owner} i -D @stryker-mutator/core @stryker-mutator/vitest-runner

package/lib/setup-hook.mjs

@@ -27,6 +27,7 @@ const APPLICATION_GATE_FILENAME = "skill-application-gate.sh";
 const GAUNTLET_FILENAME = "gauntlet.sh";
 const SHIP_GATE_FILENAME = "ship-gate.sh";
 const SHIP_GATE_PROJECTS_FILENAME = "ship-gate-projects.sh";
+const SHIP_GATE_STRUCTURE_FILENAME = "ship-gate-structure.sh";
 const SHIP_GATE_HOOK_FILENAME = "ship-gate-hook.sh";
 const VERSION_CHECK_FILENAME = "version-check.sh";
 const LEGACY_EVAL_FILENAME = "skill-forced-eval-hook.sh";
@@ -106,6 +107,7 @@ export async function setupHook(targetDir = process.cwd()) {
     GAUNTLET_FILENAME,
     SHIP_GATE_FILENAME,
     SHIP_GATE_PROJECTS_FILENAME,
+    SHIP_GATE_STRUCTURE_FILENAME,
     SHIP_GATE_HOOK_FILENAME,
     VERSION_CHECK_FILENAME,
   ]) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spardutti/claude-skills",
-  "version": "2.34.0",
+  "version": "2.36.0",
   "description": "Guardrails for Claude Code — best-practice skills, planning commands, and delivery gates.",
   "type": "module",
   "repository": {
@@ -11,7 +11,7 @@
     "claude-skills": "bin/cli.mjs"
   },
   "scripts": {
-    "prepack": "cp ../README.md README.md && mkdir -p hooks && cp ../scripts/skill-gate.sh ../scripts/skill-gate-automark.sh ../scripts/skill-application-gate.sh ../scripts/gauntlet.sh ../scripts/ship-gate.sh ../scripts/ship-gate-projects.sh ../scripts/ship-gate-hook.sh ../scripts/version-check.sh hooks/",
+    "prepack": "cp ../README.md README.md && mkdir -p hooks && cp ../scripts/skill-gate.sh ../scripts/skill-gate-automark.sh ../scripts/skill-application-gate.sh ../scripts/gauntlet.sh ../scripts/ship-gate.sh ../scripts/ship-gate-projects.sh ../scripts/ship-gate-structure.sh ../scripts/ship-gate-hook.sh ../scripts/version-check.sh hooks/",
     "postpack": "git checkout -- README.md && rm -rf hooks"
   },
   "engines": {