Add scheduled repository cleanup workflow

README.md

@@ -61,6 +61,7 @@ Use only the files that fit the project. For a tiny script repo, `AGENTS.md`, `R
 | `files/project.md` | `.codex/project.md` |
 | `files/build-gitea.yml` | `.gitea/workflows/build.yml` |
 | `files/security-scan-gitea.yml` | `.gitea/workflows/security-scan.yml` |
+| `files/repo-cleanup-gitea.yml` | `.gitea/workflows/repo-cleanup.yml` |
 | `files/release-checklist.md` | `docs/release-checklist.md` |
 | `files/security-review.md` | `docs/security-review.md` |
 | `files/blueprint.md` | `blueprint.md` |
@@ -125,6 +126,7 @@ When applying this kit, an agent should:
 - update `README.md` whenever README blueprint files change,
 - update security and release docs when release behavior changes,
 - add or preserve scheduled security automation for releasable projects,
+- add or preserve scheduled repository cleanup checks for active projects,
 - update `docs/agent-handoff.md` when work is interrupted, risky, or multi-session,
 - run `git diff --check` before finishing,
 - run the cheapest reliable verification command,
@@ -147,6 +149,21 @@ The workflow is intentionally conservative. If it fails, an agent should inspect
 
 <p align="center"><img src="https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png" alt="-----------------------------------------------------" width="100%"></p>
 
+## Scheduled Repository Cleanup
+
+`files/repo-cleanup-gitea.yml` provides an optional weekly Gitea workflow for active repositories.
+
+It reports:
+
+- generated files or dependency folders that were accidentally tracked,
+- large tracked files that may belong in release artifacts or package storage,
+- secret-prone local config files,
+- stale remote branch candidates.
+
+The workflow is intentionally non-destructive. It must not delete files, branches, packages, or releases. Agents should treat failures as maintenance reports, document intentional exceptions, and only remove repository data after explicit user approval.
+
+<p align="center"><img src="https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png" alt="-----------------------------------------------------" width="100%"></p>
+
 ## Gitea API Token
 
 When working with private repositories on `git.wilkensxl.de`, Codex agents may find a local `GITEA_TOKEN` environment variable on the machine.

agent-quickstart.md

@@ -10,6 +10,7 @@ Use its copyMap for file destinations.
 Use new-repository.md or existing-project.md as the task workflow.
 Use matching profiles/*.md guidance after detecting the stack.
 For releasable projects, add or preserve scheduled security automation.
+For active projects, add or preserve non-destructive scheduled repository cleanup checks.
 Check git status before editing.
 Preserve unrelated user changes.
 Replace all applicable placeholders and remove non-applicable placeholder sections.
@@ -79,6 +80,10 @@ Is the project releasable or does it process user/secrets/config data?
   yes -> add .gitea/workflows/security-scan.yml or preserve equivalent scheduled security automation
   no  -> document why scheduled security automation is not needed
 
+Is this an active repository with generated files, artifacts, or branches?
+  yes -> add .gitea/workflows/repo-cleanup.yml or preserve equivalent cleanup checks
+  no  -> cleanup automation can be skipped
+
 Are commands unknown?
   yes -> document PENDING in .codex/project.md
   no  -> wire commands into AGENTS.md and CI
@@ -129,6 +134,7 @@ docs/security-review.md
 docs/agent-handoff.md
 .gitea/workflows/build.yml
 .gitea/workflows/security-scan.yml
+.gitea/workflows/repo-cleanup.yml
 ```
 
 For README-generator projects:

existing-project.md

@@ -122,6 +122,8 @@ If CI does not exist:
 
 For releasable projects, add `.gitea/workflows/security-scan.yml` unless the repository already has equivalent scheduled security automation. If an existing scanner is present, document it in `.codex/project.md` instead of duplicating it.
 
+For active repositories, add `.gitea/workflows/repo-cleanup.yml` unless equivalent cleanup checks already exist. Keep cleanup automation non-destructive and document intentional exceptions.
+
 ### 6. Security Review
 
 Fill `docs/security-review.md` with known facts.

files/AGENTS.md

@@ -21,6 +21,8 @@ PROJECT_NAME: PROJECT_DESCRIPTION
 - When the project uses `blueprint.md` and `blueprint.json` for README generation, keep the rainbow `{{ template:section-line }}` divider between major README sections. Do not replace it with plain `---` unless the target renderer cannot display inline images.
 - If README blueprint files are changed, regenerate or update `README.md` in the same change and verify the generated output renders reasonably.
 - For releasable projects, add or preserve `.gitea/workflows/security-scan.yml` using `files/security-scan-gitea.yml` unless the repository already has equivalent scheduled security automation.
+- For active projects, add or preserve `.gitea/workflows/repo-cleanup.yml` using `files/repo-cleanup-gitea.yml` unless the repository already has equivalent cleanup checks.
+- Repository cleanup automation must be non-destructive. Do not delete branches, packages, releases, or tracked files without explicit user approval.
 
 ## Commands
 
@@ -56,6 +58,7 @@ ARTIFACT_NAME
 - Review `docs/security-review.md` before release work.
 - Fill `docs/security-review.md` with actual checked commands and results when performing release-readiness work.
 - Review scheduled security workflow failures before changing code. Treat matches as leads: they may be true positives, documentation examples, or test fixtures.
+- Review repository cleanup workflow failures as maintenance leads. Document intentional exceptions instead of blindly deleting files.
 - Treat generated credentials and config files as sensitive.
 - Keep external network calls documented.
 - Prefer local processing for user data.

files/repo-cleanup-gitea.yml

@@ -0,0 +1,139 @@
+name: Scheduled Repository Cleanup Check
+
+on:
+  schedule:
+    - cron: "43 3 * * 1"
+  workflow_dispatch:
+
+jobs:
+  cleanup-check:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Check ignored and untracked generated files
+        shell: bash
+        run: |
+          echo "Ignored files that would be skipped by git:"
+          git status --ignored --short || true
+
+          echo
+          echo "Tracked generated files check:"
+          generated_patterns=(
+            '(^|/)node_modules/'
+            '(^|/)dist/'
+            '(^|/)build/'
+            '(^|/)out/'
+            '(^|/)release/'
+            '(^|/)target/'
+            '(^|/)coverage/'
+            '\.log$'
+            '\.tmp$'
+            '\.temp$'
+          )
+
+          found=0
+          tracked_files="$(git ls-files)"
+          for pattern in "${generated_patterns[@]}"; do
+            if echo "$tracked_files" | grep -Ei "$pattern"; then
+              found=1
+            fi
+          done
+
+          if [ "$found" -eq 1 ]; then
+            echo "Generated files appear to be tracked. Review .gitignore and remove generated outputs from version control if appropriate."
+            exit 1
+          fi
+
+      - name: Check large tracked files
+        shell: bash
+        run: |
+          limit_bytes="${LARGE_FILE_LIMIT_BYTES:-5242880}"
+          found=0
+
+          while IFS= read -r file; do
+            [ -f "$file" ] || continue
+            size="$(wc -c < "$file")"
+            if [ "$size" -gt "$limit_bytes" ]; then
+              echo "${file} is ${size} bytes, above limit ${limit_bytes}."
+              found=1
+            fi
+          done < <(git ls-files)
+
+          if [ "$found" -eq 1 ]; then
+            echo "Large tracked files found. Move release artifacts to packages/releases or document why they belong in git."
+            exit 1
+          fi
+
+      - name: Check local config and secret-prone files
+        shell: bash
+        run: |
+          found=0
+
+          risky_patterns=(
+            '^\.env$'
+            '^\.env\.'
+            '\.pfx$'
+            '\.p12$'
+            '\.pem$'
+            '\.key$'
+            '\.token$'
+            '(^|/)secrets/'
+          )
+
+          tracked_files="$(git ls-files)"
+          for pattern in "${risky_patterns[@]}"; do
+            if echo "$tracked_files" | grep -Ei "$pattern" | grep -vE '^\.env\.example$'; then
+              found=1
+            fi
+          done
+
+          if [ "$found" -eq 1 ]; then
+            echo "Secret-prone local config files are tracked. Review immediately."
+            exit 1
+          fi
+
+      - name: Check stale branches
+        shell: bash
+        run: |
+          git fetch --all --prune
+
+          protected='^(main|master|develop|dev|release|staging|production)$'
+          cutoff="$(date -u -d '90 days ago' +%s)"
+          found=0
+
+          while IFS='|' read -r branch timestamp; do
+            branch="${branch#origin/}"
+            [ "$branch" = "HEAD" ] && continue
+            echo "$branch" | grep -Eq "$protected" && continue
+
+            if [ "$timestamp" -lt "$cutoff" ]; then
+              echo "Stale remote branch candidate: ${branch}"
+              found=1
+            fi
+          done < <(git for-each-ref refs/remotes/origin --format='%(refname:short)|%(committerdate:unix)')
+
+          if [ "$found" -eq 1 ]; then
+            echo "Stale branch candidates found. Review manually before deleting anything."
+            exit 1
+          fi
+
+      - name: Cleanup guidance
+        shell: bash
+        run: |
+          cat <<'EOF'
+          Repository cleanup check completed.
+
+          This workflow reports cleanup candidates. It does not delete branches,
+          packages, releases, or files automatically.
+
+          Recommended manual follow-up:
+          - remove generated files from git,
+          - update .gitignore,
+          - move large artifacts to releases or package registry,
+          - review stale branches,
+          - document intentional exceptions.
+          EOF

manifest.json

@@ -12,6 +12,7 @@
     "Update README.md whenever blueprint.md or blueprint.json changes.",
     "Update docs/security-review.md during release-readiness work.",
     "Update docs/release-checklist.md when release behavior changes.",
+    "Add or preserve non-destructive scheduled repository cleanup checks for active projects.",
     "Run git diff --check before finishing.",
     "Run the cheapest reliable verification command or document why it could not run.",
     "After pushing workflow-triggering commits, poll Gitea workflow runs until success or a concrete blocker."
@@ -27,6 +28,18 @@
       "AI instruction injection scan"
     ]
   },
+  "cleanupAutomation": {
+    "workflow": "files/repo-cleanup-gitea.yml",
+    "target": ".gitea/workflows/repo-cleanup.yml",
+    "schedule": "weekly",
+    "checks": [
+      "tracked generated files",
+      "large tracked files",
+      "secret-prone local config files",
+      "stale branch candidates"
+    ],
+    "destructive": false
+  },
   "readmeDivider": {
     "templateName": "section-line",
     "source": "https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png",
@@ -108,6 +121,11 @@
       "source": "files/security-scan-gitea.yml",
       "target": ".gitea/workflows/security-scan.yml",
       "required": false
+    },
+    {
+      "source": "files/repo-cleanup-gitea.yml",
+      "target": ".gitea/workflows/repo-cleanup.yml",
+      "required": false
     }
   ],
   "placeholders": [

manifest.schema.json

@@ -55,6 +55,30 @@
         }
       }
     },
+    "cleanupAutomation": {
+      "type": "object",
+      "required": ["workflow", "target", "schedule", "checks", "destructive"],
+      "properties": {
+        "workflow": {
+          "type": "string"
+        },
+        "target": {
+          "type": "string"
+        },
+        "schedule": {
+          "type": "string"
+        },
+        "checks": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "destructive": {
+          "type": "boolean"
+        }
+      }
+    },
     "workflows": {
       "type": "object",
       "required": ["newRepository", "existingProject", "quickstart"],

new-repository.md

@@ -51,6 +51,7 @@ files/blueprint.md           -> blueprint.md
 files/blueprint.json         -> blueprint.json
 files/build-gitea.yml        -> .gitea/workflows/build.yml
 files/security-scan-gitea.yml -> .gitea/workflows/security-scan.yml
+files/repo-cleanup-gitea.yml -> .gitea/workflows/repo-cleanup.yml
 ```
 
 Skip `build-gitea.yml` when the project has no CI target yet. Skip README blueprint files when the project should keep a very small manual README.
@@ -159,6 +160,8 @@ Only publish artifacts to a package registry when the artifact names and credent
 
 For releasable projects, config tools, apps, or repositories that process user data, secrets, or deployment files, also add `.gitea/workflows/security-scan.yml`. Keep the scheduled workflow conservative and review false positives before silencing checks.
 
+For active repositories, also add `.gitea/workflows/repo-cleanup.yml`. It should report cleanup candidates only; it must not delete files, branches, packages, or releases automatically.
+
 ### 7. Finish
 
 Before final response: