start-vibing 4.3.0 → 4.3.2

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

@@ -0,0 +1,180 @@
+#!/usr/bin/env bash
+# Usage: detect-apps.sh [<repo_root>]
+#
+# Detects monorepo layout for super-design per-app audit state (artifact §11
+# line 902). Reads workspace declarations from the known manifests:
+#   - pnpm-workspace.yaml       (pnpm)
+#   - package.json#workspaces   (npm / yarn / bun)
+#   - turbo.json                (Turborepo — infers apps from pipeline scope)
+#   - nx.json / workspace.json  (Nx)
+#   - bunfig.toml               (Bun workspaces)
+# For each matched glob we enumerate directories that also contain a
+# package.json; those are the apps. When no workspace config is found we
+# emit a single "single"-layout entry with path ".".
+#
+# Output JSON:
+#   {
+#     "layout": "monorepo" | "single",
+#     "apps": [
+#       { "name": "web",
+#         "path": "apps/web",
+#         "state_path": "apps/web/docs/super-design/.audit-state.json" }
+#     ]
+#   }
+#
+# POSIX-ish bash. Requires: jq. Works under git-bash on Windows (no GNU
+# find -printf, no readarray).
+set -euo pipefail
+
+ROOT="${1:-.}"
+cd "$ROOT"
+
+log() { printf '[detect-apps] %s\n' "$*" >&2; }
+
+# --- Collect workspace globs from whichever manifests exist ------------------
+GLOBS=""
+
+append_glob() {
+  # $1 = glob string; skip empty, comments, and negative (!) patterns for now.
+  local g
+  g="$(printf '%s' "$1" | tr -d '\r' | sed -e 's/^[[:space:]]*//' -e 's/[[:space:]]*$//')"
+  [ -z "$g" ] && return 0
+  case "$g" in
+    '#'*) return 0 ;;
+    '!'*) return 0 ;;
+  esac
+  GLOBS="${GLOBS}
+${g}"
+}
+
+# pnpm-workspace.yaml — very small YAML subset parser: lines under
+# "packages:" that start with "- ".
+if [ -f "pnpm-workspace.yaml" ]; then
+  in_pkgs=0
+  while IFS= read -r line; do
+    case "$line" in
+      packages:*) in_pkgs=1; continue ;;
+    esac
+    if [ "$in_pkgs" = "1" ]; then
+      case "$line" in
+        -\ *|\ *-\ *)
+          entry="$(printf '%s' "$line" | sed -e 's/^[[:space:]]*-[[:space:]]*//' -e 's/^["'\'']//' -e 's/["'\'']$//')"
+          append_glob "$entry"
+          ;;
+        [A-Za-z]*:) in_pkgs=0 ;;
+      esac
+    fi
+  done < "pnpm-workspace.yaml"
+fi
+
+# package.json#workspaces (array or { packages: [...] })
+if [ -f "package.json" ] && command -v jq >/dev/null 2>&1; then
+  WS_JSON="$(jq -r '
+    (.workspaces // empty)
+    | if type == "array" then .[]
+      elif type == "object" then (.packages // [])[]
+      else empty end
+  ' package.json 2>/dev/null || true)"
+  if [ -n "$WS_JSON" ]; then
+    while IFS= read -r g; do
+      [ -n "$g" ] && append_glob "$g"
+    done <<EOF
+$WS_JSON
+EOF
+  fi
+fi
+
+# turbo.json — Turborepo does not declare apps itself but relies on the
+# package manager's workspaces. Treat its presence as confirmation that
+# we are in a monorepo; globs come from package.json/pnpm-workspace.yaml
+# which we've already read. If only turbo.json exists (rare), fall back
+# to the conventional apps/* + packages/* layout.
+if [ -f "turbo.json" ] && [ -z "$GLOBS" ]; then
+  append_glob "apps/*"
+  append_glob "packages/*"
+fi
+
+# nx.json / workspace.json — Nx. Apps live under apps/, libs/ (or the
+# workspaceLayout override).
+if [ -f "nx.json" ]; then
+  apps_dir="apps"
+  libs_dir="libs"
+  if command -v jq >/dev/null 2>&1; then
+    override_apps="$(jq -r '.workspaceLayout.appsDir // empty' nx.json 2>/dev/null || true)"
+    override_libs="$(jq -r '.workspaceLayout.libsDir // empty' nx.json 2>/dev/null || true)"
+    [ -n "$override_apps" ] && apps_dir="$override_apps"
+    [ -n "$override_libs" ] && libs_dir="$override_libs"
+  fi
+  append_glob "${apps_dir}/*"
+  append_glob "${libs_dir}/*"
+fi
+
+# bunfig.toml — Bun workspaces. Bun primarily reads workspaces from
+# package.json#workspaces (already handled); bunfig.toml presence alone
+# is a monorepo hint only if nothing else matched.
+if [ -f "bunfig.toml" ] && [ -z "$GLOBS" ]; then
+  append_glob "apps/*"
+  append_glob "packages/*"
+fi
+
+# --- Expand globs to real directories that contain a package.json ------------
+APPS_JSON='[]'
+seen_paths=""
+
+expand_glob() {
+  # $1 = glob like "apps/*" or "packages/marketing-site"
+  local g="$1"
+  # shellcheck disable=SC2086
+  # We deliberately let the shell expand the glob. POSIX shells don't set
+  # nullglob, so an unmatched pattern comes back as the literal string —
+  # we filter that out below by checking directory existence.
+  for d in $g; do
+    [ -d "$d" ] || continue
+    [ -f "$d/package.json" ] || continue
+    # Normalize: strip trailing slash, leading ./
+    p="$(printf '%s' "$d" | sed -e 's#^\./##' -e 's#/$##')"
+    case "$seen_paths" in
+      *"|${p}|"*) continue ;;
+    esac
+    seen_paths="${seen_paths}|${p}|"
+    # Name = package.json "name" field (last path segment for scoped names),
+    # fallback to basename.
+    name="$(basename "$p")"
+    if command -v jq >/dev/null 2>&1; then
+      pkg_name="$(jq -r '.name // empty' "$p/package.json" 2>/dev/null || true)"
+      if [ -n "$pkg_name" ]; then
+        # Strip @scope/ prefix so "web" beats "@acme/web".
+        name="$(printf '%s' "$pkg_name" | sed -e 's#^@[^/]*/##')"
+      fi
+    fi
+    APPS_JSON="$(printf '%s' "$APPS_JSON" | jq --arg name "$name" --arg path "$p" \
+      --arg state "$p/docs/super-design/.audit-state.json" \
+      '. + [{name:$name, path:$path, state_path:$state}]')"
+  done
+}
+
+if [ -n "$GLOBS" ]; then
+  while IFS= read -r g; do
+    [ -z "$g" ] && continue
+    expand_glob "$g"
+  done <<EOF
+$GLOBS
+EOF
+fi
+
+APP_COUNT="$(printf '%s' "$APPS_JSON" | jq 'length')"
+
+if [ "$APP_COUNT" -eq 0 ]; then
+  # No monorepo config matched OR matched but produced no apps with
+  # package.json. Emit single-app layout.
+  jq -n '{
+    layout: "single",
+    apps: [ {name: ".", path: ".", state_path: "docs/super-design/.audit-state.json"} ]
+  }'
+  exit 0
+fi
+
+jq -n --argjson apps "$APPS_JSON" '{
+  layout: "monorepo",
+  apps: $apps
+}'

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

@@ -1,30 +1,184 @@
 #!/usr/bin/env bash
-# Usage: detect-changes.sh <last_sha> [<last_iso>]
-# Emits JSON: { mode, range_start, commits, files, classified }
+# Usage:
+#   detect-changes.sh <last_sha> [<last_iso>]                 (single app)
+#   detect-changes.sh --app <path> <last_sha> [<last_iso>]    (one app, path-scoped)
+#   detect-changes.sh --all-apps                              (monorepo loop)
+#
+# Emits JSON. Single-app form:
+#   { mode, range_start, commits, files, classified }
+#
+# Monorepo form (--all-apps) — one wrapper with per-app results; each
+# app reads its own `.audit-state.json` via detect-apps.sh:
+#   { "layout": "monorepo"|"single",
+#     "apps": [ { "name", "path", "state_path",
+#                 "last_sha", "changes": {<single-app form>} } ] }
+#
+# 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).
+#
+# Monorepo per-app state (artifact §11 line 902): when --app is given,
+# `git diff --name-status` is narrowed via `-- <app_path>/` pathspec so
+# only files under that app show up. `--all-apps` discovers apps via
+# detect-apps.sh and runs the per-app path for each.
 set -euo pipefail
 
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+EMPTY_TREE="4b825dc642cb6eb9a060e54bf8d69288fbee4904"
+
+log() { printf '[detect-changes] %s\n' "$*" >&2; }
+
+# --- Arg parsing -------------------------------------------------------------
+MODE_SELECT="single"   # single | app | all
+APP_PATH="."
+if [ "${1:-}" = "--all-apps" ]; then
+  MODE_SELECT="all"; shift
+elif [ "${1:-}" = "--app" ]; then
+  MODE_SELECT="app"; APP_PATH="${2:-.}"; shift 2
+fi
 LAST_SHA="${1:-}"
 LAST_ISO="${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
+# --- --all-apps: discover via detect-apps.sh, recurse per app ----------------
+if [ "$MODE_SELECT" = "all" ]; then
+  APPS_DOC="$(bash "$SCRIPT_DIR/detect-apps.sh" .)"
+  LAYOUT="$(printf '%s' "$APPS_DOC" | jq -r '.layout')"
+  RESULT='[]'
+  APP_COUNT="$(printf '%s' "$APPS_DOC" | jq '.apps | length')"
+  i=0
+  while [ "$i" -lt "$APP_COUNT" ]; do
+    APP_NAME="$(printf '%s' "$APPS_DOC" | jq -r ".apps[$i].name")"
+    A_PATH="$(printf '%s' "$APPS_DOC" | jq -r ".apps[$i].path")"
+    A_STATE="$(printf '%s' "$APPS_DOC" | jq -r ".apps[$i].state_path")"
+    A_LAST_SHA=""; A_LAST_ISO=""
+    if [ -f "$A_STATE" ]; then
+      A_LAST_SHA="$(jq -r '.git_sha_at_audit // ""' "$A_STATE" 2>/dev/null || true)"
+      A_LAST_ISO="$(jq -r '.last_audit_at  // ""' "$A_STATE" 2>/dev/null || true)"
+    fi
+    A_CHANGES="$(bash "$0" --app "$A_PATH" "$A_LAST_SHA" "$A_LAST_ISO")"
+    RESULT="$(printf '%s' "$RESULT" | jq \
+      --arg name "$APP_NAME" --arg path "$A_PATH" --arg state "$A_STATE" \
+      --arg lsha "$A_LAST_SHA" --argjson ch "$A_CHANGES" '
+      . + [{name:$name, path:$path, state_path:$state, last_sha:$lsha, changes:$ch}]
+    ')"
+    i=$((i + 1))
+  done
+  jq -n --arg layout "$LAYOUT" --argjson apps "$RESULT" '{layout:$layout, apps:$apps}'
+  exit 0
+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
+
+# Build the pathspec used to narrow diff/log to a single app (monorepo
+# per-app state, artifact §11 line 902). For the default "." the scope
+# is the repo root, preserving pre-existing single-app behavior.
+case "$APP_PATH" in
+  .|"") SCOPE_PATH="." ;;
+  *)    SCOPE_PATH="${APP_PATH%/}" ;;
+esac
+
+# Ladder step (c): time-based fallback.
+if [[ -z "${RANGE_START:-}" && -n "$LAST_ISO" ]]; then
+  log "using --since=$LAST_ISO time-based fallback (scope=$SCOPE_PATH)"
+  FILES="$(git log --since="$LAST_ISO" --name-only --pretty=format: -- "$SCOPE_PATH" 2>/dev/null | sort -u | sed '/^$/d' || true)"
+  COMMITS="$(git log --first-parent --since="$LAST_ISO" --pretty=format:'%H|%s|%an|%aI' -- "$SCOPE_PATH" 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 \
+      -- "$SCOPE_PATH" ':!*.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 +186,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 +197,8 @@ 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 app_path "$APP_PATH" \
   --arg tokens "${CLASSIFIED[tokens]:-}" --arg components "${CLASSIFIED[components]:-}" \
   --arg routes "${CLASSIFIED[routes]:-}" --arg imagery "${CLASSIFIED[imagery]:-}" \
   --arg deps "${CLASSIFIED[deps]:-}" --arg theory "${CLASSIFIED[theory]:-}" \
@@ -51,7 +206,8 @@ jq -Rn --arg mode "$MODE" --arg range_start "$RANGE_START" --arg last_iso "$LAST
   --argjson files "$(printf '%s\n' "$FILES" | jq -R . | jq -s .)" \
   --argjson commits "$(printf '%s\n' "$COMMITS" | jq -R . | jq -s .)" '
   def tolist(s): s | split(",") | map(select(length>0));
-  {mode:$mode, range_start:$range_start, since_iso:$last_iso,
+  {app_path:$app_path,
+   mode:$mode, range_start:$range_start, since_iso:$last_iso,
    commits:$commits, files:$files,
    classified: {
      tokens: tolist($tokens), components: tolist($components),

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

@@ -1,6 +1,26 @@
 #!/usr/bin/env bash
+# discover-routes.sh — discover route URLs for the detected framework.
+#
+# Dynamic routes (Next `[slug]` / `[[...foo]]` / `[...bar]`, Remix `$slug`,
+# React-Router/Vue `:slug`) are emitted with a `@fixture-<id>` suffix so
+# the route map has a stable identity across audits (artifact §2.7 + §7:
+# "/posts/[id]@fixture-post-123"). Fixtures are resolved via:
+#
+#   1. Sibling file: <route-dir>/<name>.fixture.json|ts (array of IDs or
+#      objects with {id|slug|key}).
+#   2. Nearby directory: <route-dir>/fixtures/*.json.
+#   3. Env override: $SUPER_DESIGN_FIXTURES — a JSON object mapping the
+#      raw pattern (e.g. "/posts/[slug]") to an array of fixture IDs.
+#   4. Placeholder fallback: `@fixture-default` (with stderr warning).
+#
+# Consumers (hash-pages.sh, sd-audit) MUST strip the `@fixture-<id>`
+# suffix before navigating; the suffix is identity-only.
+#
+# Output: JSON array of URL strings.
 set -euo pipefail
 
+log() { printf '[discover-routes] %s\n' "$*" >&2; }
+
 detect_framework() {
   if   [[ -f next.config.js || -f next.config.ts || -f next.config.mjs ]]; then echo "next"
   elif [[ -f remix.config.js || -d app/routes ]]; then echo "remix"
@@ -13,6 +33,96 @@ detect_framework() {
   else echo "unknown"; fi
 }
 
+# is_dynamic <url> → 0 if URL contains a dynamic segment, else 1.
+is_dynamic() {
+  local u="$1"
+  # Next-style: [foo], [[foo]], [...foo], [[...foo]]
+  [[ "$u" == *"["*"]"* ]] && return 0
+  # Remix-style: $foo
+  [[ "$u" == *"$"* ]] && return 0
+  # RR/Vue-style: :foo
+  [[ "$u" == *":"* ]] && return 0
+  return 1
+}
+
+# Look for a fixtures source for a given route URL and emit IDs one per
+# line. Echo `__DEFAULT__` if nothing found.
+resolve_fixture_ids() {
+  local url="$1"
+  local segment
+  # Strip leading / and use the last dynamic-bearing segment to find a file.
+  # Rough heuristic: pick the last path component that is a bare identifier
+  # (strip brackets/dollar/colon) to look up fixtures/<name>.*.
+  segment="$(printf '%s' "$url" \
+    | sed -E 's|^/||' \
+    | tr '/' '\n' \
+    | grep -E '^(\[\[?\.\.\.?.+\]\]?|\[.+\]|\$.+|:.+)$' \
+    | tail -1 \
+    | sed -E 's|^\[\[?\.?\.?\.?||; s|\]\]?$||; s|^\$||; s|^:||')"
+  [[ -z "$segment" ]] && { echo "__DEFAULT__"; return; }
+
+  # 1. Env override.
+  if [[ -n "${SUPER_DESIGN_FIXTURES:-}" ]]; then
+    local ids
+    ids="$(printf '%s' "$SUPER_DESIGN_FIXTURES" \
+      | jq -r --arg k "$url" '.[$k][]? // empty' 2>/dev/null || true)"
+    if [[ -n "$ids" ]]; then
+      printf '%s\n' "$ids"; return
+    fi
+  fi
+
+  # 2. Sibling / nearby fixture files. Search in common locations.
+  local candidate ids=""
+  for candidate in \
+      "${segment}.fixture.json" \
+      "fixtures/${segment}.json" \
+      "tests/fixtures/${segment}.json" \
+      "__fixtures__/${segment}.json" \
+      ".super-design/fixtures/${segment}.json"; do
+    local found
+    found="$(find . -type f -name "$(basename "$candidate")" 2>/dev/null \
+      | grep -F "/$candidate" | head -1 || true)"
+    if [[ -n "$found" && -f "$found" ]]; then
+      ids="$(jq -r '
+        if type == "array" then
+          .[] | if type == "object" then (.id // .slug // .key // empty) else . end
+        elif type == "object" and (.fixtures|type=="array") then
+          .fixtures[] | if type=="object" then (.id // .slug // .key // empty) else . end
+        else empty end
+      ' "$found" 2>/dev/null | head -5 || true)"
+      if [[ -n "$ids" ]]; then
+        printf '%s\n' "$ids"; return
+      fi
+    fi
+  done
+
+  # 3. Give up → default placeholder with warning.
+  log "no fixtures for $url; using @fixture-default"
+  echo "__DEFAULT__"
+}
+
+# suffix_dynamic_routes: read raw URLs on stdin, write suffixed URLs on
+# stdout. Static routes pass through untouched.
+suffix_dynamic_routes() {
+  local url ids id
+  while IFS= read -r url; do
+    [[ -z "$url" ]] && continue
+    if is_dynamic "$url"; then
+      ids="$(resolve_fixture_ids "$url")"
+      if [[ "$ids" == "__DEFAULT__" ]]; then
+        printf '%s@fixture-default\n' "$url"
+      else
+        while IFS= read -r id; do
+          [[ -z "$id" ]] && continue
+          printf '%s@fixture-%s\n' "$url" "$id"
+        done <<<"$ids"
+      fi
+    else
+      printf '%s\n' "$url"
+    fi
+  done
+}
+
 FW="$(detect_framework)"
 case "$FW" in
   next)
@@ -22,24 +132,28 @@ case "$FW" in
     PG="$(find pages src/pages -type f \( -name '*.tsx' -o -name '*.ts' -o -name '*.jsx' -o -name '*.js' -o -name '*.md' -o -name '*.mdx' \) 2>/dev/null \
       | grep -vE '(^|/)(pages|src/pages)/(_app|_document|_error|404|500|api/)' \
       | sed -E 's|(^|/)(pages|src/pages)/||; s|\.(tsx|ts|jsx|js|md|mdx)$||; s|index$||' | sort -u || true)"
-    printf '%s\n%s\n' "$APP" "$PG" | awk 'NF' | sed -E 's|^|/|; s|//|/|g' | sort -u | jq -Rn '[inputs]';;
+    printf '%s\n%s\n' "$APP" "$PG" | awk 'NF' | sed -E 's|^|/|; s|//|/|g' | sort -u \
+      | suffix_dynamic_routes | jq -Rn '[inputs]';;
   sveltekit)
     find src/routes -type f -name '+page.svelte' 2>/dev/null \
       | sed -E 's|^src/routes||; s|/\+page\.svelte$||; s|\([^)]+\)/||g' \
-      | awk 'NF==0 {print "/"; next} {print}' | sort -u | jq -Rn '[inputs]';;
+      | awk 'NF==0 {print "/"; next} {print}' | sort -u \
+      | suffix_dynamic_routes | jq -Rn '[inputs]';;
   astro)
     find src/pages -type f \( -name '*.astro' -o -name '*.md' -o -name '*.mdx' \) 2>/dev/null \
-      | sed -E 's|^src/pages||; s|\.(astro|md|mdx)$||; s|/index$||' | sort -u | jq -Rn '[inputs]';;
+      | sed -E 's|^src/pages||; s|\.(astro|md|mdx)$||; s|/index$||' | sort -u \
+      | suffix_dynamic_routes | jq -Rn '[inputs]';;
   nuxt)
     find pages app/pages -type f -name '*.vue' 2>/dev/null \
-      | sed -E 's|^(app/)?pages||; s|\.vue$||; s|/index$||' | sort -u | jq -Rn '[inputs]';;
+      | sed -E 's|^(app/)?pages||; s|\.vue$||; s|/index$||' | sort -u \
+      | suffix_dynamic_routes | jq -Rn '[inputs]';;
   remix)
     find app/routes -type f \( -name '*.tsx' -o -name '*.ts' -o -name '*.jsx' -o -name '*.js' -o -name '*.md' -o -name '*.mdx' \) 2>/dev/null \
       | sed -E 's|^app/routes/||; s|\.(tsx|ts|jsx|js|md|mdx)$||; s|\.|/|g; s|_index$||; s|^|/|' \
-      | sort -u | jq -Rn '[inputs]';;
+      | sort -u | suffix_dynamic_routes | jq -Rn '[inputs]';;
   solid-start)
     find src/routes -type f \( -name '*.tsx' -o -name '*.ts' -o -name '*.jsx' -o -name '*.js' \) 2>/dev/null \
       | sed -E 's|^src/routes||; s|\.(tsx|ts|jsx|js)$||; s|/index$||; s|\([^)]+\)/||g' \
-      | sort -u | jq -Rn '[inputs]';;
+      | sort -u | suffix_dynamic_routes | jq -Rn '[inputs]';;
   *) echo '[]';;
 esac