phase 0: scaffold + layer guard + ci wiring

.github/workflows/layer_guard.yml

@@ -0,0 +1,21 @@
+name: Layer guard
+
+on:
+  push:
+    branches:
+      - "refactor/hexagonal"
+      - "refactor/phase-**"
+  pull_request:
+    branches:
+      - "refactor/hexagonal"
+
+jobs:
+  layer-import-guard:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Run layer guard
+        run: python scripts/check_layer_imports.py

.github/workflows/lint.yml

@@ -2,9 +2,16 @@ name: Linting
 
 on:
   push:
-    branches: [ main, dev ]  
+    branches:
+      - main
+      - dev
+      - "refactor/hexagonal"
+      - "refactor/phase-**"
   pull_request:
-    branches: [ main, dev ]
+    branches:
+      - main
+      - dev
+      - "refactor/hexagonal"
 
 jobs:
   lint:

.github/workflows/unit_tests.yml

@@ -2,7 +2,11 @@ name: Unit tests
 
 on:
   push:
-    branches: [ main, dev ]
+    branches:
+      - main
+      - dev
+      - "refactor/hexagonal"
+      - "refactor/phase-**"
   pull_request:
 
 jobs:

.gitignore

@@ -59,9 +59,9 @@ volumes/*
 !volumes/.gitkeep # Keep the placeholder
 
 # services
-services/
-services/*
-!services/.gitkeep # Keep the placeholder
+/services/
+/services/*
+!/services/.gitkeep # Keep the placeholder
 
 *.csv
 *.pkl

REFACTORING_DECISION_LOG.md

@@ -0,0 +1,66 @@
+# Refactoring Decision Log
+
+Records **why** decisions were made that deviate from or extend the refactoring
+docs. When a decision changes the plan, update the strategy/workflow docs to
+reflect the new reality — then log the reasoning here so future readers know
+why the docs changed.
+
+Source abbreviations:
+- STRATEGY = `docs/refactoring/REFACTORING_STRATEGY_v1.md`
+- WORKFLOW = `docs/refactoring/REFACTORING_DEV_WORKFLOW.md`
+
+---
+
+## Phase 0 — Scaffold + import guard + CI wiring (2026-04-21)
+
+**1. The guard ignores files outside the four new layer roots.**
+Files under `openrag/components/`, `openrag/routers/`, `openrag/models/`,
+`openrag/config/`, `openrag/utils/` are skipped.
+- Why: Phase 0's verification requires existing tests to keep passing. If the
+  guard ran against legacy code, every old import that doesn't fit the new
+  rules would trip the check and block the phase. Legacy code gets migrated in
+  Phases 5–12 and the guard picks those files up as they move into the new
+  layer roots.
+- Alternative considered: whitelist-only enforcement on new code (same idea,
+  different framing). What we chose is "enforce wherever the file lives in one
+  of the four roots", which is simpler.
+
+**2. Split CI into `layer_guard.yml` + extending existing `lint.yml` and
+`unit_tests.yml`, instead of one new `refactor-ci.yml`.**
+WORKFLOW's CI example is a single file with three jobs (`unit-tests`,
+`layer-guard`, `docker-build`). We took a different shape.
+- Why: We already have a well-set-up `unit_tests.yml` and `lint.yml`. Creating
+  a parallel `refactor-ci.yml` with its own unit-tests job would duplicate the
+  uv setup and caching. Extending the existing files adds a few lines of
+  config and reuses everything.
+- Alternative considered: follow the WORKFLOW example literally. Rejected for
+  the duplication reason above. Trade-off is that refactor-specific CI isn't
+  all in one file.
+
+**3. `docker-build` CI check NOT wired in Phase 0.**
+WORKFLOW lists it as a required check.
+- Why: Existing `build.yml` and `build_dev.yml` workflows push images to ghcr,
+  which isn't what we want on every refactor push. A lightweight "docker build
+  only, don't push" check needs a new job. Deferred to keep Phase 0 scope
+  tight. Docker build was verified locally on the phase-0 tree.
+- Alternative considered: add the job in this phase. Rejected for scope.
+  Follow-up: add a `docker-build` job in a separate PR, modelled on the
+  WORKFLOW CI example.
+
+**4. Decision log policy: log reasoning, update docs.**
+When a decision deviates from the strategy/workflow docs, update the docs to
+match reality, then record the reasoning here.
+- Why: The docs should always reflect the current plan. The log captures
+  why the plan changed, not what the plan is.
+
+---
+
+## Template for future entries
+
+```
+## Phase N — [short title] ([YYYY-MM-DD])
+
+**K. [decision in one line].**
+- Why: [what forced the call, what the docs didn't cover].
+- Alternative considered: [what else was on the table, why it was rejected].
+```