create-anpunkit 2.0.3 → 2.2.0

package/template/scripts/spec-conformance.sh

@@ -0,0 +1,93 @@
+#!/usr/bin/env bash
+# spec-conformance.sh — block GREEN until the phase spec is fully filled and every
+# case is verified by a boundary test (v2.2). Runs between RED and GREEN, replacing
+# the v2.1 human TEST REVIEW gate. (§5.55, rule 18)
+#
+# Two checks, both loud-fail (nonzero), no side effects:
+#   1. NO `TBD` remains in docs/spec-phase-<n>.md or any fixture it references.
+#   2. EVERY case-id in the spec table is cited by a test via `# spec: <case-id>`
+#      (or `// spec: <case-id>`) under tests/ or e2e/.
+#
+#   bash scripts/spec-conformance.sh <phase-n>
+#
+# The case→test citation here, plus the placement convention (contract/transition
+# tests live in tests/regression/), is what closes the rule-14 chain: reachable
+# transition → filled case (rule 14) → cited boundary test (this) → regression corpus.
+set -euo pipefail
+cd "${CLAUDE_PROJECT_DIR:-.}"
+
+N="${1:-}"
+[ -n "$N" ] || { echo "spec-conformance: usage: spec-conformance.sh <phase-n>" >&2; exit 2; }
+
+SPEC="docs/spec-phase-${N}.md"
+[ -f "$SPEC" ] || { echo "spec-conformance: $SPEC not found." >&2; exit 2; }
+
+FAIL=0
+
+# ---- 1. no TBD left in the spec ----
+if grep -nE '\bTBD\b' "$SPEC" >/dev/null 2>&1; then
+  echo "spec-conformance: FAIL — unfilled 'TBD' marker(s) remain in $SPEC:" >&2
+  grep -nE '\bTBD\b' "$SPEC" | sed 's/^/    /' >&2
+  echo "  Every case must be filled (or escalated as CASE-SET-DIVERGENCE) before GREEN." >&2
+  FAIL=1
+fi
+
+# ---- referenced fixtures: must exist + carry no TBD ----
+FIXREFS="$(grep -oE 'fixtures/[A-Za-z0-9_./-]+\.json' "$SPEC" | sort -u || true)"
+if [ -n "$FIXREFS" ]; then
+  while IFS= read -r fx; do
+    [ -n "$fx" ] || continue
+    if [ ! -f "$fx" ]; then
+      echo "spec-conformance: FAIL — referenced fixture missing: $fx" >&2
+      FAIL=1
+    elif grep -nE '\bTBD\b' "$fx" >/dev/null 2>&1; then
+      echo "spec-conformance: FAIL — 'TBD' marker in fixture: $fx" >&2
+      FAIL=1
+    fi
+  done <<EOF
+$FIXREFS
+EOF
+fi
+
+# ---- 2. every case-id cited by a boundary test ----
+# case-ids = the FIRST table-column cell of each row, matching PH<n>-... exactly.
+# (Parse the column, not a free grep — else `fixtures/PH1-ORDER-01-input.json`
+#  would yield a bogus `PH1-ORDER-01-input` case-id.)
+CASE_IDS="$(grep -E '^\|' "$SPEC" \
+  | awk -F'|' '{ id=$2; gsub(/^[ \t]+|[ \t]+$/,"",id); print id }' \
+  | grep -E "^PH${N}-[A-Za-z0-9_-]+$" | sort -u || true)"
+if [ -z "$CASE_IDS" ]; then
+  echo "spec-conformance: WARN — no PH${N}-* case-ids found in $SPEC (empty spec?)." >&2
+fi
+
+SEARCH_DIRS=""
+[ -d tests ] && SEARCH_DIRS="$SEARCH_DIRS tests"
+[ -d e2e ]   && SEARCH_DIRS="$SEARCH_DIRS e2e"
+
+if [ -n "$CASE_IDS" ]; then
+  if [ -z "$SEARCH_DIRS" ]; then
+    echo "spec-conformance: FAIL — case-ids exist but no tests/ or e2e/ dir to cite them." >&2
+    FAIL=1
+  else
+    while IFS= read -r cid; do
+      [ -n "$cid" ] || continue
+      # cite convention: `spec: <case-id>` with a non-id char (or EOL) after, so
+      # PH2-ORDER-01 does not match PH2-ORDER-011.
+      if grep -rEq -- "spec:[[:space:]]*${cid}([^0-9A-Za-z_-]|$)" $SEARCH_DIRS 2>/dev/null; then
+        :
+      else
+        echo "spec-conformance: FAIL — case ${cid} has no boundary test citing it (# spec: ${cid})." >&2
+        FAIL=1
+      fi
+    done <<EOF
+$CASE_IDS
+EOF
+  fi
+fi
+
+if [ "$FAIL" -ne 0 ]; then
+  echo "spec-conformance: BLOCKED — fix the above before GREEN." >&2
+  exit 1
+fi
+echo "spec-conformance: OK — phase ${N} spec fully filled; every case-id cited by a boundary test."
+exit 0

package/template/scripts/spec-staleness.sh

@@ -0,0 +1,115 @@
+#!/usr/bin/env bash
+# spec-staleness.sh — guard the per-phase spec header against upstream drift (v2.2).
+#
+# The behavioral contract docs/spec-phase-<n>.md carries a GENERATED header that
+# transcludes the phase's PLAN.md `- acceptance:` line + the in-scope DATAFLOW.md
+# transition rows, plus an embedded hash. If PLAN.md / DATAFLOW.md change after the
+# skeleton was stamped (e.g. via /replan), the stored hash no longer matches the
+# upstream → the spec must be regenerated/re-filled before SPEC REVIEW. (§5.55, rule 17)
+#
+# Hashing lives ONLY here (no duplication in agent prompts):
+#   bash scripts/spec-staleness.sh stamp <n>    # compute + embed the hash (at /overview, on regenerate)
+#   bash scripts/spec-staleness.sh check <n>    # default: recompute + compare; nonzero on drift
+#   bash scripts/spec-staleness.sh <n>          # alias for: check <n>
+#
+# set -euo pipefail; nonzero = loud fail; `stamp` is the only side effect.
+set -euo pipefail
+cd "${CLAUDE_PROJECT_DIR:-.}"
+
+# ---- args ----
+SUB="check"
+case "${1:-}" in
+  stamp) SUB="stamp"; shift;;
+  check) SUB="check"; shift;;
+esac
+N="${1:-}"
+[ -n "$N" ] || { echo "spec-staleness: usage: spec-staleness.sh [stamp|check] <phase-n>" >&2; exit 2; }
+
+SPEC="docs/spec-phase-${N}.md"
+PLAN="docs/PLAN.md"
+DATAFLOW="docs/DATAFLOW.md"
+[ -f "$SPEC" ] || { echo "spec-staleness: $SPEC not found." >&2; exit 2; }
+[ -f "$PLAN" ] || { echo "spec-staleness: $PLAN not found." >&2; exit 2; }
+
+# ---- sha256 of stdin (portable: sha256sum -> shasum -> node) ----
+sha_stdin() {
+  if   command -v sha256sum >/dev/null 2>&1; then sha256sum | cut -d' ' -f1
+  elif command -v shasum    >/dev/null 2>&1; then shasum -a 256 | cut -d' ' -f1
+  else node -e "let d='';process.stdin.on('data',c=>d+=c).on('end',()=>console.log(require('crypto').createHash('sha256').update(d).digest('hex')))"
+  fi
+}
+
+# normalize: NFC-ish arrow unify (→ -> ->), collapse spaces, trim. Content-sensitive,
+# whitespace-insensitive — so cosmetic reflow does not trip the guard, content does.
+norm() { sed -e 's/→/->/g' -e 's/[[:space:]]\{1,\}/ /g' -e 's/^ //' -e 's/ $//'; }
+
+# ---- extract this phase's block from PLAN.md (## Phase <n>: ... up to next ## Phase) ----
+phase_block() {
+  awk -v n="$N" '
+    $0 ~ ("^## Phase " n ":") {inblk=1; print; next}
+    inblk && /^## Phase /      {inblk=0}
+    inblk                      {print}
+  ' "$PLAN"
+}
+
+BLOCK="$(phase_block || true)"
+[ -n "$BLOCK" ] || { echo "spec-staleness: no '## Phase ${N}:' block in $PLAN." >&2; exit 2; }
+
+# acceptance line(s) + dataflow line, normalized
+ACC_LINE="$(printf '%s\n' "$BLOCK"   | grep -E '^- acceptance:' | norm || true)"
+DF_LINE="$(printf '%s\n'  "$BLOCK"   | grep -E '^- dataflow:'   | norm || true)"
+
+# in-scope transition tokens (from->to) named on the dataflow line
+TOKENS="$(printf '%s\n' "$DF_LINE" | norm | grep -oE '[A-Za-z0-9_]+->[A-Za-z0-9_]+' | sort -u || true)"
+
+# matching DATAFLOW.md data-rows (table rows naming an in-scope transition)
+DF_ROWS=""
+if [ -n "$TOKENS" ] && [ -f "$DATAFLOW" ]; then
+  while IFS= read -r tok; do
+    [ -n "$tok" ] || continue
+    rows="$(grep -E '^\|' "$DATAFLOW" | norm | grep -F "$tok" || true)"
+    DF_ROWS="${DF_ROWS}${rows}
+"
+  done <<EOF
+$TOKENS
+EOF
+fi
+DF_ROWS="$(printf '%s\n' "$DF_ROWS" | grep -v '^$' | sort -u || true)"
+
+# ---- the upstream signature + its hash ----
+SIG="$(printf 'ACC:%s\nDF:%s\nROWS:\n%s\n' "$ACC_LINE" "$DF_LINE" "$DF_ROWS")"
+WANT="$(printf '%s' "$SIG" | sha_stdin)"
+
+HASH_RE='^<!-- spec-hash: .* -->$'
+HAVE="$(grep -E "$HASH_RE" "$SPEC" | head -1 | sed -E 's/^<!-- spec-hash: (.*) -->$/\1/' || true)"
+
+if [ "$SUB" = "stamp" ]; then
+  if grep -qE "$HASH_RE" "$SPEC"; then
+    tmp="$(mktemp)"
+    awk -v h="$WANT" '
+      /^<!-- spec-hash: .* -->$/ && !done { print "<!-- spec-hash: " h " -->"; done=1; next }
+      { print }
+    ' "$SPEC" > "$tmp" && mv "$tmp" "$SPEC"
+  else
+    echo "spec-staleness: $SPEC has no '<!-- spec-hash: ... -->' header line to stamp." >&2
+    exit 2
+  fi
+  echo "spec-staleness: stamped phase ${N} -> ${WANT}"
+  exit 0
+fi
+
+# ---- check ----
+if [ -z "$HAVE" ] || [ "$HAVE" = "PENDING" ]; then
+  echo "spec-staleness: FAIL — phase ${N} spec hash is unstamped (${HAVE:-missing})." >&2
+  echo "  Run: bash scripts/spec-staleness.sh stamp ${N}" >&2
+  exit 1
+fi
+if [ "$HAVE" != "$WANT" ]; then
+  echo "spec-staleness: FAIL — phase ${N} spec is STALE." >&2
+  echo "  Upstream PLAN.md acceptance / DATAFLOW.md rows changed since the skeleton was stamped." >&2
+  echo "  stored=${HAVE}  current=${WANT}" >&2
+  echo "  Regenerate the skeleton header from current PLAN/DATAFLOW, re-stamp, and re-fill." >&2
+  exit 1
+fi
+echo "spec-staleness: OK — phase ${N} spec header matches upstream (${WANT})."
+exit 0

package/template/setup.sh

@@ -12,6 +12,8 @@
 #   hybrid      -> merged idempotently, never replaced
 #
 # Flags: --src DIR --kb-path P --kb-remote URL --no-kb --force --dry-run
+#        --tools LIST   (comma/space list from: claude cursor; default both)
+#        --add-tool T   (additive: install T's files into an existing project)
 set -euo pipefail
 
 SRC="."
@@ -20,6 +22,9 @@ KB_REMOTE="${ANPUNKIT_KB_REMOTE:-}"
 NO_KB=0
 FORCE=0
 DRY=0
+TOOLS_FLAG=""
+ADD_TOOL=""
+AVAILABLE_TOOLS="claude cursor"   # tools with real adapters; extend here
 while [ $# -gt 0 ]; do
   case "$1" in
     --src)       SRC="$2"; shift 2;;
@@ -28,6 +33,8 @@ while [ $# -gt 0 ]; do
     --no-kb)     NO_KB=1; shift;;
     --force)     FORCE=1; shift;;
     --dry-run)   DRY=1; shift;;
+    --tools)     TOOLS_FLAG="$2"; shift 2;;
+    --add-tool)  ADD_TOOL="$2"; shift 2;;
     *) echo "unknown flag: $1" >&2; exit 2;;
   esac
 done
@@ -63,6 +70,36 @@ fi
 say "mode: $MODE (installed: ${OLD_VER:-none} -> new: $NEW_VER)"
 [ "$MODE" = "newer-installed" ] && say "  ! installed version is newer than this package — proceeding as repair, review carefully."
 
+# ---- tool selection (v2.1): install only the selected tools' adapters/hooks/files
+TOOLS_FILE="$DEST/.claude/anpunkit-tools.json"
+norm_tools() { printf '%s' "$1" | tr ',' ' ' | tr -s ' ' | sed 's/^ //; s/ $//'; }
+read_recorded_tools() {
+  [ -f "$TOOLS_FILE" ] || { printf ''; return; }
+  node -e "try{console.log((JSON.parse(require('fs').readFileSync(process.argv[1],'utf8')).tools||[]).join(' '))}catch(e){console.log('')}" "$TOOLS_FILE" 2>/dev/null || printf ''
+}
+valid_tool() { case " $AVAILABLE_TOOLS " in *" $1 "*) return 0;; *) return 1;; esac; }
+
+RECORDED="$(read_recorded_tools)"
+if [ -n "$TOOLS_FLAG" ]; then
+  TOOLS="$(norm_tools "$TOOLS_FLAG")"
+elif [ -n "$RECORDED" ]; then
+  TOOLS="$RECORDED"               # re-run: preserve prior selection
+elif [ "$MODE" = "fresh" ] && [ -t 0 ]; then
+  printf "  Select tools to install (space-separated from: %s) [claude cursor]: " "$AVAILABLE_TOOLS"
+  read -r _sel || true
+  TOOLS="$(norm_tools "${_sel:-claude cursor}")"
+else
+  TOOLS="claude cursor"           # non-interactive default = both (no regression)
+fi
+# additive: --add-tool unions into the selection (and is recorded)
+[ -n "$ADD_TOOL" ] && TOOLS="$(norm_tools "$TOOLS $(norm_tools "$ADD_TOOL")" | tr ' ' '\n' | sort -u | tr '\n' ' ')"
+TOOLS="$(norm_tools "$TOOLS")"
+# validate
+for t in $TOOLS; do valid_tool "$t" || { echo "FATAL: unknown tool '$t' (available: $AVAILABLE_TOOLS)"; exit 2; }; done
+[ -z "$TOOLS" ] && { echo "FATAL: no tools selected"; exit 2; }
+tool_selected() { case " $TOOLS " in *" $1 "*) return 0;; *) return 1;; esac; }
+say "tools: $TOOLS$([ -n "$ADD_TOOL" ] && echo '  (+'"$ADD_TOOL"' added)')"
+
 BACKUP="$DEST/.anpunkit-backup-$(date +%Y%m%d-%H%M%S)"
 backup_one() {
   [ "$MODE" = "fresh" ] && return 0
@@ -77,6 +114,11 @@ backup_one() {
 install_kit_file() {
   local rel="$1" s="$SRC/$1" d="$DEST/$1"
   [ -f "$s" ] || return 0
+  # v2.1 tool gating: cursor-only files skipped unless cursor selected.
+  # (.claude/* is shared infra — Cursor reads .claude/agents + .claude/hooks too.)
+  case "$rel" in
+    .cursor/*) tool_selected cursor || { act "skip     $rel (cursor not selected)"; return 0; };;
+  esac
   if [ ! -f "$d" ]; then
     act "write    $rel"; [ "$DRY" = 1 ] && return 0
     mkdir -p "$(dirname "$d")"; cp -p "$s" "$d"; return 0
@@ -114,61 +156,76 @@ else
 fi
 
 # ---- generate command adapters from commands.src/ (manifest-owned output)
-say ""; say "[2/6] generate command adapters:"
+say ""; say "[2/6] generate command adapters (tools: $TOOLS):"
 gen_adapters() {
-  mkdir -p "$DEST/.claude/commands" "$DEST/.cursor/commands" "$DEST/.cursor/rules"
+  tool_selected claude && mkdir -p "$DEST/.claude/commands"
+  tool_selected cursor && mkdir -p "$DEST/.cursor/commands" "$DEST/.cursor/rules"
   for f in "$DEST"/commands.src/*.md; do
     [ -f "$f" ] || continue
     n=$(basename "$f")
-    act "claude   .claude/commands/$n"
-    act "cursor   .cursor/commands/$n"
-    [ "$DRY" = 1 ] && continue
-    cp -p "$f" "$DEST/.claude/commands/$n"
-    awk 'BEGIN{fm=0} NR==1 && $0=="---"{fm=1; next} fm==1 && $0=="---"{fm=0; next} fm==0{print}' "$f" \
-      | sed '/^$/{1d}' > "$DEST/.cursor/commands/$n"
+    if tool_selected claude; then
+      act "claude   .claude/commands/$n"
+      [ "$DRY" = 1 ] || cp -p "$f" "$DEST/.claude/commands/$n"
+    fi
+    if tool_selected cursor; then
+      act "cursor   .cursor/commands/$n"
+      [ "$DRY" = 1 ] || awk 'BEGIN{fm=0} NR==1 && $0=="---"{fm=1; next} fm==1 && $0=="---"{fm=0; next} fm==0{print}' "$f" \
+        | sed '/^$/{1d}' > "$DEST/.cursor/commands/$n"
+    fi
   done
 }
 gen_adapters
 
-# ---- hybrid JSON merge: ensure the 3 hook entries, never drop user keys
-say ""; say "[3/6] wire hooks (idempotent merge):"
+# ---- hybrid JSON merge: ensure the hook entries for selected tools, never drop user keys
+say ""; say "[3/6] wire hooks (idempotent merge, tools: $TOOLS):"
 merge_settings() {
-  [ "$DRY" = 1 ] && { act "merge    .claude/settings.json + .cursor/hooks.json"; return 0; }
-  backup_one "$DEST/.claude/settings.json"; backup_one "$DEST/.cursor/hooks.json"
+  [ "$DRY" = 1 ] && { act "merge    $(tool_selected claude && echo -n '.claude/settings.json ')$(tool_selected cursor && echo -n '.cursor/hooks.json')"; return 0; }
+  tool_selected claude && backup_one "$DEST/.claude/settings.json"
+  tool_selected cursor && backup_one "$DEST/.cursor/hooks.json"
+  CLAUDE_SEL=$(tool_selected claude && echo 1 || echo 0) \
+  CURSOR_SEL=$(tool_selected cursor && echo 1 || echo 0) \
   node - "$DEST" <<'NODE'
 const fs=require('fs'),path=require('path');
 const dest=process.argv[2];
+const claudeSel=process.env.CLAUDE_SEL==='1', cursorSel=process.env.CURSOR_SEL==='1';
 const load=(p,d)=>{try{return JSON.parse(fs.readFileSync(p,'utf8'))}catch(e){return d}};
 const save=(p,o)=>{fs.mkdirSync(path.dirname(p),{recursive:true});fs.writeFileSync(p,JSON.stringify(o,null,2)+"\n")};
+const out=[];
 // Claude settings.json
-const sp=path.join(dest,'.claude/settings.json');
-const s=load(sp,{});
-if(!s.$schema)s.$schema='https://json.schemastore.org/claude-code-settings.json';
-s.hooks=s.hooks||{};
-const ensure=(event,matcher,cmd)=>{
-  const arr=s.hooks[event]=s.hooks[event]||[];
-  for(const blk of arr)for(const h of (blk.hooks||[]))if(h.command===cmd)return;
-  const blk={hooks:[{type:'command',command:cmd}]};
-  if(matcher)blk.matcher=matcher;
-  arr.push(blk);
-};
-ensure('SessionStart','startup|clear|compact','bash .claude/hooks/session-start.sh');
-ensure('PreCompact','auto|manual','bash .claude/hooks/pre-compact.sh');
-ensure('SubagentStop','','bash .claude/hooks/subagent-stop.sh');
-save(sp,s);
+if(claudeSel){
+  const sp=path.join(dest,'.claude/settings.json');
+  const s=load(sp,{});
+  if(!s.$schema)s.$schema='https://json.schemastore.org/claude-code-settings.json';
+  s.hooks=s.hooks||{};
+  const ensure=(event,matcher,cmd)=>{
+    const arr=s.hooks[event]=s.hooks[event]||[];
+    for(const blk of arr)for(const h of (blk.hooks||[]))if(h.command===cmd)return;
+    const blk={hooks:[{type:'command',command:cmd}]};
+    if(matcher)blk.matcher=matcher;
+    arr.push(blk);
+  };
+  ensure('SessionStart','startup|clear|compact','bash .claude/hooks/session-start.sh');
+  ensure('PreCompact','auto|manual','bash .claude/hooks/pre-compact.sh');
+  ensure('SubagentStop','','bash .claude/hooks/subagent-stop.sh');
+  save(sp,s);
+  out.push('.claude/settings.json');
+}
 // Cursor hooks.json
-const cp=path.join(dest,'.cursor/hooks.json');
-const c=load(cp,{version:1,hooks:{}});
-c.hooks=c.hooks||{};
-const cursorEnsure=(event,cmd)=>{
-  const arr=c.hooks[event]=c.hooks[event]||[];
-  if(!arr.some(h=>h.command===cmd))arr.push({command:cmd});
-};
-cursorEnsure('sessionStart','bash .claude/hooks/cursor-session-start.sh');
-cursorEnsure('preCompact','bash .claude/hooks/pre-compact.sh');
-cursorEnsure('subagentStop','bash .claude/hooks/subagent-stop.sh');
-save(cp,c);
-console.log('  merged .claude/settings.json + .cursor/hooks.json');
+if(cursorSel){
+  const cp=path.join(dest,'.cursor/hooks.json');
+  const c=load(cp,{version:1,hooks:{}});
+  c.hooks=c.hooks||{};
+  const cursorEnsure=(event,cmd)=>{
+    const arr=c.hooks[event]=c.hooks[event]||[];
+    if(!arr.some(h=>h.command===cmd))arr.push({command:cmd});
+  };
+  cursorEnsure('sessionStart','bash .claude/hooks/cursor-session-start.sh');
+  cursorEnsure('preCompact','bash .claude/hooks/pre-compact.sh');
+  cursorEnsure('subagentStop','bash .claude/hooks/subagent-stop.sh');
+  save(cp,c);
+  out.push('.cursor/hooks.json');
+}
+console.log('  merged '+(out.join(' + ')||'(nothing — no tool selected hooks)'));
 NODE
 }
 merge_settings
@@ -180,13 +237,17 @@ say ""; say "[4/6] AGENTS.md / CLAUDE.md verify:"
 verify_import() {
   local CL="$DEST/CLAUDE.md" AG="$DEST/AGENTS.md"
   [ -f "$AG" ] || { echo "FATAL VERIFY: AGENTS.md not on disk"; exit 1; }
-  # bare top-level @AGENTS.md import (not indented, not fenced)
-  if ! grep -qE '^@AGENTS\.md[[:space:]]*$' "$CL"; then
-    echo "FATAL VERIFY: CLAUDE.md is missing a bare top-level '@AGENTS.md' import line"; exit 1; fi
-  # sentinel present in AGENTS.md
+  # sentinel present in AGENTS.md (shared — both tools read AGENTS.md)
   if ! grep -q 'ANPUNKIT-AGENTS-SENTINEL' "$AG"; then
     echo "FATAL VERIFY: AGENTS.md sentinel missing (file clobbered or empty?)"; exit 1; fi
-  say "  VERIFY ok: bare @AGENTS.md import + AGENTS.md on disk + sentinel present."
+  # CLAUDE.md bare @AGENTS.md import is Claude-specific — only verify if claude selected
+  if tool_selected claude; then
+    if ! grep -qE '^@AGENTS\.md[[:space:]]*$' "$CL"; then
+      echo "FATAL VERIFY: CLAUDE.md is missing a bare top-level '@AGENTS.md' import line"; exit 1; fi
+    say "  VERIFY ok: bare @AGENTS.md import + AGENTS.md on disk + sentinel present."
+  else
+    say "  VERIFY ok: AGENTS.md on disk + sentinel present (claude not selected — CLAUDE.md import not required)."
+  fi
 }
 verify_import
 
@@ -194,7 +255,7 @@ verify_import
 say ""; say "[5/6] .gitignore patch:"
 patch_gitignore() {
   local gi="$DEST/.gitignore"
-  local -a needles=("docs/.snapshots/" "docs/.kb-snapshot.md" ".anpunkit-backup-*/" "*.anpunkit-new")
+  local -a needles=("docs/.snapshots/" "docs/.kb-snapshot.md" "docs/evidence/" ".anpunkit-backup-*/" "*.anpunkit-new")
   [ "$DRY" = 1 ] && { act "patch .gitignore (${#needles[@]} entries)"; return 0; }
   touch "$gi"
   for n in "${needles[@]}"; do grep -qxF "$n" "$gi" || printf '%s\n' "$n" >> "$gi"; done
@@ -244,12 +305,14 @@ configure_kb() {
 
 configure_kb
 
-# ---- finalize: stamp the installed manifest (copy the new one)
+# ---- finalize: stamp the installed manifest (copy the new one) + record tools
 if [ "$DRY" != 1 ]; then
   cp -p "$MAN_SRC" "$MAN_DEST" 2>/dev/null || true
+  mkdir -p "$DEST/.claude"
+  node -e "require('fs').writeFileSync(process.argv[1],JSON.stringify({tools:process.argv[2].split(' ').filter(Boolean)},null,2)+'\n')" "$TOOLS_FILE" "$TOOLS" 2>/dev/null || true
   [ -d "$BACKUP" ] && say "" && say "backup written: ${BACKUP#$DEST/}"
 fi
 
-say ""; say "anpunkit setup complete ($MODE). Open Claude Code or Cursor — the SessionStart/sessionStart hook fires automatically."
+say ""; say "anpunkit setup complete ($MODE, tools: $TOOLS). Open Claude Code or Cursor — the SessionStart/sessionStart hook fires automatically."
 if [ "$DRY" = 1 ]; then say "(dry-run: no files were written.)"; fi
 exit 0

package/template/tests/helpers/spec-assert.py

@@ -0,0 +1,162 @@
+"""spec-assert.py — kit-versioned matcher-aware deep-equality comparator (v2.2).
+
+The generated `data` boundary harness (test-author) asserts an actual response
+against `fixtures/<case-id>-expected.json` via `spec_assert(actual, expected)`.
+Deep equality, EXCEPT that volatile fields in the expected fixture carry a matcher
+token instead of a literal (see §5.49). This is the ONLY comparator — no per-project
+assertion logic. One file per supported test language; this is the Python one.
+
+Matcher tokens (string values in the expected fixture):
+
+    "<UUID>"            any UUID v4 string
+    "<ISO8601>"         any ISO 8601 datetime string
+    "<ANY_STRING>"      any non-null string
+    "<ANY_NUMBER>"      any finite number (not bool)
+    "<UNORDERED>"       any array (presence + shape only)
+    "<MATCHES:regex>"   any string matching the pattern (re.search)
+
+Order-insensitive array WITH item checking: wrap the expected array as
+    {"<UNORDERED>": [item, item, ...]}
+and the actual must be a list that is an order-insensitive deep-equal multiset of
+those items.
+
+A matcher token asserts PRESENCE + SHAPE — never "ignore this field". A missing
+volatile field still fails (strict key sets). Extra actual keys also fail.
+
+Usage (pytest or any runner):
+
+    from importlib import import_module
+    spec_assert = import_module("tests.helpers.spec-assert").spec_assert  # if importable
+    # or load directly:
+    #   import importlib.util, pathlib
+    #   spec = importlib.util.spec_from_file_location("spec_assert", ".../spec-assert.py")
+    ...
+    spec_assert(actual, expected)          # raises AssertionError with a JSON path on mismatch
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from numbers import Number
+from pathlib import Path
+from typing import Any
+
+_UUID4 = re.compile(
+    r"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$"
+)
+_ISO8601 = re.compile(
+    r"^\d{4}-\d{2}-\d{2}[Tt ]\d{2}:\d{2}:\d{2}(\.\d+)?([Zz]|[+-]\d{2}:?\d{2})?$"
+)
+_MATCHES_PREFIX = "<MATCHES:"
+
+
+class SpecMismatch(AssertionError):
+    """Raised when actual does not satisfy the expected fixture (with a JSON path)."""
+
+
+def load_fixture(path: str | Path) -> Any:
+    """Convenience loader for fixtures/<case-id>-*.json."""
+    return json.loads(Path(path).read_text(encoding="utf-8"))
+
+
+def _is_real_number(v: Any) -> bool:
+    # bool is a subclass of int in Python — exclude it explicitly.
+    return isinstance(v, Number) and not isinstance(v, bool)
+
+
+def _fail(path: str, msg: str) -> None:
+    raise SpecMismatch(f"spec-assert mismatch at {path}: {msg}")
+
+
+def _match_token(actual: Any, token: str, path: str) -> bool:
+    """Return True if `token` is a known matcher and `actual` satisfies it.
+    Raises on a known token that is NOT satisfied. Returns False if not a token."""
+    if token == "<UUID>":
+        if not (isinstance(actual, str) and _UUID4.match(actual)):
+            _fail(path, f"expected a UUID v4 string, got {actual!r}")
+        return True
+    if token == "<ISO8601>":
+        if not (isinstance(actual, str) and _ISO8601.match(actual)):
+            _fail(path, f"expected an ISO 8601 datetime string, got {actual!r}")
+        return True
+    if token == "<ANY_STRING>":
+        if not isinstance(actual, str):
+            _fail(path, f"expected any string, got {type(actual).__name__}")
+        return True
+    if token == "<ANY_NUMBER>":
+        if not _is_real_number(actual):
+            _fail(path, f"expected any finite number, got {actual!r}")
+        return True
+    if token == "<UNORDERED>":
+        if not isinstance(actual, list):
+            _fail(path, f"expected any array, got {type(actual).__name__}")
+        return True
+    if token.startswith(_MATCHES_PREFIX) and token.endswith(">"):
+        pattern = token[len(_MATCHES_PREFIX):-1]
+        if not (isinstance(actual, str) and re.search(pattern, actual)):
+            _fail(path, f"expected a string matching /{pattern}/, got {actual!r}")
+        return True
+    return False
+
+
+def _unordered_equal(actual: list, items: list, path: str) -> None:
+    if not isinstance(actual, list):
+        _fail(path, f"expected an array (unordered), got {type(actual).__name__}")
+    if len(actual) != len(items):
+        _fail(path, f"array length {len(actual)} != expected {len(items)} (unordered)")
+    remaining = list(actual)
+    for i, exp in enumerate(items):
+        found = -1
+        for j, act in enumerate(remaining):
+            try:
+                spec_assert(act, exp, f"{path}[unordered:{i}]")
+                found = j
+                break
+            except SpecMismatch:
+                continue
+        if found < 0:
+            _fail(path, f"no actual element matches expected item #{i}: {exp!r}")
+        remaining.pop(found)
+
+
+def spec_assert(actual: Any, expected: Any, path: str = "$") -> None:
+    """Assert `actual` deep-equals `expected`, honoring matcher tokens. Raises
+    SpecMismatch (an AssertionError) with a JSON path on the first divergence."""
+    # scalar matcher token
+    if isinstance(expected, str) and _match_token(actual, expected, path):
+        return
+
+    # {"<UNORDERED>": [...]} wrapper → order-insensitive item compare
+    if isinstance(expected, dict) and list(expected.keys()) == ["<UNORDERED>"]:
+        _unordered_equal(actual, expected["<UNORDERED>"], path)
+        return
+
+    if isinstance(expected, dict):
+        if not isinstance(actual, dict):
+            _fail(path, f"expected object, got {type(actual).__name__}")
+        exp_keys, act_keys = set(expected), set(actual)
+        if exp_keys != act_keys:
+            missing = exp_keys - act_keys
+            extra = act_keys - exp_keys
+            _fail(path, f"key mismatch (missing={sorted(missing)}, extra={sorted(extra)})")
+        for k in expected:
+            spec_assert(actual[k], expected[k], f"{path}.{k}")
+        return
+
+    if isinstance(expected, list):
+        if not isinstance(actual, list):
+            _fail(path, f"expected array, got {type(actual).__name__}")
+        if len(actual) != len(expected):
+            _fail(path, f"array length {len(actual)} != expected {len(expected)}")
+        for i, (a, e) in enumerate(zip(actual, expected)):
+            spec_assert(a, e, f"{path}[{i}]")
+        return
+
+    # scalar literal — strict equality (bool/int kept distinct)
+    if type(actual) is not type(expected) and not (
+        _is_real_number(actual) and _is_real_number(expected)
+    ):
+        _fail(path, f"type {type(actual).__name__} != expected {type(expected).__name__}")
+    if actual != expected:
+        _fail(path, f"{actual!r} != expected {expected!r}")