feat(structure-lock): org reusable workflow + stdlib check script (FIVUCSAS#209)

[ahmetabdullahgultekin]

What

An ArchUnit-style FREEZE for repo file/folder layout, shared org-wide. It blocks (red CI check), it does not silently auto-move — exactly like ArchUnit fails the build. Tracks Rollingcat-Software/FIVUCSAS#209.

This is the dependency PR: it ships the reusable workflow + check script. The FIVUCSAS pilot PR (policy + caller + pre-commit) consumes it.

Contents

File	Purpose
tools/check_repo_structure.py	Stdlib-only checker (no PyYAML, no deps). Reads a per-repo .repo-structure.yml, scans the repo root, exits 1 listing every offender.
tools/test_check_repo_structure.py	12 unittest cases. Run: cd tools && python3 -m unittest test_check_repo_structure.
.github/workflows/repo-structure.yml	Reusable workflow_call. Checks out the caller repo + this repo (for the script), runs the check on ubuntu-latest.
.pre-commit-hooks.yaml	Exports the repo-structure pre-commit hook (language: script) for local fast-feedback.
.repo-structure.yml + .github/workflows/structure-check.yml	This repo eats its own dog food (frozen root + self-calling gate).

Policy schema (.repo-structure.yml)

allowed_root_files:   [ ... ]          # frozen baseline of root files
allowed_root_dirs:    [ ... ]          # frozen baseline of root dirs
forbidden_root_patterns:               # Python regexes (single-quote them!)
  - '.*_(AUDIT|REVIEW|FINDINGS|REGISTER|TRIAGE|SWEEP|STATUS|SESSION|RECONCILIATION)_.*\.md$'
  - '.*_\d{4}-\d{2}-\d{2}.*\.md$'
  - '^(TODO|ROADMAP|BACKLOG|OPERATOR_TODO|PERSONAL_TODO).*\.md$'
required_files:       [ ... ]

The gate fails (exit 1) when: a root entry not in the allowlist appears, OR a path matches a forbidden pattern, OR a required file is missing. To intentionally add a new root entry you edit the policy in the same PR — the explicit, reviewed "unfreeze".

YAML note: the parser reads a deliberately small subset (block/flow lists of - "string" items) and keeps backslashes literal. Write regexes with single backslashes in single quotes ('\d', '\.') — double-quoted "\\d" would store a literal backslash and break the pattern.

Why ubuntu-latest, not the self-hosted runner

The check is a tiny stdlib Python job. It deliberately runs on GitHub-hosted ubuntu-latest so it never depends on the resource-constrained self-hosted Hetzner runner.

Security

Workflow inputs (policy, tools-ref) come from the trusted caller, not event data. policy is still passed through env: (never interpolated into the run: line). tools-ref is only used as a checkout ref.

--fix (convenience, never in CI)

python3 tools/check_repo_structure.py --fix [--dry-run] MOVES forbidden root tracking-docs into docs/archive/. Files only (never dirs, never disallowed-but-not-forbidden entries — those need a human). The gate is primary; --fix is a manual helper.

Proof (run locally against the FIVUCSAS clean root)

$ python3 tools/check_repo_structure.py --root <fivucsas>
Repo structure-lock PASSED — root layout matches .repo-structure.yml.   (exit 0)

$ : > <fivucsas>/TEST_AUDIT_2026-06-13.md
$ python3 tools/check_repo_structure.py --root <fivucsas>
Repo structure-lock FAILED ... FORBIDDEN: 'TEST_AUDIT_2026-06-13.md' matches /.*_(AUDIT|...)_.*\.md$/   (exit 1)

12/12 unit tests green.

Rollout (after merge)

1. Merge this PR (owner). Optionally cut a tag (e.g. v1) so consumers can pin @v1 instead of @main.
2. Each consuming repo adds .repo-structure.yml (frozen from its own root) + a thin caller .github/workflows/structure-check.yml that does uses: Rollingcat-Software/.github/.github/workflows/repo-structure.yml@main. The FIVUCSAS PR is the worked example.
3. Owner manual step per repo: add the status check structure-check / repo-structure / structure-check as a REQUIRED check in branch protection so violations actually block merge.

Do not merge until reviewed; owner sets the required check.