gitlogstats 1.0.5__tar.gz → 1.0.7__tar.gz

gitlogstats-1.0.7/.claude/CLAUDE.md

@@ -0,0 +1,83 @@
+# Instructions to Claude
+
+`gitlogstats` is a Python command-line tool (`src/gitlogstats/`) that reports developers' contributions to git repositories. The repository also holds JavaScript project tooling: the project-board scripts (`scripts/board/`) and the Claude Code hook tests (`.claude/hooks/`). Each language has its own conventions below.
+
+## Testing
+
+Before finalizing major changes to code, write thorough unit tests and integration tests, aiming for 100% coverage of `src/gitlogstats/`. Statistics must be checked against **real git repositories** built in the tests (see `tests/test_integration.py`), not only against hand-written `git log` text: a mocked log can only confirm the format the test author expected. All passing tests should be reproducible during regression testing as we develop new code.
+
+The checks, all run by the Stop hook (`.claude/hooks/verify.sh`):
+
+| Area                      | Command                                                     |
+| ------------------------- | ----------------------------------------------------------- |
+| Python tests              | `python -m pytest -q` (or `npm test`)                       |
+| Python coverage           | `python -m pytest --cov`                                    |
+| Formatting (Python + JS)  | `npm run format:check` (Black and Prettier)                 |
+| Board script tests        | `npm run test:scripts`                                      |
+| Hook tests                | `npm run test:hooks`                                        |
+
+### Reading a green result
+
+A passing check is not automatically evidence. Before treating one as proof, ask:
+
+- **What would this value look like if the thing that sets it had never happened?** If the answer is "the same", it is not evidence. A count of zero failures, a field read off an object that does not have it, a measurement that never ran, and a package built before the change all report exactly what success reports.
+- **Does this pass mean "nothing broke" or "the thing works"?** They are indistinguishable from outside. A green suite proves nothing about a scenario the data under test never exercises — e.g. a parser tested only on single-line commit messages says nothing about multi-line ones.
+- **Which tests did this green actually run?** `pytest` covers the Python tool only; the board scripts and hooks have their own `node --test` suites. A green from one says nothing about the others.
+- **Would the new test fail without the change?** Where it is cheap, run it against the old code (e.g. `git show HEAD:<file>` into a scratch directory) and confirm it fails.
+
+The first question you can and should ask about your own work: whether an artifact is what you think it is is checkable from the inside. **A prediction is not** — when you expect a particular answer, the expectation is what is doing the asking, so that check has to come from someone with no stake in the outcome. Where work is split across people or sessions, spend one question there rather than on general review.
+
+Fix the defect, not the instrument. If a check reports something correct as a fault, the rule is measuring the wrong thing — loosening its threshold hides the real fault it was built to catch.
+
+## Python conventions
+
+- Follow **PEP 8**, formatted with **Black** (default settings, 88-character lines). Run `black src tests` (or `npm run format`); the PostToolUse hook formats edited `.py` files automatically, and `black --check src tests` must pass.
+- Naming per PEP 8: `snake_case` for functions, methods and variables; `PascalCase` for classes; `UPPER_SNAKE_CASE` for module constants.
+- Imports at the top of the module: standard library, then third party, then local, one group each.
+- Support the Python versions in `pyproject.toml` (`requires-python`) and CI's matrix; avoid syntax newer than they allow.
+- Run git through `subprocess` with an **argument list**, never a shell string, so names, paths and patterns containing spaces or quotes are passed intact.
+- Never parse human-oriented `git log` output (commit messages, `Author:` lines) with regular expressions. Ask git for a machine-readable `--format` instead.
+- Results go to standard output; diagnostics (`--verbose`) go to standard error.
+- Runtime code uses the standard library only; test and build tools belong in the `dev` extra / `[dev-packages]`.
+
+## JavaScript conventions
+
+- JavaScript in this repository is project tooling only (`scripts/`, `.claude/hooks/`), run with Node 20+.
+- Format with **Prettier** (`.prettierrc.json`: no semicolons, single quotes, arrow parentheses avoided). Run `npm run format`; the PostToolUse hook formats edited files automatically.
+- Use ES Modules (`import`/`export`, `.mjs` files) and the Node standard library (`node:fs`, `node:test`, …). Add dependencies only when the standard library cannot do the job.
+- Test with the built-in `node:test` runner in `*.test.mjs` files next to the code they test. Scripts that run on execution must guard that with an "is main module" check so tests can import them.
+
+## Code comments
+
+Leave standard docstring comments for all modules, functions, and for large blocks of complicated code — Python docstrings, JSDoc blocks in JavaScript. Avoid jargon and keep comments concise.
+
+## Specification
+
+The specification is in `docs/SPEC.md`. It describes what the tool does today and what is planned, and it is the source of the GitHub project board. Update it in the same change whenever behaviour changes or a requirement is completed.
+
+The project-board scripts (`scripts/board`) parse `docs/SPEC.md`, so keep these formats when editing it:
+
+- **Sections are `### <N>. <Title>` headings** (e.g. `### 2. Contribution Statistics`); they label a requirement's section.
+- **Requirements are `#### <ID> <Title>` subheadings** — `<ID>` is `FAMILY-N` (uppercase family letters, hyphen, number; e.g. `STAT-5`, `REPO-2`). The prose beneath the heading, up to the next heading, becomes the issue body. Families: `REPO`, `STAT`, `FILT`, `OUT`, `CLI`, `PKG` (labels in `scripts/board/config.mjs`).
+- **Each requirement has a `**Status:** <status>` line**, one of `Todo`, `In Progress`, `Done`. An unknown status fails `board:derive`.
+- **Future Work items are `-` bullets** under `### <N>. Future Work`; they become phase-2 issues keyed by a slug of their first words, so rewording a bullet's start re-keys it.
+- **Never change an existing ID** — it keys the issue; renaming or renumbering orphans the old issue and creates a new one.
+
+## Git & project-board workflow
+
+Changes are tracked on the GitHub project board (https://github.com/users/bloombar/projects/4, linked to this repository) and follow a branch → PR flow. Follow this **by default**:
+
+- **Do not commit code changes directly to the default branch (`master`).** Create a feature branch named `feat/<REQ-ID>-<slug>` (e.g. `feat/STAT-6-mailmap`; use a short descriptive slug when no requirement id applies). **Exception:** documentation (Markdown and anything under `docs/`) and project tooling under `scripts/` and `.claude/` may be committed directly to the default branch without a PR.
+- **Open a pull request** whose description includes `Closes #N` — `N` is the board issue's number — so the issue closes on merge. Commit and push only when asked, and run the checks above first.
+- **Do not hand-create board issues.** The board is generated from the SPEC: `npm run board:derive` regenerates `scripts/board/manifest.yaml`, then `npm run board:sync` creates or updates the issues (`-- --dry-run` previews; `-- --reconcile` forces SPEC statuses back onto the board). A requirement marked `Done` in the SPEC is always closed and moved to Done; other status moves are left to the board unless `--reconcile` is passed.
+- Pushing to `master` publishes a release to PyPI (see `.github/workflows/build.yaml`), so bump `version` in `pyproject.toml` when a change to the package should be released.
+
+If asked to use a different workflow (e.g. commit code straight to the default branch), **remind the user that it diverges from this flow and confirm before proceeding** — then honor the confirmed request.
+
+## Protected paths
+
+**IMPORTANT:** `.pypirc` holds the PyPI publishing token and `.env*` files hold any other local credentials. A `PreToolUse` hook (`.claude/hooks/guard-paths.sh`, tested by `npm run test:hooks`) blocks writes to them. A block is a signal to stop and report — never route around it.
+
+## Agent workflow
+
+Larger work can run as a supervisor/developer split: `.claude/agents/developer-agent.md` implements a scoped slice against a brief, `.claude/agents/spec-reviewer.md` reviews the diff in fresh context, and the agent doing the work is never the one grading it. The brief template and definition of done are in the `phase-handoff` skill; run the `stale-check` skill before starting or reviewing a slice.

gitlogstats-1.0.7/.claude/agents/developer-agent.md

@@ -0,0 +1,40 @@
+---
+name: developer-agent
+description: Implements one scoped slice of gitlogstats work against a self-contained brief, then reports the evidence that it works. Invoked by the supervisor, one invocation per slice.
+tools: Read, Edit, Write, Grep, Glob, Bash
+model: sonnet
+---
+
+You are the implementer on gitlogstats, a Python command-line tool that reports developers' contributions to git repositories. A supervisor scopes the work and reviews it; you write the code. The repository also has JavaScript tooling (`scripts/board/`, `.claude/hooks/`); follow the conventions for whichever language you touch, as set out in `.claude/CLAUDE.md`.
+
+## What you receive
+
+A brief that names the files and interfaces involved, the SPEC requirement ids it satisfies, what is explicitly out of scope, and **the exact command that proves it works**. Treat the brief as the contract.
+
+## How you work
+
+0. **Check for stale branches and PRs first** — run the `stale-check` skill before touching anything. If an open PR touches files in your slice, or your branch is behind its base, **stop and report it** rather than editing in parallel.
+1. **Read before writing.** Match the surrounding code — its comment density, naming, and idiom. Python follows PEP 8 and is formatted with Black; JavaScript is ES Modules formatted with Prettier (no semicolons).
+2. **Stay inside the slice.** Do not refactor code the brief did not name, do not add abstraction for a future the brief did not describe, and do not fix unrelated problems you notice. Note them in your report instead. Scope creep makes the diff unreviewable.
+3. **Write the test first where it is cheap to.** New behaviour needs a test that fails without your change. For anything that affects the statistics, that means an integration test that builds a real git repository (see `tests/test_integration.py`) — a hand-written `git log` string only confirms the format you already expected.
+4. **Run the brief's check.** Then run the project checks: `python -m pytest -q` and `black --check src tests` for Python; `npm run format:check`, `npm run test:scripts` (when the slice touches `scripts/`) and `npm run test:hooks` (when it touches `.claude/hooks/`) for JavaScript. Iterate until green.
+5. **Keep the SPEC in step.** If the slice completes or changes a requirement, update its text and `**Status:**` line in `docs/SPEC.md` and run `npm run board:derive`.
+6. **Cite requirement ids in comments** where you implement them (`# STAT-5`, `// REPO-2`), so the SPEC and the code stay traceable in both directions.
+
+## What you must not do
+
+- **Never write to `.pypirc` or `.env*`.** They hold the PyPI publishing token and other credentials. A hook blocks these; if you hit that block, stop and report it — do not find another route around it.
+- Never `git push`, never merge, never open a PR, never publish to PyPI. The supervisor owns the git history and releases.
+- Never claim a check passed without having run it.
+
+## What you return
+
+Keep it short and factual:
+
+- **What changed** — the files, one line each.
+- **Evidence** — the exact commands you ran and their output. Paste the real output, including test counts. If something failed and you fixed it, say what it was.
+- **Decisions** — any judgment call you made that the brief did not settle, and why.
+- **Out of scope** — anything you noticed but deliberately left alone.
+- **Blocked** — anything you could not finish, and precisely what it needs.
+
+An honest "this part does not work yet, here is the failing output" is worth far more than a confident summary that turns out to be wrong two slices later.

gitlogstats-1.0.7/.claude/agents/spec-reviewer.md

@@ -0,0 +1,38 @@
+---
+name: spec-reviewer
+description: Adversarially reviews a slice's diff against its brief and docs/SPEC.md in a fresh context. Read-only. Checks conformance, scope, test quality, and independently re-runs the brief's verification.
+tools: Read, Grep, Glob, Bash
+model: opus
+---
+
+You review a diff you did not write, against the brief that requested it. You have not seen the reasoning that produced the change, and that is the point: you judge the result on its own terms.
+
+You are **read-only**. Never edit a file, never commit, never push.
+
+## What you check, in order
+
+0. **Staleness.** Run the `stale-check` skill. A diff built on a stale base, or one that overlaps an open PR, is a finding in its own right — report it as **must-fix** regardless of how good the code is.
+1. **Conformance.** Does every requirement in the brief actually appear in the diff? Name any that do not. A requirement that was restated in a comment but not implemented is not implemented.
+2. **Verification, reproduced.** Run the brief's check yourself — plus `python -m pytest -q` and `black --check src tests`, and `npm run format:check`, `npm run test:scripts` / `npm run test:hooks` when the slice touches `scripts/` or `.claude/hooks/`. **Do not trust reported output; produce your own.** If your result disagrees with what was reported, that is the most important finding in your review.
+3. **Test quality.** Would each new test fail without the change? Check by reading, and where it is cheap, by running it against the base version of the code. Assertions that hold trivially, tests that assert a mock was called rather than that behaviour is right, and expected values copied from the code's own output all count as missing tests. Changes to the statistics need an integration test on a real git repository.
+4. **Scope.** Did anything outside the slice change? An unrelated refactor, a dependency bump, a reformat of an untouched file, a stray `print` or `console.log`.
+5. **SPEC traceability.** Are the cited requirement ids real and correct? If the slice adds or completes requirements, is `docs/SPEC.md` updated — `#### <FAMILY>-<N> <Title>` under a `### <N>. <Title>` section, with a correct `**Status:**` line — and does `npm run board:derive` leave `scripts/board/manifest.yaml` matching the committed version?
+6. **The expensive mistakes**, weighted heavily when the slice touches them:
+   - **Statistical accuracy** — every commit credited to exactly one author; no double counting (e.g. merges); exact name matching; date boundaries inclusive; results independent of commit-message content.
+   - **Output contracts** — CSV columns and order, JSON validity across several repositories, nothing but results on standard output.
+   - **Command-line compatibility** — existing flags and defaults keep working; a changed default is called out in the README.
+   - **Secrets** — `.pypirc` and `.env*` untouched; no tokens in code, tests or logs.
+
+## How to report
+
+Rank findings by severity and label each one:
+
+- **must-fix** — wrong statistics or output; data loss; secret exposure; a stated brief requirement unimplemented; a test that passes without the change.
+- **cheap-fix** — duplication or naming _within files the slice already touched_; formatting that breaks Black or Prettier.
+- **note** — anything else.
+
+For each finding give the file and line, one sentence on the defect, and a concrete failure scenario: inputs or state, then the wrong result. A finding you cannot write a failure scenario for is a **note**, not a must-fix.
+
+**Do not pad the review.** You were asked to find gaps, which means you will be tempted to report some even when the work is sound; that tendency produces defensive scaffolding and tests for impossible cases. If the slice is correct and complete, say so and report nothing. "No must-fix findings" is a valid and useful review.
+
+Style preferences, architectural opinions about code the slice did not touch, and speculative hardening are **notes** at most, and usually should not be reported at all.

gitlogstats-1.0.7/.claude/hooks/format-edited.sh

@@ -0,0 +1,44 @@
+#!/usr/bin/env bash
+# Formats a file right after it is edited, so formatting never shows up as
+# review noise in the diff: Black for Python, Prettier for JavaScript and the
+# other web-tooling formats.
+#
+# Deliberately best-effort: this runs after every edit, and a formatter that is
+# missing or unhappy must never block the work. Always exits 0.
+
+set -uo pipefail
+
+payload=$(cat)
+
+file_path=$(printf '%s' "$payload" | python3 -c "
+import json, sys
+try:
+    data = json.load(sys.stdin)
+except Exception:
+    sys.exit(0)
+value = (data.get('tool_input') or {}).get('file_path')
+if value:
+    print(value)
+" 2>/dev/null || true)
+
+[ -n "$file_path" ] || exit 0
+[ -f "$file_path" ] || exit 0
+
+cd "${CLAUDE_PROJECT_DIR:-.}" || exit 0
+
+case "$file_path" in
+  *.py)
+    # Black is the Python formatter (PEP 8 compliant); use it if installed.
+    if command -v black >/dev/null 2>&1; then
+      black --quiet "$file_path" >/dev/null 2>&1 || true
+    fi
+    ;;
+  *.js | *.mjs | *.cjs | *.json | *.yml | *.yaml)
+    # The generated board manifest is written by derive.mjs, not formatted.
+    case "$file_path" in */scripts/board/manifest.yaml | scripts/board/manifest.yaml) exit 0 ;; esac
+    [ -d node_modules ] || exit 0
+    npx --no-install prettier --write "$file_path" >/dev/null 2>&1 || true
+    ;;
+esac
+
+exit 0

gitlogstats-1.0.7/.claude/hooks/guard-paths.sh

@@ -0,0 +1,111 @@
+#!/usr/bin/env bash
+# Blocks writes to files that must never be modified by an agent:
+#
+#   .pypirc          the PyPI API token used to publish the package
+#   .env, .env.*     any local credentials (e.g. a GitHub token)
+#
+# `.env.example` files are the tracked templates and carry no secrets, so they
+# are explicitly allowed — the rule above would otherwise block editing them.
+#
+# CLAUDE.md rules are advisory; this is not. Exit code 2 blocks the tool call and
+# shows stderr to the model, so a blocked write is a signal to stop, not an
+# obstacle to route around.
+#
+# Reads the PreToolUse hook payload as JSON on stdin.
+
+set -euo pipefail
+
+payload=$(cat)
+
+# Pull the fields we need without assuming jq is present.
+extract() {
+  printf '%s' "$payload" | python3 -c "
+import json, sys
+try:
+    data = json.load(sys.stdin)
+except Exception:
+    sys.exit(0)
+value = data
+for key in sys.argv[1].split('.'):
+    if not isinstance(value, dict):
+        sys.exit(0)
+    value = value.get(key)
+    if value is None:
+        sys.exit(0)
+print(value)
+" "$1" 2>/dev/null || true
+}
+
+tool=$(extract tool_name)
+file_path=$(extract tool_input.file_path)
+command=$(extract tool_input.command)
+
+# Paths are matched on the tail of the path, so an absolute path, a relative one
+# and a path reached via a symlink all trip the same rule.
+is_protected() {
+  case "$1" in
+    # The tracked templates come first: they are the one .env.* that is public.
+    */.env.example | .env.example) return 1 ;;
+    */.env | .env | */.env.* | .env.*) return 0 ;;
+    */.pypirc | .pypirc) return 0 ;;
+    *) return 1 ;;
+  esac
+}
+
+deny() {
+  echo "BLOCKED: $1" >&2
+  echo "This path is protected because it holds live credentials." >&2
+  echo "Do not work around this. Stop and report the block." >&2
+  exit 2
+}
+
+case "$tool" in
+  Write | Edit | MultiEdit | NotebookEdit)
+    if [ -n "$file_path" ] && is_protected "$file_path"; then
+      deny "write to $file_path"
+    fi
+    ;;
+  Bash)
+    # Only guard commands that plainly mutate a protected path. A read (cat,
+    # grep, a `grep -E '^KEY=' .env` to list key names) is allowed: the risk
+    # here is loss and leakage through modification, not inspection.
+    #
+    # Matching is restricted to the FIRST LINE of the command. Everything after
+    # a newline is a heredoc body, a commit message, or a multi-line script
+    # argument — text that merely mentions `.env` rather than acting on it.
+    # Without this, writing a commit message about the guard trips the guard,
+    # which is how an over-broad rule teaches people to disable it.
+    if [ -n "$command" ]; then
+      first_line=${command%%$'\n'*}
+
+      # Force-add: the one operation that puts a gitignored secret into history.
+      case "$first_line" in
+        *"git add "*" -f"* | *"git add "*" --force"* | *"git add -f"* | *"git add --force"*)
+          deny "git add --force can commit an ignored secret: $first_line"
+          ;;
+      esac
+
+      # Destructive operations naming a protected path.
+      case "$first_line" in
+        rm\ * | *\;\ rm\ * | *"&& rm "* | *"| rm "* | *truncate\ * | *shred\ *)
+          case "$first_line" in
+            *.env.example*) ;;
+            *.env | *.env\ * | *.env.* | *.pypirc*)
+              deny "command would delete a protected path: $first_line"
+              ;;
+          esac
+          ;;
+      esac
+
+      # Redirection into a protected path (`> .env`, `>> server/.env.production`).
+      case "$first_line" in
+        *">"*.env.example*) ;;
+        *">"*/.env* | *">"\ .env* | *">"*.pypirc*)
+          deny "command would overwrite a protected path: $first_line"
+          ;;
+      esac
+    fi
+    ;;
+esac
+
+exit 0

gitlogstats-1.0.7/.claude/hooks/guard-paths.test.mjs

@@ -0,0 +1,100 @@
+/**
+ * Tests for the PreToolUse path guard.
+ *
+ * This hook is the only mechanism standing between an agent and the files
+ * holding this project's live credentials — `.pypirc` (the PyPI publishing
+ * token) and any `.env` files. A regression here is silent — the hook simply
+ * stops blocking — so it is tested like production code.
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { execFileSync } from 'node:child_process'
+import { fileURLToPath } from 'node:url'
+import { dirname, join } from 'node:path'
+
+const HOOK = join(dirname(fileURLToPath(import.meta.url)), 'guard-paths.sh')
+
+/** Runs the hook with a payload; returns its exit code. */
+const runHook = payload => {
+  try {
+    execFileSync(HOOK, {
+      input: JSON.stringify(payload),
+      stdio: ['pipe', 'pipe', 'pipe'],
+    })
+    return 0
+  } catch (error) {
+    return error.status
+  }
+}
+
+const BLOCKED = 2
+const ALLOWED = 0
+
+const write = file_path => ({ tool_name: 'Write', tool_input: { file_path } })
+const bash = command => ({ tool_name: 'Bash', tool_input: { command } })
+
+test('blocks writes to files holding live credentials', () => {
+  for (const path of [
+    '.pypirc',
+    '/abs/path/gitlogstats/.pypirc',
+    '.env',
+    '.env.local',
+    'scripts/.env',
+    '/abs/path/gitlogstats/.env.production',
+  ])
+    assert.equal(runHook(write(path)), BLOCKED, path)
+})
+
+test('blocks a force-add, which is how a gitignored secret reaches the repo', () => {
+  assert.equal(runHook(bash('git add -f .pypirc')), BLOCKED)
+  assert.equal(runHook(bash('git add --force .env')), BLOCKED)
+})
+
+test('blocks commands that delete or overwrite a protected path', () => {
+  assert.equal(runHook(bash('rm -f .pypirc')), BLOCKED)
+  assert.equal(runHook(bash('rm .env')), BLOCKED)
+  assert.equal(runHook(bash('echo token > .pypirc')), BLOCKED)
+  assert.equal(runHook(bash('echo X=1 > scripts/.env')), BLOCKED)
+})
+
+test('allows the tracked env templates', () => {
+  // `.env.example` is committed and carries no secrets; the `.env.*` rule
+  // would block it without an explicit exception.
+  for (const path of ['.env.example', 'scripts/.env.example'])
+    assert.equal(runHook(write(path)), ALLOWED, path)
+  assert.equal(runHook(bash('rm -f .env.example')), ALLOWED)
+})
+
+test('allows ordinary source files', () => {
+  assert.equal(runHook(write('src/gitlogstats/git_logs_parser.py')), ALLOWED)
+  assert.equal(runHook(write('scripts/board/sync.mjs')), ALLOWED)
+  assert.equal(runHook(write('docs/SPEC.md')), ALLOWED)
+  assert.equal(runHook(bash('python -m pytest -q')), ALLOWED)
+})
+
+test('allows reads of protected paths — the risk is modification, not inspection', () => {
+  assert.equal(runHook(bash('grep -c password .pypirc')), ALLOWED)
+})
+
+test('only the first line is inspected, so prose about a protected path is not a command', () => {
+  // Regression: the guard originally matched the whole command string, so a
+  // commit message describing the guard tripped the guard. An over-broad rule
+  // that blocks honest work is how people learn to disable the rule.
+  const message = [
+    "git commit -F - <<'EOF'",
+    'Add guardrails',
+    '',
+    'Blocks writes to .pypirc and .env files, and refuses git add -f.',
+    'EOF',
+  ].join('\n')
+  assert.equal(runHook(bash(message)), ALLOWED)
+  assert.equal(runHook(bash('git add -A')), ALLOWED)
+  assert.equal(runHook(bash('grep -r "pypirc" .gitignore')), ALLOWED)
+  assert.equal(runHook(bash('echo "never commit .pypirc"')), ALLOWED)
+})
+
+test('a malformed payload does not block work', () => {
+  // A hook that fails open on garbage is right: it runs before every tool call,
+  // and an unparseable payload is a bug in the harness, not an attack.
+  assert.equal(runHook({}), ALLOWED)
+})

gitlogstats-1.0.7/.claude/hooks/verify.sh

@@ -0,0 +1,55 @@
+#!/usr/bin/env bash
+# Stop hook: the turn does not end until the project's checks pass.
+#
+# Runs the gate CLAUDE.md defines for a PR:
+#   Python      black --check, pytest (unit + integration)
+#   JavaScript  prettier --check, the board-script tests and the hook tests
+#
+# Only runs checks whose tools are installed: a missing tool must read as
+# "nothing to check", never as a failure, or the hook blocks every turn for the
+# wrong reason.
+#
+# Exit 2 blocks the turn and shows stderr to the model.
+
+set -uo pipefail
+
+cd "${CLAUDE_PROJECT_DIR:-.}" || exit 0
+
+failures=""
+
+run_check() {
+  local name="$1"
+  shift
+  local output
+  if ! output=$("$@" 2>&1); then
+    failures="${failures}
+--- ${name} ---
+${output}
+"
+  fi
+}
+
+# Python: the tool itself.
+if command -v black >/dev/null 2>&1; then
+  run_check "black --check" black --check --quiet src tests
+fi
+if python -c "import pytest" >/dev/null 2>&1; then
+  run_check "pytest" python -m pytest -q
+fi
+
+# JavaScript: project tooling (scripts/, .claude/hooks/).
+if [ -f package.json ] && [ -d node_modules ]; then
+  run_check "prettier --check" npx --no-install prettier --check "scripts/**/*.mjs" ".claude/**/*.mjs"
+  run_check "npm run test:scripts" npm run --silent test:scripts
+  run_check "npm run test:hooks" npm run --silent test:hooks
+fi
+
+if [ -n "$failures" ]; then
+  {
+    echo "Checks failed. Fix these before ending the turn:"
+    echo "$failures"
+  } >&2
+  exit 2
+fi
+
+exit 0

gitlogstats-1.0.7/.claude/settings.json

@@ -0,0 +1,36 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Write|Edit|MultiEdit|NotebookEdit|Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/guard-paths.sh"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Write|Edit|MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/format-edited.sh"
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/verify.sh"
+          }
+        ]
+      }
+    ]
+  }
+}

gitlogstats-1.0.7/.claude/skills/phase-handoff/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: phase-handoff
+description: The brief template and definition of done for handing a slice to developer-agent. Use when scoping work on gitlogstats.
+---
+
+# Handing off a slice
+
+A slice is work small enough that its **diff can be reviewed in one pass**. If you cannot describe the change in a few sentences, split it.
+
+## The brief template
+
+A brief without a runnable check is not ready to hand over. That check is the whole point: it is what lets the loop close without a human watching it.
+
+````markdown
+## Slice: <short name>
+
+**SPEC ids:** <FAMILY-N, …> (must already exist in docs/SPEC.md, or be added by this slice)
+**Branch:** feat/<REQ-ID>-<slug>, cut from `master` (the default branch)
+
+### Goal
+
+One paragraph. What exists after this slice that did not before.
+
+### Files and interfaces
+
+- `src/gitlogstats/<file>.py` — what it must contain
+- Reuse `existingHelper()` from an existing module rather than writing a new one
+
+### Out of scope
+
+Explicitly. Name the adjacent things you do NOT want touched — this is the line that keeps the diff reviewable, and the reviewer checks it.
+
+### Verification
+
+```bash
+<the exact command, and what its output must show>
+```
+
+### Notes
+
+Prior art elsewhere in this repo, and any decision already taken that constrains the implementation.
+````
+
+## Definition of done
+
+- `python -m pytest -q` and `black --check src tests` pass — plus `npm run format:check`, and `npm run test:scripts` if the slice touched `scripts/` or `npm run test:hooks` if it touched `.claude/hooks/`
+- Both reviewers have run and every **must-fix** finding is resolved
+- New behaviour has a test that **fails without the change**; statistics changes have an integration test on a real git repository
+- `docs/SPEC.md` describes the new behaviour, with the requirement's `**Status:**` updated
+- `npm run board:derive` has been run and `scripts/board/manifest.yaml` is committed with the change
+- Requirement ids cited in code comments where implemented
+- `README.md` updated if a command-line option, default or output changed
+- Judgment calls the brief did not settle are recorded in the PR description
+- The PR body carries `Closes #N`
+
+## The loop
+
+1. Run `stale-check`. An open PR touching these files means coordinate, not proceed.
+2. Spawn `developer-agent` with the brief.
+3. Run `/code-review` and `spec-reviewer` in parallel on the diff. Effort scales with blast radius — high for anything that changes how statistics are computed or what is printed to standard output, since users compare and grade on those numbers.
+4. Triage. **must-fix** → back to the developer. **cheap-fix** → only within files already touched. **note** → the PR description or a Future Work bullet in the SPEC, and ship.
+5. Commit, push, open the PR with `Closes #N` (verify the number — issues are not numbered in family order).
+6. After merge, run `npm run board:sync` if the SPEC changed, so the board reflects it.
+
+**Two rounds of rework, maximum.** A third means the slice was mis-scoped rather than merely wrong — re-split it and write a sharper brief.

gitlogstats-1.0.7/.claude/skills/stale-check/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: stale-check
+description: Check for stale branches, open PRs, and drift from the base branch before starting or reviewing a slice. Run this before any new task.
+---
+
+# Stale branch & PR check
+
+Run this **before starting a slice** and **before reviewing one**. The most
+expensive failure is two slices editing the same files from different bases, and that is invisible unless
+somebody looks.
+
+```bash
+# 1. What is already in flight? An open PR touching your files means coordinate, not proceed.
+gh pr list --state open --json number,title,headRefName,updatedAt,files \
+  --jq '.[] | "#\(.number) \(.headRefName) — \(.title) (updated \(.updatedAt))"'
+
+# 2. Is this branch behind its base? A slice built on a stale base merges dirty.
+#    The default branch here is `master`.
+git fetch origin --quiet
+git rev-list --count HEAD..origin/master   # commits on the base we do not have
+
+# 3. Which remote branches are merged and can be deleted?
+git branch -r --merged origin/master \
+  | grep -v 'origin/master\|origin/HEAD' || echo "none"
+
+# 4. Which remote branches have gone quiet? Anything older than ~2 weeks with no PR is a candidate.
+git for-each-ref --sort=-committerdate refs/remotes/origin \
+  --format='%(refname:short)  %(committerdate:relative)'
+```
+
+## How to act on it
+
+| finding                                         | action                                                                                                                           |
+| ----------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
+| An open PR touches files in your slice          | **Stop and report it.** Do not edit those files in parallel; the supervisor decides whether to rebase, wait, or re-scope.        |
+| Your branch is behind its base                  | Rebase onto the base before starting. Starting from a stale base is how a clean review turns into a merge conflict nobody reads. |
+| A merged branch still exists on the remote      | Report it for deletion. Do not delete branches yourself — the supervisor owns the git history.                                   |
+| A branch is quiet, unmerged, and has no open PR | Report it. It is either abandoned work to drop or unfinished work to finish, and both need a human-level decision.               |

{gitlogstats-1.0.5 → gitlogstats-1.0.7}/.gitignore

@@ -155,3 +155,6 @@ dmypy.json
 
 # Cython debug symbols
 cython_debug/
+
+# node tooling
+node_modules/

gitlogstats-1.0.7/.prettierrc.json

@@ -0,0 +1,5 @@
+{
+  "semi": false,
+  "singleQuote": true,
+  "arrowParens": "avoid"
+}