From 6ee2433956f6f9dc7e24f9e154580027fcbca9f7 Mon Sep 17 00:00:00 2001
From: Ahmet Abdullah Gultekin <ahmetabdullahgultekin@gmail.com>
Date: Sat, 13 Jun 2026 09:45:37 +0000
Subject: [PATCH] repo-structure: freeze root layout + add structure-check gate

Mirrors the FIVUCSAS umbrella pilot (Rollingcat-Software/FIVUCSAS#209): freezes
the current root file/dir layout and adds the structure-check CI gate. Owner
adds the additive ruleset / required check afterward to make it blocking.
---
 .github/workflows/structure-check.yml | 19 ++++++++
 .pre-commit-config.yaml               | 17 +++++++
 .repo-structure.yml                   | 66 +++++++++++++++++++++++++++
 3 files changed, 102 insertions(+)
 create mode 100644 .github/workflows/structure-check.yml
 create mode 100644 .pre-commit-config.yaml
 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..0ee7128
--- /dev/null
+++ b/.github/workflows/structure-check.yml
@@ -0,0 +1,19 @@
+# Repo structure-lock gate — mirrors the FIVUCSAS umbrella pilot
+# (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
+# "repo-structure / structure-check" (the reusable job) as a REQUIRED check in
+# this repo's branch protection / ruleset. See the PR body for context.
+name: structure-check
+
+on:
+  pull_request:
+    branches: [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
new file mode 100644
index 0000000..e29c89d
--- /dev/null
+++ b/.pre-commit-config.yaml
@@ -0,0 +1,17 @@
+# Pre-commit hooks (IN-M1 — 2026-04-19).
+# Minimal set: gitleaks only. We deliberately skip detect-secrets to avoid
+# baselining maintenance overhead. Per-submodule configs may add more
+# (see biometric-processor/.pre-commit-config.yaml for the Python-heavy case).
+repos:
+  - repo: https://github.com/gitleaks/gitleaks
+    rev: v8.21.2
+    hooks:
+      - id: gitleaks
+  # Repo structure-lock (mirrors 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..837029b
--- /dev/null
+++ b/.repo-structure.yml
@@ -0,0 +1,66 @@
+# Repo structure-lock policy — Rollingcat-Software/docs
+#
+# An ArchUnit-style FREEZE of this repo's ROOT layout, mirroring the FIVUCSAS
+# umbrella pilot (Rollingcat-Software/FIVUCSAS#209). The allowlists below were
+# frozen from the current origin/main root; the gate (tools/check_repo_structure.py
+# in the org .github repo, run via the reusable workflow
+# .github/workflows/repo-structure.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.
+# (Dated/sectioned CONTENT lives in the numbered subdirectories, not the root.)
+# 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:
+  - ".gitignore"
+  - ".pre-commit-config.yaml"
+  - ".repo-structure.yml"
+  - "LICENSE"
+  - "README.md"
+  - "SECURITY.md"
+  - "SECURITY_INCIDENTS.md"
+  - "gantt_fall.png"
+  - "gantt_spring.png"
+
+allowed_root_dirs:
+  - ".github"
+  - "00-meta"
+  - "01-getting-started"
+  - "02-architecture"
+  - "03-development"
+  - "04-api"
+  - "05-testing"
+  - "06-deployment"
+  - "07-status"
+  - "08-website"
+  - "09-auth-flows"
+  - "ADD_diagrams"
+  - "adr"
+  - "archive"
+  - "demo"
+  - "diagrams"
+  - "nginx"
+  - "plans"
+  - "presentations"
+  - "project"
+  - "scripts"
+  - "sql"
+
+# 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"