AGENTS.md

# AGENTS.md

## Purpose

This repo powers the NowAI-Bench static site and its leaderboard sync workflow.
The main site files are `index.html`, `style.css`, and `data/leaderboard.json`.

## Instruction Order

Read this file first.

If a root `CLAUDE.md` exists, read it next and treat it as additional
repo-specific user guidance.

When the task is about leaderboard syncing or leaderboard data, also read:

- `.claude/skills/sync-nowai-leaderboard/SKILL.md`
- `docs/superpowers/specs/2026-06-02-leaderboard-sync-design.md`
- `docs/superpowers/plans/2026-06-02-leaderboard-sync.md`

## Leaderboard Sync Support

This repo includes a repo-local skill/workflow at
`.claude/skills/sync-nowai-leaderboard/`. Codex should support that workflow
directly even if skill auto-discovery is unavailable.

Use this run order:

1. `node .claude/skills/sync-nowai-leaderboard/sync.mjs --check`
2. Inspect the diff and sanity-gate output.
3. Only if the result is sane, run
   `node .claude/skills/sync-nowai-leaderboard/sync.mjs --push`

## Deployment Guardrails

- `origin` is staging: `ServiceNow-AI/NowAI-Bench-Staging`
- `prod` is production: `ServiceNow-AI/NowAI-Bench`
- Never push to `prod` as part of automated or routine sync work.
- For sync tasks, prefer the scripted guardrails in `sync.mjs` over manual edits.

## Verification

If you change the sync workflow or transform logic, run:

- `cd .claude/skills/sync-nowai-leaderboard && node --test`

If you change site rendering, verify the static page still loads cleanly and
that leaderboard data remains consistent with `data/leaderboard.json`.


<claude-mem-context>
# Memory Context

# [NowAI-Bench] recent context, 2026-07-01 1:58pm PDT

Legend: 🎯session 🔴bugfix 🟣feature 🔄refactor ✅change 🔵discovery ⚖️decision 🚨security_alert 🔐security_note
Format: ID TIME TYPE TITLE
Fetch details: get_observations([IDs]) | Search: mem-search skill

Stats: 50 obs (19,671t read) | 93,968t work | 79% savings

### Jun 24, 2026
2281 2:35p ✅ Quarter label detection feature deployed to production HuggingFace Space
### Jul 1, 2026
2454 11:18a ✅ Approved design spec committed for blocked sync Teams warnings
2455 11:21a 🔵 Explored existing sync automation architecture and codebase patterns before implementation planning
2456 11:23a ✅ Comprehensive implementation plan written for blocked-sync Teams warnings feature
2457 11:24a ✅ Implementation plan finalized and committed to repo
2458 11:39a ⚖️ Isolated Worktree Strategy for Parallel Task Execution
2459 11:40a ✅ Configure .gitignore for Isolated Worktrees
2460 " ✅ Isolated Worktree Created for Teams Sync Warnings Work
2462 " 🔵 Baseline Test Suite Passing in Isolated Worktree
2470 11:42a 🟣 Blocked Sync Notification Builder Implementation (Task 1)
2471 " 🔵 Task 1 Implementation Details: Blocked Notification Builder
2472 11:43a 🔵 Task 1 Passes Spec Compliance Review
2474 11:45a 🔵 Code Quality Review Agent Timeout
2475 " ⚖️ Task 1 Follow-up Fixes Requested Post-Delivery
2476 11:47a 🔴 Task 1 Follow-up: Fact Key Normalization and Subtitle Deduplication
2477 " 🔵 Fact Key Normalization Implementation Strategy
2478 11:48a 🔵 Post-Fix Code Quality Review Passes
2479 " ⚖️ Task 2 Implementation Started: CLI Entrypoint for Blocked Sync Notifier
2480 11:50a 🟣 Task 2 Complete: Blocked Sync Teams Notifier CLI
2481 " 🔵 Task 2 Implementation Details: CLI Entrypoint Design
2482 11:51a 🔵 Task 2 Passes Spec Compliance Review
2483 11:53a 🔵 Code Quality Review Agent Timeout (Task 2)
2484 " 🔵 Task 2 Code Quality Issue: isMain Guard Fragility
2485 " ⚖️ Task 2 Follow-up: Fix isMain Guard for Path Safety
2486 11:55a 🔴 Task 2 Follow-up: Path-Safe isMain Guard Implementation
2487 11:56a 🔵 Task 2 Follow-up Code Quality Re-Review Passes
2488 " ✅ Plan Progress Update: Task 1 and Task 2 Complete, Moving to Wrapper Integration
2489 " ⚖️ Task 3 Implementation Started: Local Wrapper Integration
2501 12:01p 🟣 Task 3 Complete: Wrapper Integration with Blocked Sync Notifications
2502 " 🔵 Task 3 Implementation Details and Smoke Test Log Evidence
2503 12:02p 🔵 Task 3 Passes Spec Compliance Review
2504 12:04p 🔵 Code Quality Review Agent Timeout (Task 3)
2505 " 🔵 Implementation Complete: Six Commits Documenting Blocked Sync Teams Warnings Feature
2506 12:05p 🔵 Task 3 Code Quality Issues: Safety Gap and Log Detail Loss
2507 " ⚖️ Task 3 Follow-up: Fix Safety Gap and Log Detail Loss
2514 12:08p 🔴 Task 3 Follow-up: Safety-Critical Fix for Local-Ahead and Fact Logging
2515 " 🔵 Task 3 Follow-up Implementation: Exact-Sync Check and Fact Logging
2516 12:09p 🔵 Task 3 Post-Fix Code Quality Issue: Notifier Not Deployed to Production Checkout
2517 12:10p ⚖️ Task 4 Implementation Started: Documentation and Label Alignment
2518 12:12p 🟣 Task 4 Complete: Documentation Updates and Blocked Warnings Label Alignment
2519 12:13p 🔵 Task 4 Final Verification: Documentation Updates and Label Changes
2520 12:14p 🔵 Task 4 Passes Spec Compliance Review
2521 12:16p 🔵 Code Quality Review Agent Timeout (Task 4)
2522 " 🔵 Base Repository Status: Plan Documents Committed, Implementation Pending Integration
2523 12:17p 🔵 Task 4 Code Quality Issues: Deployment Gap, Stale Documentation, Maintainability Drift
2524 " ⚖️ Task 4 Follow-up: Internal Naming Alignment and Documentation Corrections
2525 12:19p 🔴 Task 4 Follow-up Complete: Out-of-Sync Reason Naming and Friday Heartbeat Documentation
2526 " ✅ Implementation Integrated: All Tasks Cherry-Picked into Base Repository
2527 " 🔵 Integration Complete: All Tests Pass in Base Repository
2532 12:22p ✅ Plan Status Updated: All Implementation Steps Complete, Final Summary Underway
S1308 Implement blocked sync Teams notifications feature - post Teams warning cards when daily leaderboard sync is blocked by precondition failures (dirty worktree, wrong branch, fetch failure, or out-of-sync state) (Jul 1 at 12:22 PM)
S1309 Follow-up quality fix for blocked-sync-teams-warnings Task 2: fix main-entry guard in notify-blocked.mjs to handle symlinked paths and paths containing spaces safely (Jul 1 at 12:23 PM)
S1310 Final overall review of the completed blocked-sync Teams warning implementation across repo code, local wrapper, and runbook without edits. (Jul 1 at 12:26 PM)
S1311 Follow-up fix after Task 4 quality review: Rename internal blocked-sync reason from `behind-or-diverged` to `out-of-sync`, update blocked-notify to support the new name with backward compatibility, align SKILL.md and DESIGN.md wording with exact-sync terminology, document Friday heartbeat behavior in DESIGN.md (Jul 1 at 12:26 PM)
S1312 Code quality review of Task 4 (blocked-sync-teams-warnings) implementation at HEAD commit 871d94432d6d2d02443a33c46909624cc293efbd in worktree, focusing on correctness, maintainability, doc consistency, and coherence of exact-sync wording change (Jul 1 at 12:29 PM)
S1313 Re-review code quality of notify-blocked.mjs and notify-blocked-cli.test.mjs at commit 06c69cf after a follow-up fix for symlinked/space-path handling, confirm whether the prior finding is resolved and identify any new blocking issues. (Jul 1 at 12:30 PM)
S1314 Re-review code quality after follow-up fix at HEAD commit 4cd6a4d; verify that two prior findings (lowercase CLI fact keys not normalized, subtitle formatter duplicated) were resolved, and confirm no new blocking quality issues remain in blocked-notify.mjs, blocked-notify.test.mjs, and sync.mjs. (Jul 1 at 12:33 PM)
S1315 Spec compliance review of Task 3 implementation in the NowAI-Bench sync wrapper (`/Users/bradley.cleveland/.nowai-sync/nowai-sync-cron.sh`), checking for required REPO override, BLOCKED_NOTIFY variable, blocked() helper function, dirty-worktree precheck, and Teams notification integration for blocked sync scenarios. (Jul 1 at 12:33 PM)
S1316 Confirm whether blocked-sync Teams warning work was merged into main and if changes can be pushed to origin (Jul 1 at 12:36 PM)
S1317 Complete the blocked-sync Teams warning feature development by confirming merge status, verifying tests, and cleaning up temporary development infrastructure (Jul 1 at 1:58 PM)
**Investigated**: Git merge status (main vs origin/main), worktree list, cherry-pick analysis to confirm all feature commits integrated, test suite validation, branch cleanup state

**Learned**: The blocked-sync Teams notification feature was fully merged into main through multiple coordinated commits; all development verification (tests passing, commits integrated) completed before cleanup; structured finish-development-branch workflow provides safe guardrails for merge confirmation and worktree cleanup

**Completed**: Blocked-sync Teams warning feature shipped and merged to main; test suite validated (23/23 tests passing); feature worktree at .worktrees/blocked-sync-teams-warnings removed; branch blocked-sync-teams-warnings deleted; development workspace consolidated to main branch only

**Next Steps**: Address the uncommitted change in AGENTS.md (either commit or discard)


Access 94k tokens of past work via get_observations([IDs]) or mem-search skill.
</claude-mem-context>