From 8a2b9840b6639731eadd935bab11a9d678a5e0c6 Mon Sep 17 00:00:00 2001
From: Ahmet Abdullah Gultekin <rollingcat.help@gmail.com>
Date: Sat, 13 Jun 2026 09:18:48 +0000
Subject: [PATCH] feat(structure-lock): freeze root layout + CI gate +
 pre-commit (FIVUCSAS#209)

Pilot the org repo structure-lock on the umbrella repo.

- .repo-structure.yml: allowlists FROZEN from the current clean origin/master
  root (16 root files + 20 root dirs) + forbidden_root_patterns so dated
  tracking docs (*_AUDIT_*, *_2026-06-13*, TODO*/ROADMAP*/BACKLOG*) can never
  reappear at root + required_files (README/LICENSE/.gitignore).
- .github/workflows/structure-check.yml: thin caller of the org reusable
  workflow Rollingcat-Software/.github .github/workflows/repo-structure.yml@main,
  on pull_request. FAILS the PR on any layout drift.
- .pre-commit-config.yaml: add the `repo-structure` hook from the .github repo
  for fast local feedback mirroring the CI gate.

Verified: check PASSES on the current clean root (exit 0) and FAILS on a
planted TEST_AUDIT_2026-06-13.md (exit 1, FORBIDDEN). Dummy removed.

Depends on Rollingcat-Software/.github#2 (reusable workflow + script).
---
 .github/workflows/structure-check.yml | 19 ++++++++
 .pre-commit-config.yaml               |  8 +++
 .repo-structure.yml                   | 70 +++++++++++++++++++++++++++
 3 files changed, 97 insertions(+)
 create mode 100644 .github/workflows/structure-check.yml
 create mode 100644 .repo-structure.yml

diff --git a/.github/workflows/structure-check.yml b/.github/workflows/structure-check.yml
new file mode 100644
index 0000000..0345a2c
--- /dev/null
+++ b/.github/workflows/structure-check.yml
@@ -0,0 +1,19 @@
+# Repo structure-lock gate (Rollingcat-Software/FIVUCSAS#209).
+#
+# Thin caller for the org-shared reusable workflow. It FREEZES this repo's root
+# layout (see .repo-structure.yml) and FAILS the PR when a disallowed/forbidden
+# file appears — e.g. a stray dated tracking doc at the root.
+#
+# Owner step to make it BLOCK merges: add the status check named
+# "structure-check / repo-structure / structure-check" (the reusable job) as a
+# REQUIRED check in this repo's branch protection. See the PR body for the exact
+# command.
+name: structure-check
+
+on:
+  pull_request:
+    branches: [master, main]
+
+jobs:
+  repo-structure:
+    uses: Rollingcat-Software/.github/.github/workflows/repo-structure.yml@main
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index c8db6c5..98763ba 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -7,3 +7,11 @@ repos:
     rev: v8.21.2
     hooks:
       - id: gitleaks
+  # Repo structure-lock (FIVUCSAS#209) — fast local feedback mirroring the CI
+  # gate (.github/workflows/structure-check.yml). Freezes the root layout and
+  # blocks stray/dated tracking docs before they are committed. Pin `rev` to a
+  # tag/SHA once the org .github repo cuts one.
+  - repo: https://github.com/Rollingcat-Software/.github
+    rev: main
+    hooks:
+      - id: repo-structure
diff --git a/.repo-structure.yml b/.repo-structure.yml
new file mode 100644
index 0000000..540632a
--- /dev/null
+++ b/.repo-structure.yml
@@ -0,0 +1,70 @@
+# Repo structure-lock policy — FIVUCSAS umbrella (Rollingcat-Software/FIVUCSAS#209)
+#
+# An ArchUnit-style FREEZE of this repo's ROOT layout. The allowlists below were
+# frozen from the clean origin/master root after the 2026-06 cleanup; the gate
+# (tools/check_repo_structure.py in the org .github repo, run via the reusable
+# workflow .github/workflows/structure-check.yml) FAILS CI when:
+#   * a root entry not listed here appears, OR
+#   * any root entry matches a forbidden pattern, OR
+#   * a required file is missing.
+#
+# Dated tracking docs (audits / reviews / sessions / TODOs) belong in GitHub
+# issues, NOT the repo root — that is what forbidden_root_patterns encodes.
+# To intentionally add a NEW root entry, add it here in the SAME PR (the
+# explicit, reviewed "unfreeze"). Parsed by a stdlib-only YAML subset, so keep
+# to simple `- "string"` block lists.
+
+allowed_root_files:
+  - "CHANGELOG.md"
+  - "CLAUDE.md"
+  - "CONTRIBUTING.md"
+  - "LICENSE"
+  - "LOCAL_TESTING_RUNBOOK.md"
+  - "OPERATOR_SECURITY_RUNBOOKS.md"
+  - "README.md"
+  - "SECURITY.md"
+  - "docker-compose.yml"
+  - "docker-compose.dev.yml"
+  - "docker-compose.prod.yml"
+  - ".env.example"
+  - ".gitignore"
+  - ".gitmodules"
+  - ".pre-commit-config.yaml"
+  - ".pre-commit-install"
+  - ".repo-structure.yml"
+
+allowed_root_dirs:
+  - ".claude"
+  - ".github"
+  - "biometric-processor"
+  - "bys-demo"
+  - "client-apps"
+  - "docs"
+  - "docs-site"
+  - "identity-core-api"
+  - "infra"
+  - "landing-website"
+  - "links-website"
+  - "load-tests"
+  - "monitoring"
+  - "nginx"
+  - "practice-and-test"
+  - "scripts"
+  - "spoof-detector"
+  - "Thesis"
+  - "verify-widget"
+  - "web-app"
+
+# Dated / tracking-doc names that must NEVER reappear at the root.
+# These are Python `re` patterns, matched with re.search against each root entry
+# name. Tracking content goes in GitHub issues instead. Use SINGLE quotes so
+# backslashes stay literal (write \d and \. — not \\d) for the regex engine.
+forbidden_root_patterns:
+  - '.*_(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:
+  - "README.md"
+  - "LICENSE"
+  - ".gitignore"