git-push

name	git-push
description	> Use when this capability is needed.

git-push — NanoRTC Pre-flight Push Workflow

Run local CI, fix formatting, review commits, check doc freshness, then push. The goal is to catch everything GitHub Actions would catch, before the code leaves your machine.

Step 1: Pre-flight Status

Gather context. Run ALL of these in parallel:

git status
git branch --show-current
git remote -v
git log --oneline -5
git rev-parse --abbrev-ref @{upstream} 2>/dev/null || echo "NO_UPSTREAM"

Handle edge cases before proceeding:

• Detached HEAD: Stop. Tell the user to create or checkout a branch first.
• No remote configured: Stop. Tell the user to add a remote.
• On main/master with uncommitted changes: Warn and ask for confirmation before continuing.
• Clean working tree AND up-to-date with remote: Tell the user nothing to push. Stop.

Step 2: CI Validation

This is the ONE command that validates everything. Do not replicate its individual checks.

./scripts/ci-check.sh

This script covers: architecture constraints (no platform headers, no malloc in src/), clang-format, all 3 profile builds (DATA/AUDIO/MEDIA), ctest for each profile, symbol prefix validation, no global mutable state, and AddressSanitizer build+test.

If it fails:

1. Check if the failure is clang-format. Look for FAIL next to clang-format check in the output while other checks passed. If so, auto-fix:

   clang-format -i src/*.c src/*.h include/*.h crypto/*.h crypto/*.c
   

   Then re-run ./scripts/ci-check.sh. If it passes now, the formatting fixes become part of the uncommitted changes handled in Step 3.

2. If the failure is NOT clang-format (build error, test failure, architecture constraint violation, symbol naming, ASan failure): stop the entire flow. Show the failure output clearly to the user. Do NOT attempt automatic fixes for anything other than formatting.

Step 3: Handle Uncommitted Changes

Only reached after Step 2 CI validation passes. If git status shows uncommitted changes (including any clang-format auto-fixes from Step 2):

1. Show changes:

   git status
   git diff HEAD
   

2. Stage relevant files by name. Never stage files matching: .env*, credentials*, *.key, *.pem, *.p12. Warn the user if such files appear in the working tree.

3. Generate a commit message with conventional commit prefix (feat:, fix:, docs:, refactor:, test:, chore:, style:) based on the actual changes. If the only change is formatting, use style: auto-fix clang-format.

4. Commit using HEREDOC format:

   git commit -m "$(cat <<'EOF'
   <type>: <description>
   
   Co-Authored-By: Claude Opus 4.6 (1M context) <[e-mail]>
   EOF
   )"
   

If no uncommitted changes, skip this step.

Step 4: Patch-on-Patch Review (Advisory)

Detect layered incremental fixes in today's commits that could be squashed into cleaner history.

# Today's commits on this branch
git log --since="00:00" --format='%h %s' --no-merges

# Source files modified in multiple commits today
git log --since="00:00" --format='%h' --no-merges | \
  xargs -I{} git diff-tree --no-commit-id --name-only -r {} | \
  grep -E '\.(c|h)$' | sort | uniq -c | sort -rn

If fewer than 2 commits today: Skip entirely. Proceed to Step 5.

Look for these signals:

• Any .c or .h file modified in 3+ commits today (strong signal)
• Fix chains: "implement X" then "fix X" or "fix typo in X"
• Messages containing "forgot to", "actually", "another attempt"

If detected, warn the user:

Patch-on-patch detected: nano_stun.c modified across multiple commits today. Consider squashing with git rebase -i before pushing.

This is advisory only — if the user says proceed, continue to Step 5.

Step 5: Documentation Freshness Check (Advisory)

Compare changed files against upstream to detect potentially stale documentation.

UPSTREAM=$(git rev-parse --abbrev-ref @{upstream} 2>/dev/null || echo "origin/main")
git diff --name-only "$UPSTREAM"...HEAD 2>/dev/null || git diff --name-only HEAD~5..HEAD

Apply these mapping rules:

Changed files	Check this doc	Reason
src/nano_*.c or src/nano_*.h	docs/QUALITY_SCORE.md	Module grade may need updating
include/nanortc.h	ARCHITECTURE.md	Public API change affects architecture
New file in src/	docs/engineering/development-workflow.md	Module order may need updating
CMakeLists.txt	AGENTS.md	Build instructions may have changed
New tests/test_*.c	docs/QUALITY_SCORE.md	Test coverage column may need updating
crypto/nanortc_crypto*.c	docs/references/rfc-index.md	Crypto RFC refs may need adding
Any src/ or crypto/ file	docs/exec-plans/active/*.md	Active plan progress may need updating

If staleness detected, list the potential gaps and let the user decide:

Docs may need updating:

• docs/QUALITY_SCORE.md — nano_stun implemented, grade may need bumping from D
• ARCHITECTURE.md — nanortc.h public API changed

Do not block. The user decides whether to update docs before or after pushing.

Step 6: Push

Check upstream tracking and push:

# Check if upstream exists
git rev-parse --abbrev-ref @{upstream} 2>/dev/null

• No upstream: git push -u origin $(git branch --show-current)
• Has upstream: git push

Step 7: Post-push Summary

Display a summary in English:

Push complete
  Branch: feat/stun-parser
  Commits: 3
  Remote: origin ([e-mail]:user/nanortc.git)
  CI validation: PASSED
  Doc reminders: 1 (QUALITY_SCORE.md)

If branch is not main, suggest creating a PR.

Rules

• Never force push unless the user explicitly requests it. Warn if targeting main/master.
• Never skip CI. Always run ./scripts/ci-check.sh before pushing. No shortcuts.
• Never commit secrets. Abort and warn if any staged file looks like a key, token, or credential.
• Do not replicate ci-check.sh. The script handles architecture constraints, formatting, 3 profile builds, tests, symbol checks, and ASan. Just run it. If the script is updated, the skill automatically benefits.
• Only auto-fix formatting. Build failures, test failures, and constraint violations need human judgment. clang-format is the only auto-fixable issue.
• Patch-on-patch and doc freshness are advisory. Warn but never block the push.
• HEREDOC for commit messages. Always use the heredoc format.
• Co-Authored-By trailer on all auto-generated commits.
• Prefer new commits over amending. Format fixes get their own commit.

---

Source: 0x1abin/nanortc — distributed by TomeVault.