Add production push utilities and inline help comments to Makefile

AGENTS.md

@@ -51,7 +51,7 @@ that leaderboard data remains consistent with `data/leaderboard.json`.
 <claude-mem-context>
 # Memory Context
 
-# [NowAI-Bench] recent context, 2026-06-30 12:47pm PDT
+# [NowAI-Bench] recent context, 2026-06-30 1:02pm PDT
 
 Legend: 🎯session 🔴bugfix 🟣feature 🔄refactor ✅change 🔵discovery ⚖️decision 🚨security_alert 🔐security_note
 Format: ID TIME TYPE TITLE

Makefile

@@ -1,16 +1,51 @@
 SYNC := .claude/skills/sync-nowai-leaderboard/sync.mjs
 LOG  := $(HOME)/Library/Logs/nowai-sync.log
 
-.PHONY: sync check logs
+.PHONY: sync check logs push-to-prod force-push-to-prod
 
-## Run full sync (commit + push to staging)
-sync:
+sync: ## Run full sync (commit + push to staging)
 	node $(SYNC) --push
 
-## Dry-run: print diff, no writes
-check:
+check: ## Dry-run: print diff, no writes
 	node $(SYNC) --check
 
-## Show last 50 lines of the sync log
-logs:
+logs: ## Show last 50 lines of the sync log
 	tail -50 $(LOG)
+
+push-to-prod: ## Push current main to production after staging review
+	@set -eu; \
+	if [ -n "$$(git status --short)" ]; then \
+		echo "Refusing to push to prod: working tree is not clean."; \
+		exit 1; \
+	fi; \
+	if [ "$$(git branch --show-current)" != "main" ]; then \
+		echo "Refusing to push to prod: current branch must be main."; \
+		exit 1; \
+	fi; \
+	if [ "$$(git rev-parse HEAD)" != "$$(git rev-parse origin/main)" ]; then \
+		echo "Refusing to push to prod: local HEAD must match origin/main."; \
+		exit 1; \
+	fi; \
+	echo "WARNING: this will push main to the production remote (prod)."; \
+	printf "Hit Enter or type Yes to continue: "; \
+	read answer; \
+	if [ -n "$$answer" ] && [ "$$answer" != "Yes" ]; then \
+		echo "Aborted."; \
+		exit 1; \
+	fi; \
+	git push prod main:main
+
+force-push-to-prod: ## Force-push current main to production after explicit confirmation
+	@set -eu; \
+	echo "WARNING: this will force-push main to the production remote (prod)."; \
+	echo "Use this only when you intentionally need to override production history."; \
+	printf "Type Yes to continue: "; \
+	read answer; \
+	if [ "$$answer" != "Yes" ]; then \
+		echo "Aborted."; \
+		exit 1; \
+	fi; \
+	git push --force-with-lease prod main:main
+
+help: ## Display this help
+		@grep -E '^[a-zA-Z0-9_-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-30s\033[0m %s\n", $$1, $$2}'

docs/superpowers/plans/2026-06-30-make-help-inline-comments.md

@@ -0,0 +1,75 @@
+# Make Help Inline Comments 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:** Restore `make help` output by moving target descriptions inline in `Makefile`.
+
+**Architecture:** Keep the existing `help` parsing logic and align the target declarations to that contract. This is a minimal bugfix in one file with command-based verification before and after the change.
+
+**Tech Stack:** GNU Make, grep, awk
+
+---
+
+## File Structure
+
+- Modify: `Makefile` - move target descriptions onto target lines.
+- Create: `docs/superpowers/specs/2026-06-30-make-help-inline-comments-design.md` - approved design record.
+- Create: `docs/superpowers/plans/2026-06-30-make-help-inline-comments.md` - implementation handoff.
+
+### Task 1: Reproduce the bug
+
+**Files:**
+- Modify: `Makefile`
+
+- [ ] **Step 1: Run the failing command**
+
+Run:
+
+```bash
+make help
+```
+
+Expected: only `help` is listed because the parser does not read comment lines
+above targets.
+
+### Task 2: Move descriptions inline
+
+**Files:**
+- Modify: `Makefile`
+
+- [ ] **Step 1: Move descriptions onto target lines**
+
+Change the target declarations to:
+
+```make
+sync: ## Run full sync (commit + push to staging)
+check: ## Dry-run: print diff, no writes
+logs: ## Show last 50 lines of the sync log
+push-to-prod: ## Push current main to production after staging review
+force-push-to-prod: ## Force-push current main to production after explicit confirmation
+```
+
+- [ ] **Step 2: Keep the existing `help` parser unchanged**
+
+Do not modify:
+
+```make
+help: ## Display this help
+	@grep -E '^[a-zA-Z0-9_-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-30s\033[0m %s\n", $$1, $$2}'
+```
+
+### Task 3: Verify the fix
+
+**Files:**
+- Modify: `Makefile`
+
+- [ ] **Step 1: Run the verification command**
+
+Run:
+
+```bash
+make help
+```
+
+Expected: `check`, `force-push-to-prod`, `help`, `logs`, `push-to-prod`, and
+`sync` are all listed with descriptions.

docs/superpowers/plans/2026-06-30-prod-push-utilities.md

@@ -0,0 +1,75 @@
+# Production Push Utilities 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:** Add guarded and force-push production promotion targets to the repo `Makefile`.
+
+**Architecture:** Keep prod promotion outside the staging-only sync workflow. Encode the normal safety path in `push-to-prod`, and provide a separate explicit override path in `force-push-to-prod`.
+
+**Tech Stack:** GNU Make, POSIX shell, git
+
+---
+
+## File Structure
+
+- Modify: `Makefile` — add prod promotion targets and prompt/check logic.
+- Create: `docs/superpowers/specs/2026-06-30-prod-push-utilities-design.md` — approved design record.
+- Create: `docs/superpowers/plans/2026-06-30-prod-push-utilities.md` — implementation handoff.
+
+### Task 1: Add guarded prod push target
+
+**Files:**
+- Modify: `Makefile`
+
+- [ ] **Step 1: Update the phony target list**
+
+Add `push-to-prod` and `force-push-to-prod` to `.PHONY`.
+
+- [ ] **Step 2: Add `push-to-prod` checks and prompt**
+
+Implement a recipe that:
+- fails on a dirty worktree
+- fails off the `main` branch
+- fails if `HEAD` does not match `origin/main`
+- prints a warning
+- accepts either empty input or `Yes`
+- pushes with `git push prod main:main`
+
+- [ ] **Step 3: Verify normal guard behavior**
+
+Run a safe verification while the worktree is dirty:
+
+```bash
+printf '\n' | make push-to-prod
+```
+
+Expected: the target exits non-zero before any push and reports that the
+working tree must be clean.
+
+### Task 2: Add explicit override target
+
+**Files:**
+- Modify: `Makefile`
+
+- [ ] **Step 1: Add `force-push-to-prod` prompt**
+
+Implement a recipe that prints a stronger warning, accepts either empty input
+or `Yes`, and aborts on any other input.
+
+- [ ] **Step 2: Push with lease protection**
+
+Use:
+
+```bash
+git push --force-with-lease prod main:main
+```
+
+- [ ] **Step 3: Verify abort behavior**
+
+Run:
+
+```bash
+printf 'no\n' | make force-push-to-prod
+```
+
+Expected: the target exits non-zero with an abort message and does not push.

docs/superpowers/specs/2026-06-30-make-help-inline-comments-design.md

@@ -0,0 +1,30 @@
+# Make Help Inline Comments Design
+
+**Date:** 2026-06-30
+**Status:** Approved
+
+## Goal
+
+Restore `make help` output for the existing targets without changing the current
+`help` parser.
+
+## Root Cause
+
+The `help` recipe matches only lines shaped like
+`target: ... ## description`. Most target descriptions in `Makefile` were moved
+to the line above the target, so the parser no longer sees them.
+
+## Decision
+
+- Keep the `help` recipe unchanged.
+- Move target descriptions inline onto the same line as each target:
+  - `sync`
+  - `check`
+  - `logs`
+  - `push-to-prod`
+  - `force-push-to-prod`
+
+## Verification
+
+- Before the fix, `make help` shows only `help`.
+- After the fix, `make help` shows all documented targets.

docs/superpowers/specs/2026-06-30-prod-push-utilities-design.md

@@ -0,0 +1,33 @@
+# Production Push Utilities Design
+
+**Date:** 2026-06-30
+**Status:** Approved
+
+## Goal
+
+Add explicit manual promotion utilities for pushing the current `main` branch to
+the production Hugging Face Space remote after staging has been reviewed.
+
+## Decisions
+
+- Keep leaderboard sync automation staging-only.
+- Add two manual `Makefile` targets:
+  - `push-to-prod` for guarded promotion.
+  - `force-push-to-prod` for explicit override.
+- Require an interactive warning prompt before either target pushes.
+- `push-to-prod` must fail unless:
+  - the worktree is clean
+  - the current branch is `main`
+  - `HEAD` matches `origin/main`
+- `force-push-to-prod` may bypass those checks, but it must still require a
+  stronger warning prompt and use `--force-with-lease`.
+
+## Commands
+
+- Guarded push: `git push prod main:main`
+- Override push: `git push --force-with-lease prod main:main`
+
+## Scope
+
+Only the repo `Makefile` changes behavior. No changes are needed to the
+staging-only sync skill or its guardrails.