diff --git a/README.md b/README.md index c3a213a..2c77933 100644 --- a/README.md +++ b/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

-----------------------------------------------------

+## 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. + +

-----------------------------------------------------

+ ## 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. diff --git a/agent-quickstart.md b/agent-quickstart.md index 7edbb9d..0d0440e 100644 --- a/agent-quickstart.md +++ b/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: diff --git a/existing-project.md b/existing-project.md index 04b3bab..52ea211 100644 --- a/existing-project.md +++ b/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. diff --git a/files/AGENTS.md b/files/AGENTS.md index c0f462c..3972ee4 100644 --- a/files/AGENTS.md +++ b/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. diff --git a/files/repo-cleanup-gitea.yml b/files/repo-cleanup-gitea.yml new file mode 100644 index 0000000..a4b7156 --- /dev/null +++ b/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 diff --git a/manifest.json b/manifest.json index 0dc9dc9..6a1eb39 100644 --- a/manifest.json +++ b/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": [ diff --git a/manifest.schema.json b/manifest.schema.json index 6df4919..649d507 100644 --- a/manifest.schema.json +++ b/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"], diff --git a/new-repository.md b/new-repository.md index febd3a6..bfe1ec6 100644 --- a/new-repository.md +++ b/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: