start-vibing 4.2.0 → 4.3.1

package/template/.claude/skills/super-design/scripts/detect-changes.sh

@@ -1,30 +1,122 @@
 #!/usr/bin/env bash
 # Usage: detect-changes.sh <last_sha> [<last_iso>]
 # Emits JSON: { mode, range_start, commits, files, classified }
+#
+# Implements the fallback ladder from artifact §6 + §14:
+#   1. Anchor exists → diff with rename detection (-M90%).
+#   2. Anchor missing + shallow repo → `git fetch --unshallow --no-tags`.
+#   3. Still missing → fetch super-design git notes, retry.
+#   4. Still missing → `--since=<iso>` time-based fallback.
+#   5. Empty repo / no last_sha at all → diff against empty-tree SHA
+#      4b825dc642cb6eb9a060e54bf8d69288fbee4904 (artifact line 900).
+# Also uses --first-parent + --cherry-pick --right-only when walking
+# history (artifact §2.5 line 167-172).
 set -euo pipefail
 
 LAST_SHA="${1:-}"
 LAST_ISO="${2:-}"
+EMPTY_TREE="4b825dc642cb6eb9a060e54bf8d69288fbee4904"
+
+log() { printf '[detect-changes] %s\n' "$*" >&2; }
 
-if [[ -z "$LAST_SHA" ]]; then echo '{"error":"missing last_sha"}'; exit 2; fi
 if ! git rev-parse --git-dir >/dev/null 2>&1; then echo '{"error":"not-a-git-repo"}'; exit 3; fi
 
-if git rev-parse --verify --quiet "${LAST_SHA}^{commit}" >/dev/null; then
-  if git merge-base --is-ancestor "$LAST_SHA" HEAD; then RANGE_START="$LAST_SHA"
-  else RANGE_START="$(git merge-base HEAD "$LAST_SHA" 2>/dev/null || echo "")"; fi
-else RANGE_START=""; fi
-
-if [[ -z "$RANGE_START" ]]; then
-  if [[ -n "$LAST_ISO" ]]; then
-    FILES="$(git log --since="$LAST_ISO" --name-only --pretty=format: 2>/dev/null | sort -u | sed '/^$/d' || true)"
-    COMMITS="$(git log --since="$LAST_ISO" --pretty=format:'%H|%s|%an|%aI' 2>/dev/null || true)"
-    MODE="since-time"
-  else echo '{"error":"lost-anchor-no-fallback-time"}'; exit 4; fi
+# Determine HEAD availability — empty repos have no commits at all.
+if ! git rev-parse --verify --quiet HEAD >/dev/null; then
+  log "no HEAD commit; using empty-tree SHA fallback"
+  LAST_SHA="$EMPTY_TREE"
+fi
+
+# If caller didn't pass a last_sha, treat it as empty-tree (first audit).
+if [[ -z "$LAST_SHA" ]]; then
+  log "missing last_sha; defaulting to empty-tree SHA"
+  LAST_SHA="$EMPTY_TREE"
+fi
+
+resolve_anchor() {
+  # Sets RANGE_START (may be empty if anchor unrecoverable).
+  if [[ "$LAST_SHA" == "$EMPTY_TREE" ]]; then
+    RANGE_START="$EMPTY_TREE"; return 0
+  fi
+  if git rev-parse --verify --quiet "${LAST_SHA}^{commit}" >/dev/null; then
+    if git merge-base --is-ancestor "$LAST_SHA" HEAD 2>/dev/null; then
+      RANGE_START="$LAST_SHA"
+    else
+      RANGE_START="$(git merge-base HEAD "$LAST_SHA" 2>/dev/null || echo "")"
+    fi
+    return 0
+  fi
+  RANGE_START=""
+  return 1
+}
+
+if ! resolve_anchor; then
+  # Ladder step (a): unshallow if possible.
+  if [[ "$(git rev-parse --is-shallow-repository 2>/dev/null || echo false)" == "true" ]]; then
+    log "anchor missing and repo is shallow; attempting git fetch --unshallow --no-tags"
+    git fetch --unshallow --no-tags 2>/dev/null || log "unshallow fetch failed (continuing)"
+    resolve_anchor || true
+  fi
+fi
+if [[ -z "${RANGE_START:-}" ]]; then
+  # Ladder step (b): try to fetch super-design notes; they may pin a commit
+  # we don't have locally.
+  log "anchor still missing; fetching refs/notes/super-design"
+  git fetch origin '+refs/notes/super-design:refs/notes/super-design' 2>/dev/null \
+    || log "notes fetch failed (continuing)"
+  resolve_anchor || true
+fi
+
+# Ladder step (c): time-based fallback.
+if [[ -z "${RANGE_START:-}" && -n "$LAST_ISO" ]]; then
+  log "using --since=$LAST_ISO time-based fallback"
+  FILES="$(git log --since="$LAST_ISO" --name-only --pretty=format: 2>/dev/null | sort -u | sed '/^$/d' || true)"
+  COMMITS="$(git log --first-parent --since="$LAST_ISO" --pretty=format:'%H|%s|%an|%aI' 2>/dev/null || true)"
+  MODE="since-time"
+  RANGE_START=""
+elif [[ -z "${RANGE_START:-}" ]]; then
+  echo '{"error":"lost-anchor-no-fallback-time"}'; exit 4
 else
-  FILES="$(git diff --name-only "${RANGE_START}..HEAD" \
-    -- ':!*.lock' ':!package-lock.json' ':!pnpm-lock.yaml' ':!yarn.lock' \
-       ':!.github/**' ':!**/*.test.*' ':!**/*.spec.*' ':!**/*.stories.*' | sort -u)"
-  COMMITS="$(git log --no-merges --pretty=format:'%H|%s|%an|%aI' "${RANGE_START}..HEAD" 2>/dev/null || true)"
+  # SHA range available. Use --name-status -M90% -z to catch renames AND
+  # filenames with spaces (NUL-terminated output).
+  RANGE="${RANGE_START}..HEAD"
+  if [[ "$RANGE_START" == "$EMPTY_TREE" ]]; then
+    # Empty-tree baseline: everything in HEAD is "new".
+    RANGE="${EMPTY_TREE} HEAD"
+  fi
+
+  # Parse NUL-terminated name-status output.
+  # Format: <STATUS>\0<path>[\0<new_path>]  where STATUS can be A/M/D/Rnn/Cnn.
+  # We collapse to the post-rename path so downstream classification matches
+  # the current file layout.
+  FILES="$(
+    git diff --name-status -M90% -z \
+      -- . ':!*.lock' ':!package-lock.json' ':!pnpm-lock.yaml' ':!yarn.lock' \
+         ':!.github/**' ':!**/*.test.*' ':!**/*.spec.*' ':!**/*.stories.*' \
+      $RANGE 2>/dev/null |
+    awk -v RS='\0' '
+      BEGIN { status = "" }
+      {
+        if (status == "") { status = $0; next }
+        # Rename/copy has two path fields; we want the second (post-rename).
+        if (status ~ /^R/ || status ~ /^C/) {
+          if (wanted == "") { wanted = 1; next }
+          print; status = ""; wanted = ""
+        } else {
+          print; status = ""
+        }
+      }
+    ' | sort -u
+  )"
+
+  # --first-parent keeps one entry per merged PR (trunk-based). Combine
+  # with --cherry-pick --right-only to dedupe back-ports / rebased copies.
+  if [[ "$RANGE_START" == "$EMPTY_TREE" ]]; then
+    COMMITS="$(git log --first-parent --pretty=format:'%H|%s|%an|%aI' HEAD 2>/dev/null || true)"
+  else
+    COMMITS="$(git log --first-parent --cherry-pick --right-only --no-merges \
+      --pretty=format:'%H|%s|%an|%aI' "${RANGE_START}...HEAD" 2>/dev/null || true)"
+  fi
   MODE="sha-range"
 fi
 
@@ -32,7 +124,7 @@ declare -A CLASSIFIED
 while IFS= read -r p; do
   [[ -z "$p" ]] && continue
   case "$p" in
-    tailwind.config.*|*.tokens.json|styles/tokens.css|styles/theme.css) CLASSIFIED[tokens]+="$p,";;
+    tailwind.config.*|*.tokens.json|*.tokens|styles/tokens.css|styles/theme.css) CLASSIFIED[tokens]+="$p,";;
     components/*|src/components/*|app/_components/*) CLASSIFIED[components]+="$p,";;
     app/*/page.*|app/page.*|app/*/route.*|app/route.*|pages/*|src/pages/*|app/routes/*|src/routes/*) CLASSIFIED[routes]+="$p,";;
     public/*|src/assets/*|assets/*) CLASSIFIED[imagery]+="$p,";;
@@ -43,7 +135,7 @@ while IFS= read -r p; do
   esac
 done <<< "$FILES"
 
-jq -Rn --arg mode "$MODE" --arg range_start "$RANGE_START" --arg last_iso "$LAST_ISO" \
+jq -Rn --arg mode "$MODE" --arg range_start "${RANGE_START:-}" --arg last_iso "$LAST_ISO" \
   --arg tokens "${CLASSIFIED[tokens]:-}" --arg components "${CLASSIFIED[components]:-}" \
   --arg routes "${CLASSIFIED[routes]:-}" --arg imagery "${CLASSIFIED[imagery]:-}" \
   --arg deps "${CLASSIFIED[deps]:-}" --arg theory "${CLASSIFIED[theory]:-}" \
@@ -59,3 +151,6 @@ jq -Rn --arg mode "$MODE" --arg range_start "$RANGE_START" --arg last_iso "$LAST
      deps: tolist($deps), theory: tolist($theory), content: tolist($content)
    }
   }'
+
+# TODO(sd-audit-state §11/artifact line 902): monorepo per-app state
+#   (apps/*/docs/super-design/.audit-state.json) not yet supported.

package/template/.claude/skills/super-design/scripts/discover-routes.sh

@@ -1,4 +1,11 @@
 #!/usr/bin/env bash
+# TODO(sd-audit-state artifact §14): dynamic routes like `/posts/[slug]`
+#   should be expanded to `/posts/@fixture-<id>` using a fixtures manifest
+#   (discovered from tests or a user-configured JSON) before being passed
+#   to hash-pages/sd-audit. Current impl emits the raw pattern.
+# TODO(sd-audit-state artifact §8): madge-based import-graph builder
+#   (`madge --json --ts-config tsconfig.json src`) to compute N-hop
+#   component → page blast radius. Expected alongside this script.
 set -euo pipefail
 
 detect_framework() {

package/template/.claude/skills/super-design/scripts/extract-tokens.mjs

@@ -1,6 +1,11 @@
 #!/usr/bin/env node
+// Extract + canonicalize + hash design tokens from Tailwind configs and
+// CSS custom properties. Output is deterministic regardless of insertion
+// order (artifact §9.2 line 722: "canonical = JSON.stringify(theme,
+// Object.keys(theme).sort())").
 import fs from "node:fs";
 import path from "node:path";
+import { createHash } from "node:crypto";
 import { pathToFileURL } from "node:url";
 
 const out = {};
@@ -28,12 +33,24 @@ try {
   }
 } catch (e) { out._postcss_error = String(e.message || e); }
 
-console.log(JSON.stringify(out, null, 2));
+// TODO(sd-audit-state §9.1 artifact line 707-709): DTCG *.tokens.json and
+// Tokens Studio support — parse JSON, resolve `{alias}` refs per §9.2 line
+// 747 before hashing, then merge into `out` with prefix `dtcg:`.
+
+// Deterministic canonical form: keys sorted top-to-bottom.
+const sorted = Object.keys(out).sort().reduce((acc, k) => { acc[k] = out[k]; return acc; }, {});
+const canonical = JSON.stringify(sorted);
+const tokens_hash = "sha256:" + createHash("sha256").update(canonical).digest("hex");
+
+console.log(JSON.stringify({ tokens: sorted, tokens_hash }, null, 2));
 
 function flatten(obj, prefix, acc) {
   if (obj == null) return;
   if (typeof obj !== "object") { acc[prefix] = String(obj); return; }
-  for (const [k, v] of Object.entries(obj)) {
+  // Sort keys so hash is stable across JS engines / config formatters.
+  // Artifact §9.2 line 722 calls this out explicitly.
+  for (const k of Object.keys(obj).sort()) {
+    const v = obj[k];
     const key = `${prefix}.${k}`;
     if (v && typeof v === "object" && !Array.isArray(v)) flatten(v, key, acc);
     else acc[key] = Array.isArray(v) ? v.join(",") : String(v);

package/template/.claude/skills/super-design/scripts/hash-pages.sh

@@ -1,5 +1,11 @@
 #!/usr/bin/env bash
 # Usage: hash-pages.sh <urls_file>
+#
+# TODO(sd-audit-state artifact §10 line 492, §16 line 1367-1384):
+#   Per-viewport hashes (mobile_375 / tablet_768 / desktop_1280) + pHash
+#   for perceptual similarity, plus mask_selectors passed to
+#   page.screenshot({ mask: [...] }) for deterministic diffs. Current impl
+#   hashes a single desktop viewport only.
 set -euo pipefail
 URLS="${1:?usage: hash-pages.sh <urls_file>}"
 OUT_DIR="${OUT_DIR:-docs/super-design/.cache/hashes}"

package/template/.claude/skills/super-design/scripts/setup-git-notes.sh

@@ -0,0 +1,21 @@
+#!/usr/bin/env bash
+# Usage: setup-git-notes.sh
+#
+# One-shot setup so `git notes --ref=super-design` round-trips across
+# clones. Without the remote refspec, git fetch ignores notes by default
+# (artifact §7 line 570-573).
+set -euo pipefail
+
+if ! git rev-parse --git-dir >/dev/null 2>&1; then
+  echo '{"error":"not-a-git-repo"}' >&2; exit 3
+fi
+
+# Idempotent: only add if absent.
+if git config --get-all remote.origin.fetch 2>/dev/null |
+   grep -q 'refs/notes/super-design'; then
+  echo '{"status":"already-configured"}'
+else
+  git config --add remote.origin.fetch \
+    '+refs/notes/super-design:refs/notes/super-design'
+  echo '{"status":"added","ref":"refs/notes/super-design"}'
+fi

package/template/.claude/skills/super-design/scripts/validate-state.sh

@@ -1,14 +1,46 @@
 #!/usr/bin/env bash
+# Usage: validate-state.sh [<state_path>]
+#
+# Validates the super-design audit state file. On schema/parse errors,
+# moves the broken file aside (artifact §3 "Graceful corruption handling"
+# line 74) and emits a JSON verdict. Also enforces schema_version major
+# compatibility (artifact §12 line 934).
 set -euo pipefail
 STATE="${1:-docs/super-design/.audit-state.json}"
+
+# Current schema major is either read from a sibling .schema-version file
+# (so the number can be bumped without editing shell) or falls back to 1.
+SCHEMA_VERSION_FILE="$(dirname "$0")/../.schema-version"
+if [[ -f "$SCHEMA_VERSION_FILE" ]]; then
+  CURRENT_SCHEMA_MAJOR="$(cut -d. -f1 <"$SCHEMA_VERSION_FILE" | tr -d '[:space:]')"
+else
+  CURRENT_SCHEMA_MAJOR=1
+fi
+
 if [[ ! -f "$STATE" ]]; then echo '{"status":"missing"}'; exit 2; fi
-jq -e '
+
+# Parse + shape check. On failure, rename so the user can inspect and we
+# fall through to first-audit (SKILL.md Step 1 treats "corrupt" that way).
+if ! jq -e '
   (.schema_version | type == "string") and
   (.last_audit_at  | fromdateiso8601 | . > 0) and
   (.git_sha_at_audit | test("^[0-9a-f]{7,64}$")) and
   (.skill_version  | type == "string") and
   (.tools | type == "object")
-' "$STATE" >/dev/null 2>&1 || { echo '{"status":"corrupt"}'; exit 2; }
+' "$STATE" >/dev/null 2>&1; then
+  mv "$STATE" "$STATE.corrupt-$(date +%s)" 2>/dev/null || true
+  echo '{"status":"corrupt"}'; exit 2
+fi
+
+# schema_version major-bump check — if state was written by a newer OR
+# incompatible-older skill, force a full re-audit rather than silently
+# trusting the shape.
+STATE_MAJOR="$(jq -r '.schema_version' "$STATE" | cut -d. -f1)"
+if [[ -z "$STATE_MAJOR" || "$STATE_MAJOR" != "$CURRENT_SCHEMA_MAJOR" ]]; then
+  echo "{\"status\":\"schema-incompatible\",\"action\":\"force-full\",\"state_major\":\"${STATE_MAJOR:-unknown}\",\"current_major\":\"${CURRENT_SCHEMA_MAJOR}\"}"
+  exit 1
+fi
+
 AGE_DAYS=$(( ( $(date -u +%s) - $(jq -r '.last_audit_at | fromdateiso8601' "$STATE") ) / 86400 ))
 if (( AGE_DAYS > 180 )); then echo "{\"status\":\"stale-force-full\",\"age_days\":$AGE_DAYS}"; exit 1
 elif (( AGE_DAYS > 90 )); then echo "{\"status\":\"stale-refresh-research\",\"age_days\":$AGE_DAYS}"; exit 1

package/template/.claude/skills/super-design/scripts/write-state.sh

@@ -0,0 +1,26 @@
+#!/usr/bin/env bash
+# Usage: write-state.sh [<target>]        (reads JSON body from stdin)
+#
+# Atomic state writer: accepts JSON on stdin, writes to <target>.tmp,
+# validates with jq, then renames in place. Referenced from
+# docs/compass_artifact §11 ("Write-then-rename (atomic)") and SKILL.md
+# Step 4 ("Atomic write .audit-state.json").
+set -euo pipefail
+
+TARGET="${1:-docs/super-design/.audit-state.json}"
+TMP="${TARGET}.tmp"
+
+mkdir -p "$(dirname "$TARGET")"
+
+# Drain stdin into the tmp file.
+cat >"$TMP"
+
+# Validate it is parseable JSON before swapping.
+if ! jq -e 'type == "object"' "$TMP" >/dev/null 2>&1; then
+  rm -f "$TMP"
+  echo '{"error":"invalid-json-on-stdin"}' >&2
+  exit 2
+fi
+
+mv -f "$TMP" "$TARGET"
+echo "{\"status\":\"written\",\"path\":\"$TARGET\"}"