docs: add blocked sync Teams warning plan

docs/superpowers/plans/2026-07-01-blocked-sync-teams-warnings.md

@@ -0,0 +1,522 @@
+# Blocked Sync Teams Warnings Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Send a Teams warning whenever the local NowAI-Bench sync wrapper blocks a run before `sync.mjs` starts.
+
+**Architecture:** Keep preflight ownership in `~/.nowai-sync/nowai-sync-cron.sh`, but move blocked-warning message formatting into repo-owned Node code that reuses `lib/teams.mjs`. The wrapper stays thin: it detects blocked states, passes a normalized reason plus facts to the repo notifier, and exits without running `sync.mjs`.
+
+**Tech Stack:** Node 20 ESM, `node:test`, bash, git, Power Automate Teams webhook
+
+---
+
+## File Structure
+
+- Create: `.claude/skills/sync-nowai-leaderboard/lib/blocked-notify.mjs` — pure helpers for blocked reason labels, timestamp subtitle, and CLI argument parsing.
+- Create: `.claude/skills/sync-nowai-leaderboard/notify-blocked.mjs` — CLI entrypoint the wrapper calls to post a blocked warning card.
+- Create: `.claude/skills/sync-nowai-leaderboard/test/blocked-notify.test.mjs` — unit tests for reason mapping and CLI argument parsing.
+- Create: `.claude/skills/sync-nowai-leaderboard/test/notify-blocked-cli.test.mjs` — smoke test for the CLI entrypoint without a webhook configured.
+- Modify: `.claude/skills/sync-nowai-leaderboard/SKILL.md` — document blocked preflight Teams warnings.
+- Modify: `~/.nowai-sync/nowai-sync-cron.sh` — add dirty-worktree precheck and call the repo notifier for every blocked state.
+- Modify: `~/.nowai-sync/DESIGN.md` — document the new blocked-warning flow and the safe clone-based smoke tests.
+- Existing: `docs/superpowers/specs/2026-07-01-blocked-sync-teams-warnings-design.md` — approved design record.
+- Create: `docs/superpowers/plans/2026-07-01-blocked-sync-teams-warnings.md` — this implementation handoff.
+
+### Task 1: Add a tested blocked-notification builder
+
+**Files:**
+- Create: `.claude/skills/sync-nowai-leaderboard/lib/blocked-notify.mjs`
+- Create: `.claude/skills/sync-nowai-leaderboard/test/blocked-notify.test.mjs`
+
+- [ ] **Step 1: Write the failing unit test**
+
+Create `.claude/skills/sync-nowai-leaderboard/test/blocked-notify.test.mjs`:
+
+```js
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import {
+  buildBlockedNotification,
+  parseBlockedCliArgs,
+} from '../lib/blocked-notify.mjs';
+
+test('buildBlockedNotification maps dirty-worktree to a warning card payload', () => {
+  const out = buildBlockedNotification({
+    reason: 'dirty-worktree',
+    facts: [['Branch', 'main'], ['Files', '3']],
+    now: new Date('2026-07-01T21:00:00Z'),
+  });
+
+  assert.equal(out.kind, 'warning');
+  assert.equal(out.title, '⚠️ Leaderboard sync blocked');
+  assert.equal(out.subtitle, 'NowAI-Bench Sync · 2026-07-01 21:00 UTC');
+  assert.deepEqual(out.facts, [
+    ['Reason', 'Worktree has uncommitted files'],
+    ['Branch', 'main'],
+    ['Files', '3'],
+  ]);
+});
+
+test('parseBlockedCliArgs accepts repeated --fact pairs', () => {
+  const out = parseBlockedCliArgs([
+    '--reason', 'behind-or-diverged',
+    '--fact', 'Branch=main',
+    '--fact', 'RemoteAhead=2',
+    '--fact', 'LocalAhead=0',
+  ]);
+
+  assert.equal(out.reason, 'behind-or-diverged');
+  assert.deepEqual(out.facts, [
+    ['Branch', 'main'],
+    ['RemoteAhead', '2'],
+    ['LocalAhead', '0'],
+  ]);
+});
+
+test('parseBlockedCliArgs rejects unknown blocked reasons', () => {
+  assert.throws(
+    () => parseBlockedCliArgs(['--reason', 'mystery-reason']),
+    /Unknown blocked reason: mystery-reason/,
+  );
+});
+
+test('parseBlockedCliArgs rejects malformed fact entries', () => {
+  assert.throws(
+    () => parseBlockedCliArgs(['--reason', 'wrong-branch', '--fact', 'Branch']),
+    /Invalid --fact, expected key=value: Branch/,
+  );
+});
+```
+
+- [ ] **Step 2: Run the new test and confirm it fails**
+
+Run:
+
+```bash
+cd .claude/skills/sync-nowai-leaderboard
+node --test test/blocked-notify.test.mjs
+```
+
+Expected: FAIL with `Cannot find module '../lib/blocked-notify.mjs'`.
+
+- [ ] **Step 3: Write the minimal implementation**
+
+Create `.claude/skills/sync-nowai-leaderboard/lib/blocked-notify.mjs`:
+
+```js
+const REASON_LABELS = {
+  'dirty-worktree': 'Worktree has uncommitted files',
+  'wrong-branch': 'Current branch is not main',
+  'fetch-failed': 'git fetch origin main failed',
+  'behind-or-diverged': 'Local main is behind or diverged from origin/main',
+};
+
+export function blockedSubtitle(now = new Date()) {
+  return 'NowAI-Bench Sync · ' + now.toISOString().replace('T', ' ').slice(0, 16) + ' UTC';
+}
+
+export function buildBlockedNotification({ reason, facts = [], now = new Date() }) {
+  const label = REASON_LABELS[reason];
+  if (!label) throw new Error(`Unknown blocked reason: ${reason}`);
+
+  return {
+    kind: 'warning',
+    title: '⚠️ Leaderboard sync blocked',
+    subtitle: blockedSubtitle(now),
+    facts: [['Reason', label], ...facts],
+  };
+}
+
+export function parseBlockedCliArgs(argv) {
+  const facts = [];
+  let reason;
+
+  for (let i = 0; i < argv.length; i++) {
+    const token = argv[i];
+
+    if (token === '--reason') {
+      reason = argv[++i];
+      continue;
+    }
+
+    if (token === '--fact') {
+      const raw = argv[++i] ?? '';
+      const eq = raw.indexOf('=');
+      if (eq <= 0) throw new Error(`Invalid --fact, expected key=value: ${raw}`);
+      facts.push([raw.slice(0, eq), raw.slice(eq + 1)]);
+      continue;
+    }
+
+    throw new Error(`Unknown argument: ${token}`);
+  }
+
+  if (!reason) throw new Error('Missing required --reason');
+
+  // Reuse payload validation so the CLI parser and notifier stay in lockstep.
+  buildBlockedNotification({ reason, facts, now: new Date(0) });
+
+  return { reason, facts };
+}
+```
+
+- [ ] **Step 4: Run the test again and confirm it passes**
+
+Run:
+
+```bash
+cd .claude/skills/sync-nowai-leaderboard
+node --test test/blocked-notify.test.mjs
+```
+
+Expected: PASS with 4 passing tests.
+
+- [ ] **Step 5: Commit the repo-tracked change**
+
+```bash
+git add \
+  .claude/skills/sync-nowai-leaderboard/lib/blocked-notify.mjs \
+  .claude/skills/sync-nowai-leaderboard/test/blocked-notify.test.mjs
+git commit -m "feat: add blocked sync notification builder"
+```
+
+### Task 2: Add the CLI entrypoint the wrapper will call
+
+**Files:**
+- Create: `.claude/skills/sync-nowai-leaderboard/notify-blocked.mjs`
+- Create: `.claude/skills/sync-nowai-leaderboard/test/notify-blocked-cli.test.mjs`
+
+- [ ] **Step 1: Write the failing CLI smoke test**
+
+Create `.claude/skills/sync-nowai-leaderboard/test/notify-blocked-cli.test.mjs`:
+
+```js
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+const ENTRY = fileURLToPath(new URL('../notify-blocked.mjs', import.meta.url));
+
+test('notify-blocked CLI exits 1 when no Teams webhook is configured', () => {
+  const res = spawnSync(
+    process.execPath,
+    [ENTRY, '--reason', 'wrong-branch', '--fact', 'Branch=feature/demo'],
+    {
+      env: { ...process.env, TEAMS_WEBHOOK_URL: '' },
+      encoding: 'utf8',
+    },
+  );
+
+  assert.equal(res.status, 1);
+  assert.match(res.stdout, /no TEAMS_WEBHOOK_URL set; skipping card/);
+  assert.match(res.stdout, /\[teams\] not posted\./);
+  assert.equal(res.stderr, '');
+});
+```
+
+- [ ] **Step 2: Run the CLI smoke test and confirm it fails**
+
+Run:
+
+```bash
+cd .claude/skills/sync-nowai-leaderboard
+node --test test/notify-blocked-cli.test.mjs
+```
+
+Expected: FAIL because `notify-blocked.mjs` does not exist yet.
+
+- [ ] **Step 3: Implement the CLI entrypoint**
+
+Create `.claude/skills/sync-nowai-leaderboard/notify-blocked.mjs`:
+
+```js
+#!/usr/bin/env node
+import { postTeams } from './lib/teams.mjs';
+import {
+  buildBlockedNotification,
+  parseBlockedCliArgs,
+} from './lib/blocked-notify.mjs';
+
+const isMain = import.meta.url === `file://${process.argv[1]}`;
+
+if (isMain) {
+  try {
+    const { reason, facts } = parseBlockedCliArgs(process.argv.slice(2));
+    const ok = await postTeams(buildBlockedNotification({ reason, facts }));
+    console.log(ok ? '[teams] posted.' : '[teams] not posted.');
+    process.exit(ok ? 0 : 1);
+  } catch (e) {
+    console.error('[teams] invalid blocked notification args: ' + e.message);
+    process.exit(2);
+  }
+}
+```
+
+- [ ] **Step 4: Run the targeted tests and confirm both pass**
+
+Run:
+
+```bash
+cd .claude/skills/sync-nowai-leaderboard
+node --test test/blocked-notify.test.mjs test/notify-blocked-cli.test.mjs
+```
+
+Expected: PASS with both test files green.
+
+- [ ] **Step 5: Commit the repo-tracked change**
+
+```bash
+git add \
+  .claude/skills/sync-nowai-leaderboard/notify-blocked.mjs \
+  .claude/skills/sync-nowai-leaderboard/test/notify-blocked-cli.test.mjs
+git commit -m "feat: add blocked sync Teams notifier cli"
+```
+
+### Task 3: Wire blocked preflight notifications into the local wrapper
+
+**Files:**
+- Modify: `~/.nowai-sync/nowai-sync-cron.sh`
+
+- [ ] **Step 1: Make the wrapper repo path overridable and add a blocked-notify helper**
+
+Update the top of `~/.nowai-sync/nowai-sync-cron.sh` so clone-based smoke tests can point at a temporary repo without editing the script:
+
+```bash
+REPO="${REPO:-/Users/bradley.cleveland/git/hf/NowAI-Bench}"
+SYNC="$REPO/.claude/skills/sync-nowai-leaderboard/sync.mjs"
+BLOCKED_NOTIFY="$REPO/.claude/skills/sync-nowai-leaderboard/notify-blocked.mjs"
+STAGING_URL="https://huggingface.co/spaces/ServiceNow-AI/NowAI-Bench-Staging"
+LOG="$HOME/Library/Logs/nowai-sync.log"
+NOTIFIER="/opt/homebrew/bin/terminal-notifier"
+TITLE="NowAI-Bench Sync"
+```
+
+Add this helper below `fail()`:
+
+```bash
+blocked() {
+  local reason="$1" message="$2"
+  shift 2
+
+  log "BLOCKED: $reason - $message"
+  notify "Skipped" "$message" "Basso"
+
+  if [ -f "$BLOCKED_NOTIFY" ]; then
+    if ! node "$BLOCKED_NOTIFY" --reason "$reason" "$@" >>"$LOG" 2>&1; then
+      log "WARN: Teams blocked-notify failed for $reason"
+    fi
+  else
+    log "WARN: blocked notifier missing: $BLOCKED_NOTIFY"
+  fi
+
+  exit 0
+}
+```
+
+- [ ] **Step 2: Add the dirty-worktree precheck before fetch**
+
+Insert this after the branch lookup:
+
+```bash
+branch="$(git rev-parse --abbrev-ref HEAD 2>/dev/null)"
+if [ "$branch" != "main" ]; then
+  blocked "wrong-branch" \
+    "On branch '$branch', not main. No sync run." \
+    --fact "Branch=$branch" \
+    --fact "Expected=main"
+fi
+
+dirty_count="$(git status --porcelain | wc -l | tr -d ' ')"
+if [ "$dirty_count" != "0" ]; then
+  blocked "dirty-worktree" \
+    "Worktree has uncommitted files. Sync did not run." \
+    --fact "Branch=$branch" \
+    --fact "Files=$dirty_count"
+fi
+```
+
+- [ ] **Step 3: Convert fetch and behind/diverged skips to blocked Teams warnings**
+
+Replace the current `git fetch` / `merge-base` section with:
+
+```bash
+if ! fetch_out="$(git fetch origin main 2>&1)"; then
+  fetch_tail="$(printf '%s' "$fetch_out" | tail -n1)"
+  blocked "fetch-failed" \
+    "git fetch origin main failed. Sync did not run." \
+    --fact "Remote=origin/main" \
+    --fact "Error=${fetch_tail:-unknown}"
+fi
+
+if ! git merge-base --is-ancestor origin/main HEAD 2>/dev/null; then
+  counts="$(git rev-list --left-right --count origin/main...HEAD 2>/dev/null || printf 'unknown unknown')"
+  remote_ahead="${counts%% *}"
+  local_ahead="${counts##* }"
+  blocked "behind-or-diverged" \
+    "Local main is behind or diverged from staging. Reconcile manually, then it resumes." \
+    --fact "Branch=$branch" \
+    --fact "RemoteAhead=$remote_ahead" \
+    --fact "LocalAhead=$local_ahead"
+fi
+```
+
+- [ ] **Step 4: Verify the dirty-worktree blocked path with a temporary clone**
+
+Run:
+
+```bash
+rm -rf /tmp/nowai-bench-dirty
+git clone . /tmp/nowai-bench-dirty
+touch /tmp/nowai-bench-dirty/.blocked-sync-smoke
+REPO=/tmp/nowai-bench-dirty /bin/bash ~/.nowai-sync/nowai-sync-cron.sh
+rm -rf /tmp/nowai-bench-dirty
+```
+
+Expected:
+- desktop toast says the run was skipped
+- `~/Library/Logs/nowai-sync.log` gains a `BLOCKED: dirty-worktree` line
+- Teams receives `⚠️ Leaderboard sync blocked` with `Reason = Worktree has uncommitted files`
+
+- [ ] **Step 5: Verify the wrong-branch blocked path with a temporary clone**
+
+Run:
+
+```bash
+rm -rf /tmp/nowai-bench-wrong-branch
+git clone . /tmp/nowai-bench-wrong-branch
+git -C /tmp/nowai-bench-wrong-branch switch -c blocked-sync-smoke
+REPO=/tmp/nowai-bench-wrong-branch /bin/bash ~/.nowai-sync/nowai-sync-cron.sh
+rm -rf /tmp/nowai-bench-wrong-branch
+```
+
+Expected:
+- log shows `BLOCKED: wrong-branch`
+- Teams card includes `Branch = blocked-sync-smoke`
+
+- [ ] **Step 6: Verify the behind/diverged blocked path with a temporary clone**
+
+Run:
+
+```bash
+rm -rf /tmp/nowai-bench-behind
+git clone . /tmp/nowai-bench-behind
+git -C /tmp/nowai-bench-behind checkout -B main origin/main~1
+REPO=/tmp/nowai-bench-behind /bin/bash ~/.nowai-sync/nowai-sync-cron.sh
+rm -rf /tmp/nowai-bench-behind
+```
+
+Expected:
+- log shows `BLOCKED: behind-or-diverged`
+- Teams card includes `RemoteAhead` of at least `1`
+
+- [ ] **Step 7: Verify the fetch-failed blocked path with a temporary clone**
+
+Run:
+
+```bash
+rm -rf /tmp/nowai-bench-fetch
+git clone . /tmp/nowai-bench-fetch
+git -C /tmp/nowai-bench-fetch remote set-url origin https://127.0.0.1.invalid/ServiceNow-AI/NowAI-Bench-Staging
+REPO=/tmp/nowai-bench-fetch /bin/bash ~/.nowai-sync/nowai-sync-cron.sh
+rm -rf /tmp/nowai-bench-fetch
+```
+
+Expected:
+- log shows `BLOCKED: fetch-failed`
+- Teams card includes `Remote = origin/main`
+- Teams card includes the fetch error text in the `Error` fact
+
+### Task 4: Update docs and run the final repo verification
+
+**Files:**
+- Modify: `.claude/skills/sync-nowai-leaderboard/SKILL.md`
+- Modify: `~/.nowai-sync/DESIGN.md`
+
+- [ ] **Step 1: Update the repo skill doc to mention blocked preflight Teams warnings**
+
+Change the `Teams notifications` section in `.claude/skills/sync-nowai-leaderboard/SKILL.md` to:
+
+```md
+## Teams notifications
+- Set `TEAMS_WEBHOOK_URL` (secret/env var, never committed — keep it in the
+  gitignored `.env`) to enable. The URL is a Power Automate "Workflows" webhook
+  (`*.powerplatform.com`), so `lib/teams.mjs` posts an **Adaptive Card** in the
+  `message/attachments` envelope that template expects — not a raw MessageCard.
+- Cards: green ✅ success (with "Open staging" button), red ❌ failure, amber ⚠️
+  sanity-gate abort, amber ⚠️ blocked preflight skip (dirty worktree / wrong
+  branch / fetch failure / behind-diverged), blue 📋 Friday heartbeat (no
+  changes detected — shows last date `data/leaderboard.json` actually changed).
+- The daily 14:00 launchd job (`~/.nowai-sync/`) loads `TEAMS_WEBHOOK_URL` from
+  `.env`, posts blocked-preflight warnings through `notify-blocked.mjs`, and
+  also fires a local macOS desktop notification for every outcome.
+```
+
+- [ ] **Step 2: Update the local automation design doc**
+
+In `~/.nowai-sync/DESIGN.md`, make these three edits:
+
+1. Change wrapper flow step 3 to:
+
+```md
+3. **Precheck (abort + notify on fail):** branch must be `main`; worktree must
+   be clean; `git fetch origin main`; local must not be behind/diverged from
+   `origin/main`. Every blocked precheck also posts a Teams warning card.
+```
+
+2. Change the Teams-notification table to:
+
+```md
+| Outcome | Card | Color |
+|---|---|---|
+| Updated + pushed | "✅ Staging ready for review" + Open-staging button + change facts | Good (green) |
+| Sanity-gate abort | "⚠️ Leaderboard sync aborted" + issues | Warning (amber) |
+| Blocked precheck | "⚠️ Leaderboard sync blocked" + reason/facts | Warning (amber) |
+| Any failure | "❌ Leaderboard sync failed" + stage/error facts | Attention (red) |
+| No changes | *(no Teams card — desktop only)* | — |
+```
+
+3. Add this smoke-test section under `Install / manage`:
+
+~~~md
+### Smoke-test blocked warnings
+
+Use a temporary clone so the live repo is not disturbed:
+
+```sh
+rm -rf /tmp/nowai-bench-dirty
+git clone /Users/bradley.cleveland/git/hf/NowAI-Bench /tmp/nowai-bench-dirty
+touch /tmp/nowai-bench-dirty/.blocked-sync-smoke
+REPO=/tmp/nowai-bench-dirty /bin/bash ~/.nowai-sync/nowai-sync-cron.sh
+rm -rf /tmp/nowai-bench-dirty
+```
+~~~
+
+- [ ] **Step 3: Run the full repo test suite**
+
+Run:
+
+```bash
+cd .claude/skills/sync-nowai-leaderboard
+node --test
+```
+
+Expected: PASS, including the existing transform tests and the new blocked-notify tests.
+
+- [ ] **Step 4: Commit the repo-tracked changes**
+
+```bash
+git add \
+  .claude/skills/sync-nowai-leaderboard/lib/blocked-notify.mjs \
+  .claude/skills/sync-nowai-leaderboard/notify-blocked.mjs \
+  .claude/skills/sync-nowai-leaderboard/test/blocked-notify.test.mjs \
+  .claude/skills/sync-nowai-leaderboard/test/notify-blocked-cli.test.mjs \
+  .claude/skills/sync-nowai-leaderboard/SKILL.md
+git commit -m "feat: send Teams warnings for blocked sync runs"
+```
+
+- [ ] **Step 5: Leave the local wrapper and local DESIGN doc in place**
+
+There is no git commit for `~/.nowai-sync/nowai-sync-cron.sh` or
+`~/.nowai-sync/DESIGN.md` because those files intentionally live outside the
+repo. The implementation is not complete until those local files have been
+edited and the smoke tests above have posted real Teams warnings.