refactor(layout): src/ + tests/ + pyproject.toml, and a decluttered root

.github/workflows/ci.yml

@@ -56,7 +56,7 @@ jobs:
           ORCH_LOCAL_RUNTIME: ${{ runner.temp }}/orch-runtime
         run: |
           mkdir -p "$ORCH_STATE_DIR" "$ORCH_LOCAL_RUNTIME"
-          python3 verify.py
+          python3 src/verify.py
 
       # verify.py already fails on: any pytest failure, ZERO tests collected, a collection count
       # below the recorded floor, passed+skipped dropping below the floor, MORE SKIPS THAN THE
@@ -151,7 +151,7 @@ jobs:
           ORCH_LOCAL_RUNTIME: ${{ runner.temp }}/orch-runtime
         run: |
           mkdir -p "$ORCH_STATE_DIR" "$ORCH_LOCAL_RUNTIME"
-          python3 verify.py --reconcile-floor
+          python3 src/verify.py --reconcile-floor
 
       - name: Commit the reconciled floor
         run: |

.github/workflows/pr-00-gate.yml

@@ -130,23 +130,26 @@ jobs:
           lint = format_check = cache = RUN_CORE
           pytest_markers = 'not quarantine and not slow'
 
-          # typecheck (and its deprecated `run-mypy` alias) -- OFF.
-          #   blocking:  608 mypy errors across 89 of 189 files (measured 2026-08-23 on 24cb115 with
-          #              `python3 scripts/ci_lint_baseline.py`, which runs
-          #              `mypy --exclude .workflows-lib .` under the pinned mypy 2.3.1).
-          #              THIS NUMBER DRIFTS: it moved 601 -> 604 -> 607 -> 608 during
-          #              2026-08-23 as typed code landed, and nothing couples it to a
-          #              measurement, so re-run that script rather than trusting it.
-          #   drainable: 0 per PR. Every one is a real annotation or logic change in a distinct
-          #              module; there is no formatter and no `--fix` for this.
-          #   drains by: typed modules landing incrementally. Turn this on the same day the count
-          #              reaches 0, not before -- the 15 commonest of the 19 codes cover 603
-          #              of the 608, so a `disable_error_code` list would make the job green
-          #              while checking essentially nothing, the defect verify.py exists to stop.
-          #   note:      mypy.ini is committed even though the check is off, because without it
-          #              `mypy .` aborts on a duplicate-module setup error and the count above would
-          #              be unverifiable prose instead of a number anyone can regenerate.
-          typecheck = False
+          # typecheck (and its deprecated `run-mypy` alias) -- ON, over a BOUNDED scope.
+          #   It was OFF because 608 errors across the whole tree were drainable 0 per PR: an
+          #   all-or-nothing check over code that cannot be fixed in one change is a gate whose
+          #   clear path is blocked by the thing it measures, and it stayed shut.
+          #   Two changes made it openable, both real rather than cosmetic:
+          #     * the src/ move scoped the Gate's `target="src"` to the 99 modules, 608 -> 467;
+          #     * pyproject.toml's [[tool.mypy.overrides]] exempts the 66 modules that still have
+          #       findings BY NAME, so the 33 already-clean ones are checked TODAY.
+          #   blocking:  0. The check passes as configured -- `mypy --config-file pyproject.toml
+          #              --exclude .workflows-lib src` reports "no issues found in 99 source files".
+          #   drainable: 66 modules, one at a time, each by typing it and deleting its line from the
+          #              override list. That is a real mechanism, not "someone notices".
+          #   drains by: typed modules landing incrementally. Unlike the old OFF state this now
+          #              RATCHETS: `.verify-floor.json`'s `mypy_exempt_max` fails if the list grows,
+          #              so new untyped code in a clean module is a red, and verify.py prints the
+          #              remaining count on every run so green can never mean "checks nothing".
+          #   NOT a suppression: no error code is disabled anywhere. The 467 findings stay visible
+          #              (`python3 scripts/ci_lint_baseline.py`) and counted; only their MODULES are
+          #              scoped out, by name, from a list that can only shrink.
+          typecheck = RUN_CORE
 
           # coverage (and the soft gate that reads its artifacts) -- ON since 2026-08-23.
           #   was:       OFF until 2026-08-23. `reusable-10-ci-python.yml` appended

ADDING_CAPABILITIES.md

@@ -25,7 +25,7 @@ in a table nothing wrote for it.
 The dated evidence for all nine failure modes is deliberately **not** committed — it names this
 instance's repositories, PRs, spend and working constraints. It lives in
 `ADDING_CAPABILITIES.local.md` (see `LOCAL_POLICY.md`), and the item-by-item status history lives in
-the machine-local improvement log, reached with `python3 improvement_log.py search <term>`.
+the machine-local improvement log, reached with `python3 src/improvement_log.py search <term>`.
 
 The governing lesson survives the split, and it is the reason this file has a test file rather than
 only prose: **a rule that lives only in a document does not survive the next session.** `CLAUDE.md`
@@ -38,7 +38,7 @@ them.
 Enforced by `capability_admission.py` + `test_capability_admission.py`. Run **before** writing code:
 
 ```bash
-python3 capability_admission.py --preflight '{"capability_id":"capability:my-thing", ...}'
+python3 src/capability_admission.py --preflight '{"capability_id":"capability:my-thing", ...}'
 ```
 
 `preflight` answers the six declarable requirements immediately — including findability, which is the

ARCHITECTURE.md

@@ -656,16 +656,16 @@ unattended agent isn't caught until a bad outcome hours later), and the scaffold
 ### CLI
 
 ```bash
-python3 roles.py --selftest                       # offline contract checks
-python3 roles.py route --role redirect            # show the router-chosen backend
-python3 roles.py redirect --report-json r.json --ac "<acceptance criteria>" \
+python3 src/roles.py --selftest                       # offline contract checks
+python3 src/roles.py route --role redirect            # show the router-chosen backend
+python3 src/roles.py redirect --report-json r.json --ac "<acceptance criteria>" \
     [--proposal-json p.json]   # replay a captured proposal (offline)
-python3 roles.py redirect --report-json r.json --ac "..." --dispatch   # live offload to the backend
-python3 redirect_shadow.py record --report-json r.json --ac "..." --dispatch
-python3 redirect_shadow.py summarize
-python3 redirect_shadow.py historical-candidates
-python3 redirect_shadow.py link-outcome --role-run-id RID --influenced-run-id DOWNSTREAM_RID
-python3 roles.py link-outcome --role-run-id RID --influenced-run-id DOWNSTREAM_RID
+python3 src/roles.py redirect --report-json r.json --ac "..." --dispatch   # live offload to the backend
+python3 src/redirect_shadow.py record --report-json r.json --ac "..." --dispatch
+python3 src/redirect_shadow.py summarize
+python3 src/redirect_shadow.py historical-candidates
+python3 src/redirect_shadow.py link-outcome --role-run-id RID --influenced-run-id DOWNSTREAM_RID
+python3 src/roles.py link-outcome --role-run-id RID --influenced-run-id DOWNSTREAM_RID
 ```
 
 All `redirect` invocations print a dry-run plan and a SHADOW banner; none mutate state. Live dispatches
@@ -701,10 +701,10 @@ boundaries, risks, and confidence.
 ### CLI
 
 ```bash
-python3 roles.py route --role prompt
-python3 roles.py prompt --target owner/repo#N --goal "..." --task-type implement \
+python3 src/roles.py route --role prompt
+python3 src/roles.py prompt --target owner/repo#N --goal "..." --task-type implement \
   --target-detail "issue body or PR context" [--proposal-json p.json]
-python3 roles.py prompt --target owner/repo#N --goal "..." --task-type implement --dispatch
+python3 src/roles.py prompt --target owner/repo#N --goal "..." --task-type implement --dispatch
 ```
 
 ## DecomposerAgent — the third role (built 2026-06-20)
@@ -724,10 +724,10 @@ verification, and re-decomposition triggers.
 ### CLI
 
 ```bash
-python3 roles.py route --role decomposer
-python3 roles.py decompose --goal "..." --repo owner/repo --target owner/repo#N \
+python3 src/roles.py route --role decomposer
+python3 src/roles.py decompose --goal "..." --repo owner/repo --target owner/repo#N \
   [--subtask-count 3] [--proposal-json plan.json]
-python3 roles.py decompose --goal "..." --repo owner/repo --dispatch
+python3 src/roles.py decompose --goal "..." --repo owner/repo --dispatch
 ```
 
 ## TriageAgent — the fourth role (built 2026-06-20)
@@ -750,9 +750,9 @@ into advisory recommendations: work now, defer, needs scope, skip, monitor, and
 ### CLI
 
 ```bash
-python3 roles.py route --role triage
-python3 roles.py triage --backlog-json ~/.codex/handoff/backlog.json [--proposal-json triage.json]
-python3 roles.py triage --backlog-json ~/.codex/handoff/backlog.json --dispatch
+python3 src/roles.py route --role triage
+python3 src/roles.py triage --backlog-json ~/.codex/handoff/backlog.json [--proposal-json triage.json]
+python3 src/roles.py triage --backlog-json ~/.codex/handoff/backlog.json --dispatch
 ```
 
 ## AdjudicatorAgent — the fifth role (built 2026-06-20)
@@ -775,7 +775,7 @@ evidence.
 ### CLI
 
 ```bash
-python3 roles.py route --role adjudicator
-python3 roles.py adjudicate --case-json case.json [--proposal-json adjudication.json]
-python3 roles.py adjudicate --case-json case.json --dispatch
+python3 src/roles.py route --role adjudicator
+python3 src/roles.py adjudicate --case-json case.json [--proposal-json adjudication.json]
+python3 src/roles.py adjudicate --case-json case.json --dispatch
 ```

CLAUDE.md

@@ -156,8 +156,8 @@ back. Adding a "new" feature that already exists is the easy mistake here.
    "calibrat", "adversar", "drain" before building routing/recovery/calibration/review/quota work).
 2. Read the historical dormancy inventory:
    `Code/Audits/Orchestrator/2026-07-08-dormancy-rescan.md`, then generate current activation truth
-   with `python3 capabilities.py inventory`. Feature maturity is not activation evidence.
-3. Search the improvement log — `python3 improvement_log.py search <term>`. Items carry status
+   with `python3 src/capabilities.py inventory`. Feature maturity is not activation evidence.
+3. Search the improvement log — `python3 src/improvement_log.py search <term>`. Items carry status
    notes and many "ideas" are already DONE. The log is machine-local evidence living outside the
    tree, so **use the accessor, never a path**: it resolves `$ORCH_LOCAL_RUNTIME` for you, prints
    each hit under the item that owns it, and — when the log is not on this machine — names what is
@@ -173,7 +173,7 @@ or "exists at file:line, dormant behind FLAG; activating." **Record it in the ca
 after it was written.
 
 **`ADDING_CAPABILITIES.md` is the procedure, and it is ENFORCED.** Run
-`python3 capability_admission.py --preflight '<spec json>'` before writing code: a capability must
+`python3 src/capability_admission.py --preflight '<spec json>'` before writing code: a capability must
 arrive with a dedup finding, a caller, a heartbeat, a recurrence fixture, an outcome path, a kill
 switch, a rollback, an expiry-or-cadence, **and a surface that can offer it**.
 `test_capability_admission.py` fails the suite otherwise, and also fails on a citation to a dated
@@ -204,16 +204,30 @@ Do not create a second event log, model registry, or capability inventory.
   (default `~/.codex/orchestrator`), the machine-local state, which is never committed.
   `cmp`-clean is not agreement: re-run the verdict FROM THE MIRROR, since a path resolved relative
   to a module's own directory is right in one tree and wrong in the other.
+- **The modules live in `src/`, the tests in `tests/`, and the CHECKOUT ROOT IS NOT THE MODULE
+  DIRECTORY.** Those were the same directory until 2026-08-23, and every path in the tree was
+  derived from that accident. Two questions with two answers now: sibling modules resolve from
+  `paths.MODULE_DIR`, while `orchestrate.sh`, `.verify-floor.json`, `pyproject.toml` and the docs
+  resolve from `paths.REPO_ROOT`. **Never write `Path(__file__).resolve().parent` for a repo-root
+  file, and never hardcode `parent.parent` for it either** — `paths.checkout_root(module_dir)`
+  applies the rule, and the rule is DETECTED (module dir named `src` ⇒ checkout is its parent, else
+  they coincide) because THE MIRROR IS FLAT. A hardcoded prefix is right in one tree and wrong in
+  the other, which is the failure `capability_activation_audit._fleet_roots` already documents.
+  `orchestrate.sh` does the same detection in shell for `$ORCH`. Verify with
+  `python3 src/verify.py`.
 - **A remote merge is inert until the mirror is synced.** Keep that gap manual. It is the only
   circuit breaker between an agent's change and the dispatcher that dispatches those agents.
+  **The `src/` move needs a one-time patch to `orch-sync-mirror.sh`, which lives outside the repo:
+  its `cp "$SRC"/*.py` now matches nothing.** The patch and how to confirm it are in
+  `docs/MIRROR_SYNC_PATCH.md`. Until it is applied the mirror has no modules.
 - Run the touched module's `--selftest` (the project's test suite). Add a selftest case for new
   behavior, including a deliberate-break→revert demonstration for correctness-critical logic.
 - Register or update lifecycle state in `capabilities.py` for any new/wired capability. Run
-  `python3 capabilities.py --selftest` and `python3 capabilities.py --json validate`. Never mark a
+  `python3 src/capabilities.py --selftest` and `python3 src/capabilities.py --json validate`. Never mark a
   capability active from code existence, a passing selftest, or a feature-registry maturity alone;
   activation requires executable producer, consumer, outcome, expiry, kill-switch, and rollback
   evidence.
-- **Verify with `python3 verify.py`, never with `for t in test_*.py; do python3 "$t"; done`.**
+- **Verify with `python3 src/verify.py`, never with `for t in test_*.py; do python3 "$t"; done`.**
   Most test files are pytest-only: run directly they define their tests, execute nothing, and exit
   0 — which is how 9 failures and a two-month-old broken selftest went unnoticed. `verify.py` runs
   real pytest, reads the COUNTS rather than the exit status, enforces a collection floor so tests
@@ -334,7 +348,7 @@ and update the gated-features list in README.md + the dormancy inventory.
 When you activate a dormant feature, un-gate a flag, or add a subsystem: update its lifecycle
 record, regenerate the capability inventory, update README.md's functionality section if the
 topology changed, and record a status note on the relevant improvement-log item with
-`python3 improvement_log.py append <item-ref> "<note>"`. Use the accessor rather than editing a
+`python3 src/improvement_log.py append <item-ref> "<note>"`. Use the accessor rather than editing a
 file: the log is machine-local (outside the tree), the accessor finds the item and places the dated
 note inside it, and it REFUSES on an ambiguous or unknown ref rather than guessing — a note filed
 against the wrong item corrupts the record it exists to improve. Do not duplicate lifecycle verdicts

IMPROVEMENT_BACKLOG.md

@@ -7,9 +7,9 @@ is this instance's EVIDENCE, not the tool, so it lives outside the tree with the
 accessor, which resolves the path for you:
 
 ```bash
-python3 improvement_log.py search <term>        # CLAUDE.md §0 step 3 — is this already DONE?
-python3 improvement_log.py append <item-ref> "<note>"   # CLAUDE.md §5 — record a status note
-python3 improvement_log.py path                 # where it resolved to, and whether it is here
+python3 src/improvement_log.py search <term>        # CLAUDE.md §0 step 3 — is this already DONE?
+python3 src/improvement_log.py append <item-ref> "<note>"   # CLAUDE.md §5 — record a status note
+python3 src/improvement_log.py path                 # where it resolved to, and whether it is here
 ```
 
 `search` prints each hit under the item heading that owns it, plus the number of lines and sections it