instar 0.26.11 → 0.27.2

package/playbook-scripts/build-state.py

@@ -0,0 +1,529 @@
+#!/usr/bin/env python3
+"""
+Build State Manager for Instar /build skill.
+
+Manages phase transitions, step tracking, worktree lifecycle, audit logging,
+and state persistence for the rigorous build pipeline.
+
+State lives in .instar/state/build/ following Instar's state directory convention.
+Worktree support ensures all /build development happens in isolation.
+
+Commands:
+  init <task> [--size SMALL|STANDARD|LARGE]   Initialize a new build
+  transition <phase> [--evidence TEXT]          Transition to a new phase
+  step-complete <n> <desc> <tests> <passing>   Record a completed step
+  status                                       Show current build status
+  query [--event X] [--phase Y] [--limit N]    Query audit log
+  report                                       Generate build summary
+  complete                                     Mark build as complete
+  resume                                       Check if resumable
+  worktree-create [--branch NAME]              Create isolated worktree
+  worktree-merge                               Merge worktree back to source
+  worktree-cleanup                             Remove worktree
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import subprocess
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+
+STATE_DIR = Path(".instar/state/build")
+STATE_FILE = STATE_DIR / "build-state.json"
+AUDIT_LOG = STATE_DIR / "audit.jsonl"
+PLAN_FILE = STATE_DIR / "plan.md"
+HISTORY_DIR = STATE_DIR / "history"
+
+PHASES = [
+    "idle", "clarify", "planning", "executing",
+    "verifying", "fixing", "hardening",
+    "complete", "failed", "escalated",
+]
+
+TRANSITIONS = {
+    "idle":       ["clarify", "planning", "executing"],
+    "clarify":    ["planning"],
+    "planning":   ["executing"],
+    "executing":  ["verifying", "complete"],
+    "verifying":  ["complete", "fixing", "hardening"],
+    "fixing":     ["verifying", "failed", "escalated"],
+    "hardening":  ["complete"],
+    "complete":   [],
+    "failed":     [],
+    "escalated":  [],
+}
+
+UNIVERSAL_TARGETS = {"failed", "escalated"}
+
+PROTECTION_LEVELS = {
+    "SMALL":    {"reinforcements": 3, "label": "light"},
+    "STANDARD": {"reinforcements": 5, "label": "medium"},
+    "LARGE":    {"reinforcements": 10, "label": "heavy"},
+}
+
+
+def now_iso():
+    return datetime.now(timezone.utc).isoformat()
+
+
+def load_state():
+    if not STATE_FILE.exists():
+        return None
+    try:
+        return json.loads(STATE_FILE.read_text())
+    except (json.JSONDecodeError, IOError):
+        return None
+
+
+def save_state(state):
+    STATE_DIR.mkdir(parents=True, exist_ok=True)
+    STATE_FILE.write_text(json.dumps(state, indent=2))
+
+
+def append_audit(event, data=None):
+    STATE_DIR.mkdir(parents=True, exist_ok=True)
+    entry = {"event": event, "timestamp": now_iso()}
+    if data:
+        entry.update(data)
+    with open(AUDIT_LOG, "a") as f:
+        f.write(json.dumps(entry) + "\n")
+
+
+def read_audit():
+    if not AUDIT_LOG.exists():
+        return []
+    entries = []
+    for line in AUDIT_LOG.read_text().splitlines():
+        if line.strip():
+            try:
+                entries.append(json.loads(line))
+            except json.JSONDecodeError:
+                pass
+    return entries
+
+
+def out(obj):
+    print(json.dumps(obj))
+
+
+def git_run(args, cwd=None):
+    """Run a git command and return (success, stdout, stderr)."""
+    result = subprocess.run(
+        ["git"] + args, capture_output=True, text=True, cwd=cwd)
+    return result.returncode == 0, result.stdout.strip(), result.stderr.strip()
+
+
+# ─── Worktree Commands ──────────────────────────────────────────
+
+def cmd_worktree_create(args):
+    """Create an isolated git worktree for the build."""
+    state = load_state()
+    if not state:
+        out({"error": "No active build. Run 'init' first."})
+        sys.exit(1)
+
+    if state.get("worktree"):
+        out({"error": "Worktree already exists",
+             "path": state["worktree"]["path"],
+             "branch": state["worktree"]["branch"]})
+        sys.exit(1)
+
+    # Determine branch name
+    task_slug = state["task"][:40].lower()
+    task_slug = "".join(c if c.isalnum() or c == "-" else "-" for c in task_slug)
+    task_slug = task_slug.strip("-")
+    branch = args.branch or ("build/%s" % task_slug)
+
+    # Get current branch
+    ok, current_branch, _ = git_run(["rev-parse", "--abbrev-ref", "HEAD"])
+    if not ok:
+        out({"error": "Not in a git repo"})
+        sys.exit(1)
+
+    # Create worktree path
+    worktree_path = ".instar/worktrees/%s" % branch.replace("/", "-")
+
+    # Create the worktree with a new branch
+    ok, stdout, stderr = git_run(
+        ["worktree", "add", "-b", branch, worktree_path, current_branch])
+    if not ok:
+        # Branch might exist already, try without -b
+        ok, stdout, stderr = git_run(
+            ["worktree", "add", worktree_path, branch])
+        if not ok:
+            out({"error": "Failed to create worktree",
+                 "stderr": stderr})
+            sys.exit(1)
+
+    state["worktree"] = {
+        "path": worktree_path,
+        "branch": branch,
+        "sourceBranch": current_branch,
+        "createdAt": now_iso(),
+    }
+    save_state(state)
+    append_audit("worktree.created", {
+        "path": worktree_path, "branch": branch,
+        "sourceBranch": current_branch})
+
+    out({"status": "worktree_created",
+         "path": worktree_path, "branch": branch,
+         "sourceBranch": current_branch,
+         "instruction": "cd %s to work in isolation" % worktree_path})
+
+
+def cmd_worktree_merge(args):
+    """Merge worktree branch back to source."""
+    state = load_state()
+    if not state or not state.get("worktree"):
+        out({"error": "No active worktree"})
+        sys.exit(1)
+
+    wt = state["worktree"]
+    source = wt["sourceBranch"]
+    branch = wt["branch"]
+
+    # Merge the build branch into source
+    ok, stdout, stderr = git_run(["merge", branch, "--no-ff",
+                                   "-m", "Merge build/%s" % branch])
+    if not ok:
+        out({"error": "Merge conflict",
+             "stderr": stderr,
+             "action": "Resolve conflicts manually, then run worktree-cleanup"})
+        sys.exit(1)
+
+    append_audit("worktree.merged", {
+        "branch": branch, "into": source})
+
+    out({"status": "merged", "branch": branch, "into": source})
+
+
+def cmd_worktree_cleanup(args):
+    """Remove the worktree."""
+    state = load_state()
+    if not state or not state.get("worktree"):
+        out({"error": "No active worktree"})
+        sys.exit(1)
+
+    wt = state["worktree"]
+    worktree_path = wt["path"]
+    branch = wt["branch"]
+
+    # Remove worktree
+    git_run(["worktree", "remove", worktree_path, "--force"])
+
+    # Optionally delete the branch
+    git_run(["branch", "-d", branch])
+
+    state["worktree"] = None
+    save_state(state)
+    append_audit("worktree.cleaned", {"path": worktree_path, "branch": branch})
+
+    out({"status": "cleaned", "path": worktree_path, "branch": branch})
+
+
+# ─── Core Commands ───────────────────────────────────────────────
+
+def cmd_init(args):
+    existing = load_state()
+    if existing and existing.get("phase") not in ("complete", "failed", "escalated"):
+        out({"error": "Active build exists", "phase": existing["phase"],
+             "task": existing["task"], "hint": "Use 'complete' or 'resume' first"})
+        sys.exit(1)
+
+    size = (args.size or "STANDARD").upper()
+    if size not in PROTECTION_LEVELS:
+        out({"error": "Invalid size. Use SMALL, STANDARD, or LARGE"})
+        sys.exit(1)
+
+    state = {
+        "task": args.task, "phase": "idle", "size": size,
+        "protection": PROTECTION_LEVELS[size],
+        "startedAt": now_iso(), "completedAt": None,
+        "currentStep": 0, "totalSteps": 0, "steps": [],
+        "totalTests": 0, "allPassing": True,
+        "fixIterations": 0, "maxFixIterations": 3,
+        "verifyIterations": 0, "maxVerifyIterations": 3,
+        "reinforcementsUsed": 0,
+        "worktree": None,
+    }
+    save_state(state)
+    append_audit("build.initialized", {"task": args.task, "size": size})
+    out({"status": "initialized", "task": args.task, "size": size,
+         "protection": PROTECTION_LEVELS[size]["label"],
+         "reinforcements": PROTECTION_LEVELS[size]["reinforcements"]})
+
+
+def cmd_transition(args):
+    state = load_state()
+    if not state:
+        out({"error": "No active build. Run 'init' first."})
+        sys.exit(1)
+
+    current = state["phase"]
+    target = args.phase
+
+    if target not in PHASES:
+        out({"error": "Invalid phase: %s" % target, "valid": PHASES})
+        sys.exit(1)
+
+    legal = TRANSITIONS.get(current, [])
+    if target not in legal and target not in UNIVERSAL_TARGETS:
+        out({"error": "Cannot transition %s -> %s" % (current, target),
+             "legal_targets": list(set(legal) | UNIVERSAL_TARGETS)})
+        sys.exit(1)
+
+    if target == "fixing":
+        state["fixIterations"] = state.get("fixIterations", 0) + 1
+        if state["fixIterations"] > state.get("maxFixIterations", 3):
+            state["phase"] = "escalated"
+            save_state(state)
+            append_audit("build.escalated", {
+                "reason": "max_fix_iterations",
+                "iterations": state["fixIterations"]})
+            out({"error": "Max fix iterations exceeded", "action": "escalated"})
+            sys.exit(1)
+
+    if current == "fixing" and target == "verifying":
+        state["verifyIterations"] = state.get("verifyIterations", 0) + 1
+
+    old = state["phase"]
+    state["phase"] = target
+    save_state(state)
+    append_audit("phase.transition", {
+        "from": old, "to": target,
+        "evidence": args.evidence or None})
+    out({"status": "transitioned", "from": old, "to": target})
+
+
+def cmd_step_complete(args):
+    state = load_state()
+    if not state:
+        out({"error": "No active build."})
+        sys.exit(1)
+    if state["phase"] != "executing":
+        out({"error": "Not in executing phase (currently: %s)" % state["phase"]})
+        sys.exit(1)
+
+    step = {
+        "step": args.step_number, "description": args.description,
+        "tests": args.tests, "passing": args.passing,
+        "timestamp": now_iso(),
+    }
+    state["steps"].append(step)
+    state["currentStep"] = args.step_number
+    state["totalTests"] = sum(s["tests"] for s in state["steps"])
+    state["allPassing"] = all(s["tests"] == s["passing"] for s in state["steps"])
+    save_state(state)
+    append_audit("step.completed", {
+        "step": args.step_number, "description": args.description,
+        "tests": args.tests, "passing": args.passing,
+        "totalTests": state["totalTests"]})
+    out({"status": "step_completed", "step": args.step_number,
+         "tests": args.tests, "passing": args.passing,
+         "totalTests": state["totalTests"], "allPassing": state["allPassing"]})
+
+
+def cmd_status(_args):
+    state = load_state()
+    if not state:
+        out({"status": "no_active_build"})
+        return
+
+    elapsed = None
+    if state.get("startedAt"):
+        try:
+            started = datetime.fromisoformat(
+                state["startedAt"].replace("Z", "+00:00"))
+            elapsed = (datetime.now(timezone.utc) - started).total_seconds() / 60
+        except ValueError:
+            pass
+
+    result = {
+        "task": state["task"], "phase": state["phase"],
+        "size": state["size"],
+        "protection": state.get("protection", {}).get("label", "unknown"),
+        "currentStep": state["currentStep"],
+        "stepsCompleted": len(state["steps"]),
+        "totalTests": state["totalTests"],
+        "allPassing": state["allPassing"],
+        "fixIterations": state.get("fixIterations", 0),
+        "verifyIterations": state.get("verifyIterations", 0),
+        "reinforcementsUsed": state.get("reinforcementsUsed", 0),
+        "elapsedMinutes": round(elapsed, 1) if elapsed else None,
+    }
+    if state.get("worktree"):
+        result["worktree"] = state["worktree"]
+    out(result)
+
+
+def cmd_query(args):
+    entries = read_audit()
+    if args.event:
+        entries = [e for e in entries if e.get("event") == args.event]
+    if args.phase:
+        entries = [e for e in entries
+                   if e.get("to") == args.phase or e.get("from") == args.phase]
+    limit = args.limit or 50
+    out({"count": len(entries[-limit:]), "entries": entries[-limit:]})
+
+
+def cmd_report(_args):
+    state = load_state()
+    if not state:
+        print("No active build.")
+        return
+
+    entries = read_audit()
+    elapsed_str = "unknown"
+    if state.get("startedAt"):
+        try:
+            started = datetime.fromisoformat(
+                state["startedAt"].replace("Z", "+00:00"))
+            end = datetime.now(timezone.utc)
+            if state.get("completedAt"):
+                end = datetime.fromisoformat(
+                    state["completedAt"].replace("Z", "+00:00"))
+            elapsed_str = "%d min" % ((end - started).total_seconds() / 60)
+        except ValueError:
+            pass
+
+    event_counts = {}
+    for e in entries:
+        k = e.get("event", "unknown")
+        event_counts[k] = event_counts.get(k, 0) + 1
+
+    lines = [
+        "BUILD REPORT: %s" % state["task"], "",
+        "Status: %s" % state["phase"],
+        "Size: %s (%s protection)" % (
+            state["size"], state.get("protection", {}).get("label", "?")),
+        "Duration: %s" % elapsed_str,
+        "Steps: %d" % len(state["steps"]),
+        "Tests: %d (all passing: %s)" % (state["totalTests"], state["allPassing"]),
+        "Fix cycles: %d/%d" % (
+            state.get("fixIterations", 0), state.get("maxFixIterations", 3)),
+    ]
+    if state.get("worktree"):
+        lines.append("Worktree: %s (branch: %s)" % (
+            state["worktree"]["path"], state["worktree"]["branch"]))
+    lines.append("")
+    for s in state["steps"]:
+        tag = "PASS" if s["tests"] == s["passing"] else "FAIL"
+        lines.append("  Step %d: %s [%d tests, %s]" % (
+            s["step"], s["description"], s["tests"], tag))
+    if event_counts:
+        lines.append("")
+        lines.append("Audit events:")
+        for k, v in sorted(event_counts.items()):
+            lines.append("  %s: %d" % (k, v))
+    print("\n".join(lines))
+
+
+def cmd_complete(_args):
+    state = load_state()
+    if not state:
+        out({"error": "No active build."})
+        sys.exit(1)
+    if not state["allPassing"]:
+        out({"error": "Cannot complete: not all tests passing"})
+        sys.exit(1)
+
+    state["phase"] = "complete"
+    state["completedAt"] = now_iso()
+    save_state(state)
+    append_audit("build.complete", {
+        "task": state["task"], "totalTests": state["totalTests"],
+        "stepsCompleted": len(state["steps"]),
+        "fixIterations": state.get("fixIterations", 0)})
+
+    HISTORY_DIR.mkdir(parents=True, exist_ok=True)
+    ts = datetime.now().strftime("%Y%m%d-%H%M%S")
+    hist = HISTORY_DIR / ("build-%s.json" % ts)
+    hist.write_text(json.dumps(state, indent=2))
+
+    out({"status": "complete", "task": state["task"],
+         "totalTests": state["totalTests"],
+         "stepsCompleted": len(state["steps"]),
+         "archivedTo": str(hist)})
+
+
+def cmd_resume(_args):
+    state = load_state()
+    if not state:
+        out({"canResume": False, "reason": "No active build found"})
+        return
+    if state["phase"] in ("complete", "failed", "escalated"):
+        out({"canResume": False,
+             "reason": "Terminal state: %s" % state["phase"]})
+        return
+    result = {
+        "canResume": True, "task": state["task"],
+        "phase": state["phase"], "size": state["size"],
+        "currentStep": state["currentStep"],
+        "stepsCompleted": len(state["steps"]),
+        "totalTests": state["totalTests"],
+        "allPassing": state["allPassing"],
+        "planExists": PLAN_FILE.exists(),
+    }
+    if state.get("worktree"):
+        result["worktree"] = state["worktree"]
+    out(result)
+
+
+def main():
+    p = argparse.ArgumentParser(description="Instar Build State Manager")
+    sub = p.add_subparsers(dest="command")
+
+    s = sub.add_parser("init")
+    s.add_argument("task")
+    s.add_argument("--size", choices=["SMALL", "STANDARD", "LARGE"],
+                   default="STANDARD")
+
+    s = sub.add_parser("transition")
+    s.add_argument("phase")
+    s.add_argument("--evidence")
+
+    s = sub.add_parser("step-complete")
+    s.add_argument("step_number", type=int)
+    s.add_argument("description")
+    s.add_argument("tests", type=int)
+    s.add_argument("passing", type=int)
+
+    sub.add_parser("status")
+
+    s = sub.add_parser("query")
+    s.add_argument("--event")
+    s.add_argument("--phase")
+    s.add_argument("--limit", type=int, default=50)
+
+    sub.add_parser("report")
+    sub.add_parser("complete")
+    sub.add_parser("resume")
+
+    s = sub.add_parser("worktree-create")
+    s.add_argument("--branch")
+
+    sub.add_parser("worktree-merge")
+    sub.add_parser("worktree-cleanup")
+
+    args = p.parse_args()
+    if not args.command:
+        p.print_help()
+        sys.exit(1)
+
+    {
+        "init": cmd_init, "transition": cmd_transition,
+        "step-complete": cmd_step_complete, "status": cmd_status,
+        "query": cmd_query, "report": cmd_report,
+        "complete": cmd_complete, "resume": cmd_resume,
+        "worktree-create": cmd_worktree_create,
+        "worktree-merge": cmd_worktree_merge,
+        "worktree-cleanup": cmd_worktree_cleanup,
+    }[args.command](args)
+
+
+if __name__ == "__main__":
+    main()

package/scripts/check-contract-evidence.js

@@ -0,0 +1,103 @@
+#!/usr/bin/env node
+/**
+ * Pre-publish contract evidence check.
+ *
+ * If any messaging adapter source files have been modified since the last
+ * published version, this script requires fresh contract test evidence.
+ *
+ * This is the FINAL gate before `npm publish`. It catches the exact scenario
+ * that burned us: shipping integration code verified only by mocked unit tests.
+ *
+ * Bypass (emergency only): SKIP_CONTRACT_CHECK=1 npm publish
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { execSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const ROOT = path.resolve(__dirname, '..');
+
+if (process.env.SKIP_CONTRACT_CHECK === '1') {
+  console.log('  ⚠️  SKIP_CONTRACT_CHECK=1 — bypassing contract evidence check');
+  console.log('  You are publishing adapter changes WITHOUT verified API testing.\n');
+  process.exit(0);
+}
+
+const ADAPTER_PATHS = [
+  'src/messaging/slack/',
+  'src/messaging/telegram/',
+  'src/messaging/whatsapp/',
+  'src/messaging/imessage/',
+];
+
+// Check if adapter files changed since last tag
+let adapterChanges = [];
+try {
+  // Find files changed since the last npm version tag
+  const lastTag = execSync('git describe --tags --abbrev=0 2>/dev/null || echo ""', {
+    encoding: 'utf-8',
+    cwd: ROOT,
+  }).trim();
+
+  const diffBase = lastTag || 'HEAD~10';
+  const changedFiles = execSync(`git diff --name-only ${diffBase}...HEAD 2>/dev/null || echo ""`, {
+    encoding: 'utf-8',
+    cwd: ROOT,
+  }).trim().split('\n').filter(Boolean);
+
+  adapterChanges = changedFiles.filter(f =>
+    ADAPTER_PATHS.some(prefix => f.startsWith(prefix))
+  );
+} catch {
+  // If git fails, be conservative — check for evidence anyway
+  adapterChanges = ['(unable to determine — checking evidence anyway)'];
+}
+
+if (adapterChanges.length === 0) {
+  // No adapter changes — no contract evidence required
+  process.exit(0);
+}
+
+console.log(`\n  📋 Adapter files modified (${adapterChanges.length}):`);
+adapterChanges.slice(0, 5).forEach(f => console.log(`     • ${f}`));
+if (adapterChanges.length > 5) console.log(`     • ...and ${adapterChanges.length - 5} more`);
+
+// Check evidence file
+const evidencePath = path.join(ROOT, '.contract-test-evidence.json');
+
+if (!fs.existsSync(evidencePath)) {
+  console.log('\n  ❌ No contract test evidence found.');
+  console.log('  You MUST run contract tests before publishing adapter changes:\n');
+  console.log('    SLACK_CONTRACT_BOT_TOKEN=xoxb-... npm run test:contract\n');
+  console.log('  This verifies your changes work against the REAL API.');
+  console.log('  Emergency bypass: SKIP_CONTRACT_CHECK=1 npm publish\n');
+  process.exit(1);
+}
+
+try {
+  const evidence = JSON.parse(fs.readFileSync(evidencePath, 'utf-8'));
+  const ageMs = Date.now() - (evidence.timestamp || 0);
+  const maxAgeMs = 4 * 60 * 60 * 1000; // 4 hours
+
+  if (!evidence.passed) {
+    console.log('\n  ❌ Contract tests FAILED on their last run.');
+    console.log('  Fix the failures and re-run: npm run test:contract\n');
+    process.exit(1);
+  }
+
+  if (ageMs > maxAgeMs) {
+    const hoursAgo = Math.round(ageMs / 3600000);
+    console.log(`\n  ❌ Contract test evidence is stale (${hoursAgo}h old, max 4h).`);
+    console.log('  Re-run: SLACK_CONTRACT_BOT_TOKEN=xoxb-... npm run test:contract\n');
+    process.exit(1);
+  }
+
+  const minutesAgo = Math.round(ageMs / 60000);
+  console.log(`\n  ✅ Contract tests passed ${minutesAgo}m ago — evidence valid\n`);
+
+} catch (err) {
+  console.log('\n  ❌ Contract evidence file is corrupt. Re-run: npm run test:contract\n');
+  process.exit(1);
+}

package/scripts/pre-push-gate.js

@@ -146,6 +146,59 @@ try {
       (srcChanges.length > 5 ? `\n      • ...and ${srcChanges.length - 5} more` : '')
     );
   }
+  // ── 4. Adapter contract test gate ─────────────────────────────────────
+  // If messaging adapter source files changed, require contract test evidence.
+  // This prevents shipping integration code verified only by mocked unit tests.
+  // The evidence file is created by `npm run test:contract` when tests pass.
+
+  const ADAPTER_PATHS = [
+    'src/messaging/slack/',
+    'src/messaging/telegram/',
+    'src/messaging/whatsapp/',
+    'src/messaging/imessage/',
+  ];
+
+  const adapterChanges = srcChanges.filter(f =>
+    ADAPTER_PATHS.some(prefix => f.startsWith(prefix))
+  );
+
+  if (adapterChanges.length > 0) {
+    const evidencePath = path.join(ROOT, '.contract-test-evidence.json');
+    let evidenceValid = false;
+
+    if (fs.existsSync(evidencePath)) {
+      try {
+        const evidence = JSON.parse(fs.readFileSync(evidencePath, 'utf-8'));
+        const ageMs = Date.now() - (evidence.timestamp || 0);
+        const maxAgeMs = 4 * 60 * 60 * 1000; // 4 hours
+
+        if (ageMs < maxAgeMs && evidence.passed === true) {
+          evidenceValid = true;
+          const ageMin = Math.round(ageMs / 60000);
+          console.log(`  ✅ Contract tests passed ${ageMin}m ago (${evidence.suite})`);
+        } else if (ageMs >= maxAgeMs) {
+          console.log(`  ⏰ Contract test evidence is stale (${Math.round(ageMs / 3600000)}h old)`);
+        } else if (!evidence.passed) {
+          console.log(`  ❌ Contract test evidence shows FAILURE`);
+        }
+      } catch {
+        // Corrupt evidence file
+      }
+    }
+
+    if (!evidenceValid) {
+      errors.push(
+        `Adapter source files changed but no recent contract test evidence found.\n` +
+        `      Adapter files modified:\n` +
+        adapterChanges.slice(0, 5).map(f => `        • ${f}`).join('\n') +
+        (adapterChanges.length > 5 ? `\n        • ...and ${adapterChanges.length - 5} more` : '') +
+        `\n\n      Run contract tests against the REAL API before pushing:\n` +
+        `        SLACK_CONTRACT_BOT_TOKEN=xoxb-... npm run test:contract\n\n` +
+        `      This ensures your changes work against the actual API, not just mocked responses.\n` +
+        `      Contract test evidence expires after 4 hours.`
+      );
+    }
+  }
 } catch {
   // Git commands may fail in CI or detached HEAD — skip gracefully
 }