feat: repository file freshness system (script + config)

.github/workflows/file-freshness.yml

@@ -0,0 +1,56 @@
+# Repository file freshness workflow
+#
+# This workflow intentionally triggers only on a schedule and manual dispatch.
+# It commits generated artifacts back to the repository, and we avoid `on: push`
+# to prevent feedback loops.
+name: File Freshness
+
+on:
+  schedule:
+    - cron: "30 3 * * *" # Daily at 03:30 UTC
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+concurrency:
+  group: file-freshness-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  freshness:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v8.0.0
+        with:
+          enable-cache: true
+
+      - name: Set up Python
+        run: uv python install 3.11
+
+      - name: Sync dependencies
+        run: uv sync --frozen --extra dev
+
+      - name: Generate freshness artifacts
+        run: uv run --active python scripts/repo_file_freshness.py
+
+      - name: Configure git author
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+
+      - name: Commit and push (if changed)
+        run: |
+          git add docs/repo_file_status_report.md file_freshness.json freshness_summary.json freshness_ignore.json
+          if git diff --staged --quiet; then
+            echo "No freshness changes to commit."
+            exit 0
+          fi
+          git commit -m "chore: update file freshness report"
+          git push

.gitignore

@@ -77,12 +77,19 @@ instance/
 
 # Sphinx documentation
 docs/_build/
-docs/
+docs/*
+
+# Allow the freshness dashboard report to be committed.
+!docs/
+!docs/repo_file_status_report.md
 
 # Copier template ships MkDocs sources under template/docs/ (must not match the rule above).
 !template/docs/
 !template/docs/**
 
+# Repo freshness dashboard (generated + committed)
+!docs/repo_file_status_report.md
+
 # PyBuilder
 target/
 

docs/repo_file_status_report.md

@@ -0,0 +1,196 @@
+# Repository File Status Report
+
+Last updated: **2026-04-08 17:52:36 UTC**
+
+## Summary
+
+- 🟢 Green: **170**
+- 🟡 Yellow: **0**
+- 🔴 Red: **0**
+- 🔵 Blue: **0**
+
+## 🟢 Green (recent)
+
+- `.vscode/extensions.json` — **7** days
+- `.vscode/launch.json` — **7** days
+- `.vscode/settings.json` — **7** days
+- `LICENSE` — **7** days
+- `template/.github/CODE_OF_CONDUCT.md.jinja` — **7** days
+- `template/.github/ISSUE_TEMPLATE/bug_report.md.jinja` — **7** days
+- `template/.github/ISSUE_TEMPLATE/config.yml.jinja` — **7** days
+- `template/.github/ISSUE_TEMPLATE/feature_request.md.jinja` — **7** days
+- `template/.github/PULL_REQUEST_TEMPLATE.md.jinja` — **7** days
+- `template/.vscode/extensions.json.jinja` — **7** days
+- `template/.vscode/launch.json.jinja` — **7** days
+- `template/.vscode/settings.json.jinja` — **7** days
+- `template/LICENSE.jinja` — **7** days
+- `.claude/commands/ci.md` — **6** days
+- `.claude/commands/generate.md` — **6** days
+- `.claude/commands/test.md` — **6** days
+- `template/tests/{{ package_name }}/test_core.py.jinja` — **6** days
+- `.claude/commands/coverage.md` — **5** days
+- `.claude/commands/dependency-check.md` — **5** days
+- `.claude/commands/docs-check.md` — **5** days
+- `.claude/commands/release.md` — **5** days
+- `.claude/commands/review.md` — **5** days
+- `.claude/commands/standards.md` — **5** days
+- `.claude/commands/update-claude-md.md` — **5** days
+- `.claude/commands/validate-release.md` — **5** days
+- `README.md` — **5** days
+- `scripts/bump_version.py` — **5** days
+- `scripts/update_files.sh` — **5** days
+- `template/.claude/commands/ci.md` — **5** days
+- `template/.claude/commands/coverage.md.jinja` — **5** days
+- `template/.claude/commands/docs-check.md.jinja` — **5** days
+- `template/.claude/commands/generate.md` — **5** days
+- `template/.claude/commands/guided-template-update.md.jinja` — **5** days
+- `template/.claude/commands/release.md.jinja` — **5** days
+- `template/.claude/commands/review.md.jinja` — **5** days
+- `template/.claude/commands/standards.md.jinja` — **5** days
+- `template/.claude/commands/test.md` — **5** days
+- `template/.github/CODEOWNERS.jinja` — **5** days
+- `template/src/{{ package_name }}/common/__init__.py.jinja` — **5** days
+- `template/src/{{ package_name }}/common/decorators.py.jinja` — **5** days
+- `template/src/{{ package_name }}/common/file_manager.py.jinja` — **5** days
+- `template/src/{{ package_name }}/common/utils.py.jinja` — **5** days
+- `template/tests/__init__.py.jinja` — **5** days
+- `template/tests/{{ package_name }}/__init__.py.jinja` — **5** days
+- `template/{{_copier_conf.answers_file}}.jinja` — **5** days
+- `template/src/{{ package_name }}/core.py.jinja` — **4** days
+- `.github/dependabot.yml` — **3** days
+- `.github/workflows/dependency-review.yml` — **3** days
+- `.github/workflows/lint.yml` — **3** days
+- `.github/workflows/release.yml` — **3** days
+- `.github/workflows/stale.yml` — **3** days
+- `template/.github/workflows/ci.yml.jinja` — **3** days
+- `template/.github/workflows/dependency-review.yml.jinja` — **3** days
+- `template/.github/workflows/docs.yml.jinja` — **3** days
+- `template/.github/workflows/lint.yml.jinja` — **3** days
+- `template/.github/workflows/pre-commit-update.yml.jinja` — **3** days
+- `.claude/hooks/README.md` — **2** days
+- `.claude/hooks/post-bash-pr-created.sh` — **2** days
+- `.claude/hooks/post-edit-copier-migration.sh` — **2** days
+- `.claude/hooks/post-edit-jinja.sh` — **2** days
+- `.claude/hooks/post-edit-markdown.sh` — **2** days
+- `.claude/hooks/post-edit-python.sh` — **2** days
+- `.claude/hooks/post-edit-template-mirror.sh` — **2** days
+- `.claude/hooks/pre-bash-block-no-verify.sh` — **2** days
+- `.claude/hooks/pre-bash-commit-quality.sh` — **2** days
+- `.claude/hooks/pre-bash-git-push-reminder.sh` — **2** days
+- `.claude/hooks/pre-compact-save-state.sh` — **2** days
+- `.claude/hooks/pre-config-protection.sh` — **2** days
+- `.claude/hooks/pre-protect-uv-lock.sh` — **2** days
+- `.claude/hooks/pre-suggest-compact.sh` — **2** days
+- `.claude/hooks/pre-write-doc-file-warning.sh` — **2** days
+- `.claude/hooks/pre-write-jinja-syntax.sh` — **2** days
+- `.claude/hooks/session-start-bootstrap.sh` — **2** days
+- `.claude/hooks/stop-cost-tracker.sh` — **2** days
+- `.claude/hooks/stop-desktop-notify.sh` — **2** days
+- `.claude/hooks/stop-evaluate-session.sh` — **2** days
+- `.claude/hooks/stop-session-end.sh` — **2** days
+- `.claude/rules/README.md` — **2** days
+- `.claude/rules/bash/coding-style.md` — **2** days
+- `.claude/rules/bash/security.md` — **2** days
+- `.claude/rules/common/code-review.md` — **2** days
+- `.claude/rules/common/coding-style.md` — **2** days
+- `.claude/rules/common/development-workflow.md` — **2** days
+- `.claude/rules/common/git-workflow.md` — **2** days
+- `.claude/rules/common/security.md` — **2** days
+- `.claude/rules/common/testing.md` — **2** days
+- `.claude/rules/jinja/coding-style.md` — **2** days
+- `.claude/rules/jinja/testing.md` — **2** days
+- `.claude/rules/markdown/conventions.md` — **2** days
+- `.claude/rules/python/coding-style.md` — **2** days
+- `.claude/rules/python/hooks.md` — **2** days
+- `.claude/rules/python/patterns.md` — **2** days
+- `.claude/rules/python/security.md` — **2** days
+- `.claude/rules/python/testing.md` — **2** days
+- `.claude/rules/yaml/conventions.md` — **2** days
+- `.claude/settings.json` — **2** days
+- `CLAUDE.md` — **2** days
+- `template/.claude/hooks/README.md` — **2** days
+- `template/.claude/hooks/post-edit-markdown.sh` — **2** days
+- `template/.claude/hooks/post-edit-python.sh` — **2** days
+- `template/.claude/hooks/pre-bash-block-no-verify.sh` — **2** days
+- `template/.claude/hooks/pre-bash-commit-quality.sh` — **2** days
+- `template/.claude/hooks/pre-bash-git-push-reminder.sh` — **2** days
+- `template/.claude/hooks/pre-config-protection.sh` — **2** days
+- `template/.claude/hooks/pre-protect-uv-lock.sh` — **2** days
+- `template/.claude/rules/README.md` — **2** days
+- `template/.claude/rules/bash/coding-style.md` — **2** days
+- `template/.claude/rules/bash/security.md` — **2** days
+- `template/.claude/rules/common/code-review.md` — **2** days
+- `template/.claude/rules/common/coding-style.md` — **2** days
+- `template/.claude/rules/common/development-workflow.md` — **2** days
+- `template/.claude/rules/common/git-workflow.md` — **2** days
+- `template/.claude/rules/common/security.md` — **2** days
+- `template/.claude/rules/common/testing.md` — **2** days
+- `template/.claude/rules/markdown/conventions.md` — **2** days
+- `template/.claude/rules/python/coding-style.md.jinja` — **2** days
+- `template/.claude/rules/python/hooks.md` — **2** days
+- `template/.claude/rules/python/patterns.md.jinja` — **2** days
+- `template/.claude/rules/python/security.md` — **2** days
+- `template/.claude/rules/python/testing.md` — **2** days
+- `template/.claude/settings.json` — **2** days
+- `template/.github/workflows/security.yml.jinja` — **2** days
+- `.github/labeler.yml` — **1** days
+- `.github/renovate.json` — **1** days
+- `.pre-commit-config.yaml` — **1** days
+- `.secrets.baseline` — **1** days
+- `template/.github/renovate.json.jinja` — **1** days
+- `template/.pre-commit-config.yaml.jinja` — **1** days
+- `template/.secrets.baseline` — **1** days
+- `template/CLAUDE.md.jinja` — **1** days
+- `template/CONTRIBUTING.md.jinja` — **1** days
+- `template/README.md.jinja` — **1** days
+- `template/SECURITY.md.jinja` — **1** days
+- `template/cliff.toml.jinja` — **1** days
+- `template/docs/ci.md.jinja` — **1** days
+- `template/docs/index.md.jinja` — **1** days
+- `template/mkdocs.yml.jinja` — **1** days
+- `template/src/{{ package_name }}/__init__.py.jinja` — **1** days
+- `template/src/{{ package_name }}/cli.py.jinja` — **1** days
+- `template/tests/test_imports.py.jinja` — **1** days
+- `.claude/rules/copier/template-conventions.md` — **0** days
+- `.github/workflows/file-freshness.yml` — **0** days
+- `.github/workflows/labeler.yml` — **0** days
+- `.github/workflows/pre-commit-update.yml` — **0** days
+- `.github/workflows/security.yml` — **0** days
+- `.github/workflows/sync-skip-if-exists.yml` — **0** days
+- `.github/workflows/tests.yml` — **0** days
+- `.gitignore` — **0** days
+- `copier.yml` — **0** days
+- `docs/repo_file_status_report.md` — **0** days
+- `env.example` — **0** days
+- `file_freshness.json` — **0** days
+- `freshness_ignore.json` — **0** days
+- `freshness_summary.json` — **0** days
+- `justfile` — **0** days
+- `pyproject.toml` — **0** days
+- `scripts/repo_file_freshness.py` — **0** days
+- `scripts/sync_skip_if_exists.py` — **0** days
+- `template/.github/workflows/release.yml.jinja` — **0** days
+- `template/.gitignore.jinja` — **0** days
+- `template/env.example.jinja` — **0** days
+- `template/justfile.jinja` — **0** days
+- `template/pyproject.toml.jinja` — **0** days
+- `template/src/{{ package_name }}/common/bump_version.py.jinja` — **0** days
+- `template/src/{{ package_name }}/common/logging_manager.py.jinja` — **0** days
+- `template/tests/conftest.py.jinja` — **0** days
+- `template/tests/{{ package_name }}/test_support.py.jinja` — **0** days
+- `tests/test_repo_file_freshness.py` — **0** days
+- `tests/test_template.py` — **0** days
+- `uv.lock` — **0** days
+
+## 🟡 Yellow (moderate)
+
+_None._
+
+## 🔴 Red (stale)
+
+_None._
+
+## 🔵 Blue (ignored)
+
+_None._
+