feat(scripts): add rolling 28-day commit statistics tool

[Copilot]

Adds scripts/commit_stats.py — a zero-dependency Python script that buckets the last 28 days of commits on any branch into four 7-day rolling windows and prints a Markdown table (Week Range, Commits, Authors, Top10 author:count).

Summary

• Base branch target: master
• Problem: No reusable tooling existed to summarise recent commit activity by rolling week with per-author breakdowns.
• Why it matters: Enables contributors and maintainers to quickly audit contribution cadence and authorship distribution without external tooling.
• What changed:
  • scripts/commit_stats.py — GitHub REST API mode (paginated) + local git log fallback; author identity prefers GitHub login, falls back to commit.author.name/email; CLI: --repo, --token/$GITHUB_TOKEN, --ref, --days, --top, --local
  • scripts/tests/test_commit_stats.py — 21 unit tests (fixed sample data, no network) covering window generation, stat bucketing, table rendering, CLI parsing
  • docs/commit-stats.md — usage reference
  • docs/SUMMARY.md — link added under Operations
• What did not change: No Rust source, no CI workflows, no existing scripts touched.

Label Snapshot (required)

• Risk label: risk: low
• Size label: size: S
• Scope labels: scripts, docs
• Module labels: N/A
• Contributor tier label: (auto-managed)
• If any auto-label is incorrect, note requested correction: N/A

Change Metadata

• Change type: feature
• Primary scope: docs

Linked Issue

• Closes #
• Related #
• Depends on #
• Supersedes #

Supersede Attribution (required when Supersedes # is used)

• N/A — no prior PR superseded.
• Co-authored-by trailers added: No
• If No: no prior PR superseded.
• Trailer format check: N/A

Validation Evidence (required)

# Rust checks intentionally skipped — no Rust changes
python -m pytest scripts/tests/test_commit_stats.py -v
# 21 passed in 0.06s

python scripts/commit_stats.py --local --ref HEAD
# Prints Markdown table with live data from local clone

• Evidence provided: all 21 unit tests pass; local smoke test confirms correct Markdown output
• Skipped: cargo fmt/clippy/test — zero Rust changes

Security Impact (required)

• New permissions/capabilities? No
• New external network calls? Yes — optional GitHub REST API calls (api.github.com/repos/.../commits) gated behind explicit --repo flag; no calls when --local is used
• Secrets/tokens handling changed? No — token read from env var GITHUB_TOKEN or --token flag; never logged or stored
• File system access scope changed? No
• Risk: token forwarded via Authorization: Bearer header only; truncated in error messages to _ERROR_BODY_MAX chars to avoid accidental secret leakage in logs

Privacy and Data Hygiene (required)

• Data-hygiene status: pass
• Redaction/anonymization notes: no personal data committed; sample fixtures use synthetic author names (alice, bob, charlie)
• Neutral wording confirmation: test identifiers are system-focused and impersonal

Compatibility / Migration

• Backward compatible? Yes — new standalone script, no existing interface changed
• Config/env changes? No
• Migration needed? No

i18n Follow-Through (required when docs or user-facing wording changes)

• i18n follow-through triggered? Yes — new docs/commit-stats.md added and linked in docs/SUMMARY.md
• Locale navigation parity updated? No — tool-specific reference doc, not a navigation hub or entry-point page; no locale equivalents needed
• Localized runtime-contract docs updated? N/A — new tool doc, not an existing runtime-contract reference
• Vietnamese canonical docs synced? N/A
• Scope decision: commit-stats.md is a self-contained operational reference, not a locale-parity surface (analogous to cargo-slicer-speedup.md). No follow-up issue required.

Human Verification (required)

• Verified scenarios: --local --ref HEAD on shallow clone produces correct 4-row table; --days 14 produces 2-row table; invalid --days 10 exits with error
• Edge cases checked: empty commit window outputs — in Top10 column; --top 5 with 20 authors caps correctly; missing --repo/--local exits with clear error message
• What was not verified: live GitHub API pagination against a repo with >1000 commits in 28 days (covered by unit tests for pagination logic)

Side Effects / Blast Radius

• Affected subsystems/workflows: none — standalone script, no imports into existing modules
• Potential unintended effects: none
• Guardrails: script errors surface via non-zero exit code and stderr messages

Agent Collaboration Notes (recommended)

• Agent tools used: Copilot coding agent
• Workflow/plan summary: explored existing scripts/ and python/ patterns → authored script + tests + docs in one pass → ran parallel_validation → addressed review feedback (consistent error truncation constant, named EOD constants, Python version accuracy in docs, test helper rename)
• Verification focus: window boundary correctness, author identity fallback, pagination loop termination
• Confirmation: naming + architecture boundaries followed per AGENTS.md + CONTRIBUTING.md ✅

Rollback Plan (required)

• Fast rollback: git revert <commit> — touches only new files, zero blast radius
• Feature flags: none
• Observable failure symptoms: N/A — script is opt-in; no existing workflow depends on it

Risks and Mitigations

• Risk: GitHub API rate-limit (60 req/h unauthenticated) exhausted if called in rapid CI loops without a token
  • Mitigation: documented in docs/commit-stats.md; unauthenticated use typically requires 1–5 pages per run, well under limit; $GITHUB_TOKEN injection is the recommended CI path

Original prompt

在 ralf003/zeroclaw 仓库中新增一个可复用的“提交统计”脚本/工具，用于按滚动 7 天为一周统计最近 4 周（28 天）master 分支的 commit 提交情况，并输出表格：每周 commit 数、当周贡献作者数、当周 Top10 作者及其 commit 数。要求：

• 统计窗口：以当前日期为基准的最近 28 天（含当天），切分为 4 个连续的 7 天区间（第 1 周为最近 0-6 天，第 2 周为 7-13 天，第 3 周为 14-20 天，第 4 周为 21-27 天）。
• 数据来源：GitHub API（或本地 git log）均可，但需在 README 或脚本说明中写清楚使用方式。
• 输出：在控制台打印 Markdown 表格，包含列：Week Range（YYYY-MM-DD..YYYY-MM-DD）、Commits、Authors、Top10 (author:count, 用逗号分隔)。
• 作者识别优先使用 GitHub login；若缺失则回退到 commit.author.name/email。
• 处理分页/大量提交：确保能覆盖 28 天内所有 commit。
• 增加基础测试或自检（例如对固定的样例输入进行断言，或对本地仓库运行时做 sanity check）。
• 将脚本放入合理位置（如 scripts/commit_stats.*），并在文档中添加使用说明。

The following is the prior conversation context from the user's chat exploration (may be truncated):

User: 请分析zeroclaw分支 近4周的commit提交情况，形成一个表格，每周的commit提交数，有贡献的作者数目，前10名作者当周提交的commit数

Assistant: 目前**无法按“近 4 周”给出准确的周度统计表：GitHub 的 commits API 分页最多每页 100 条，而你这个仓库 master 分支最近提交非常密集，我在仅抓取前 200 条（page=1~2）**的情况下，还没拿到每个 commit 的提交时间 commit.author.date（工具返回内容里只有 html_url/author 等摘要字段），因此无法可靠地把提交归档到每周并统计“每周提交数 / 作者数 / Top10 作者”。

不过我已经确认了两点关键信息：

1. 你提到的 zeroclaw 分支 不存在；仓库目前可见分支返回的是 master。
2. master 分支提交量很大，需要继续翻页并且需要拿到每条 commit 的时间字段，才能做“近 4 周”周报。

我需要你确认 1 个问题（选一个口径）

你说的“每周”想按哪种周口径统计？

• A) 自然周（周一~周日，按你所在时区；你提供的当前日期是 2026-04-08，周三）
• B) 滚动 7 天为一周（近 28 天切成 4 段：0-6 / 7-13 / 14-20 / 21-27 天）

回复我 A 或 B 即可。

同时给你一个“继续获取更多提交”的入口

由于 API 结果分页限制，想覆盖近 4 周，需要继续拉取更多页。你也可以直接在 GitHub UI 里查看更早的提交列表（从我已拉取的接口参数构造）：

https://github.com/ralf003/zeroclaw/commits/master?per_page=100

只要你确认了周口径（A/B），我下一步会继续把 master 分支提交分页拉全到覆盖 2026-03-12 ~ 2026-04-08（近 28 天），然后输出你要的表格（每周：commit 数、作者数、Top10 作者及其当周 commit 数）。

User: 1、B) 滚动 7 天为一周 2、你可以自己形成一些skill来完成我的任务，我刚刚的任务不是特别复杂“请分析zeroclaw分支 近4周的commit提交情况，形成一个表格，每周的commit提交数，有贡献的作者数目，前10名作者当周提交的commit数”

Assistant: 我这边已经发起了相应的工具调用来继续完成“按滚动 7 天统计近 4 周 master 分支 commits 并输出表格”的分析/实现流程，现在需要等待你在弹窗里确认/允许该工具调用后，我才能继续执行并给出最终的周度统计表格结果。

This pull request was created from Copilot chat.