Commit the agent tooling: workflow hooks, three project skills, and a fully ignored reports/

[andre-salvati]

What?

Makes this repo's agent tooling part of the repo instead of one developer's local config:

• .claude/hooks/ + .claude/settings.json — four workflow hooks (branch protection, PR description as merge body, CHANGELOG gate, and a new PR-description freshness gate) and the settings file that registers them.
• data-divergence — a new skill for investigating why two datasets that should agree don't, shipping a worked investigation of this repo's own prod catalog.
• project-costs / sql-diagram — converted from slash commands to skills, each shipping the artifact it explains under examples/.
• reports/ is now entirely gitignored, and the artifacts that were tracked there moved into the skills that use them.

Why?

CLAUDE.md and specs/workflow.md state the hook-enforced rules as project rules, but the hooks lived only in an ignored config — so the rules were a description of one machine, not a property of the repo. A fresh clone got none of them.

The two slash commands only loaded when someone typed them. As skills their descriptions sit in context and match on relevance, so "why is our Databricks spend up?" reaches project-costs without anyone remembering it exists. Typing /project-costs still works.

data-divergence came out of a live investigation this week — batch vs SDP silver in prod, a 13-day date shift. The procedure is written generically (no table or column names); its committed example is the one place it names real tables.

The fourth hook was added late, for a reason visible in this PR's own history: pr-merge-description.sh copies the PR body into the merge commit message, and this description had gone stale twice — advertising an example.md that later commits deleted, and warning that job1_prod was failing daily when the fix had been on main since 2026-07-25. On GitHub that is editable; in a merge commit it is permanent.

How?

.gitignore un-ignores by name, never by wildcard. The AI Dev Kit installs ~30 user-level skills into .claude/skills/; a wildcard there would commit all of them, the exact drift specs/tooling.md#install-layout documents as having shadowed the user-level set for two months. Git also won't descend into an excluded directory, so .claude/skills/ is re-included before its children are re-excluded. git add -An .claude/ is the check — it must list only our paths.

settings.json uses $CLAUDE_PROJECT_DIR. Absolute paths would break every other clone. Machine-specific entries (an update check pointing into ~/.ai-dev-kit/) moved to the still-ignored settings.local.json; Claude Code merges the two.

Every hook self-gates on the command text. pr-merge-description.sh originally relied on the settings-level if: filter alone, and that filter leaks: it rewrote unrelated Bash commands mid-session, appending --subject/--body-file to non-merges and firing a gh pr edit network write each time. Fixed here; the gate belongs in the script.

Freshness is enforced by a sentinel, not by judgement. A hook cannot tell whether prose is accurate. require-fresh-pr-description.sh proves the weaker thing that catches the real failure — that someone looked at the description at the exact commit being merged — via <!-- description-verified: <sha> --> checked against HEAD. It runs before pr-merge-description.sh, since a stale body caught after that point is already history.

Examples live with the skill, not in reports/. .gitignore only governs untracked files, so ignoring reports/ would have left the force-added artifacts in the index and made the rule a lie. They moved to .claude/skills/<skill>/examples/, a committed path. Both example.md commentary files were deleted along the way: an example is the artifact, and two files narrating one artifact drift — the prose is the copy that goes stale.

Validation?

• git add -An .claude/ lists only our paths — no kit skills leak in. Re-run after touching that block.
• Hooks commit at mode 100755; verified via git ls-files -s.
• require-fresh-pr-description.sh has a test suite — 11/11 passing against a stubbed gh (no network): pass-through on non-merge and on unrelated gh commands; blocks on a missing stamp, a stamp from an older commit, and a stamp naming no real commit; allows a full-sha stamp, a short-sha stamp, and a merge with no PR ref. Includes a regression test that pr-merge-description.sh no longer rewrites non-merge commands or fires gh pr edit on them, and still rewrites a real merge.
• protect-main-branch.sh ran on every commit in this branch and correctly allowed them.
• require-changelog-entry.sh blocked work twice this session on commands merely containing its trigger phrase — a known false positive, not fixed here.
• sql-diagram was exercised end to end on a deliberately complex query. That run found real blind spots in the tool — window functions are never drawn, WHERE is only drawn above a join, OUTPUT shows aliases not expressions — now documented in the skill.
• Secret scan across all tracked files and full git history: no tokens, hosts, org IDs, ARNs, AWS account IDs or keys. README config samples are placeholders; CI uses ${{ secrets.* }} with the client secret scoped to steps rather than workflow env.
• No Python changed; ruff pre-commit hooks skipped on every commit.

Impact in prod

• No table schema/data change — no production impact.
• Schema change — classify and declare the remediation:

Tooling and docs only. No commonSchemas.py, task module, cluster key, job definition or bundle resource is touched, so nothing here reaches a medallion table or a running job.

Chosen strategy: leave as-is — nothing to migrate.

---

⚠️ The committed data-divergence example documents four live divergences in prod, none fixed here and none introduced by this PR:

1. curated.order_enriched_sdp carries order_date 13 days early on 6,000,000 rows, root-caused to seed_sources.py:135 anchoring the backfill on run date rather than the existing _EPOCH constant.
2. country diverges on 5,364,000 rows / 447 of 500 customers — the same append-only freeze, on a column nobody intended to freeze.
3. report.order_agg is missing 2026-07-24 entirely: the run failed, bronze self-healed via full overwrite, and the silver incremental MERGE is scoped to date == seed_date, so no later run backfills it. Any failed daily run leaves a permanent hole.
4. 5,000 orders of 2026-06-24 are tripled in the SDP silver, since only the batch path runs DQX.

Recommended order once someone picks these up: anchor _seed_initial on _EPOCH, backfill 07-24 (or widen that filter to a lookback window), deploy, then make drop env=prod. A full refresh alone would restate product_name across all history.