fix: harden Flow inspector safety

.github/workflows/ci.yml

@@ -43,4 +43,4 @@ jobs:
         run: python -m unittest discover -s tests -v
 
       - name: Compile flow inspector
-        run: python -m py_compile scripts/flow/inspect_repo_flow.py
+        run: python -m py_compile scripts/flow/inspector_core.py scripts/flow/inspect_repo_flow.py

README.md

@@ -21,7 +21,7 @@ For the high-level relationship between `flow`, `bootstrap`, `.github`, individu
 - [`schemas/`](schemas/) - issue and PR contract schemas.
 - [`github/`](github/) - canonical labels, issue templates, project fields, and PR template inputs.
 - [`dashboards/`](dashboards/) - saved query patterns for operational review.
-- [`scripts/flow/inspect_repo_flow.py`](scripts/flow/inspect_repo_flow.py) - local inspector for repo flow metadata.
+- [`scripts/flow/inspect_repo_flow.py`](scripts/flow/inspect_repo_flow.py) - read-only-by-default inspector for repo flow metadata; see the [operator guide](docs/flow-inspector.md).
 - [`docs/autonomous-flow-platform.md`](docs/autonomous-flow-platform.md) - design rationale and rollout plan.
 - [`docs/omt-global-operating-map.md`](docs/omt-global-operating-map.md) - org-level ownership map.
 
@@ -52,15 +52,20 @@ Open PR clearance has priority over starting new implementation work:
 ```sh
 python -m json.tool schemas/issue-contract.schema.json >/dev/null
 python -m json.tool schemas/pr-contract.schema.json >/dev/null
-python -m py_compile scripts/flow/inspect_repo_flow.py
+python -m py_compile scripts/flow/inspector_core.py scripts/flow/inspect_repo_flow.py
+python -m unittest discover -s tests -v
 ```
 
-Run the repo CI gate before opening a PR:
+Inspect a repository without mutating GitHub or local assignment state:
 
 ```sh
-bash scripts/ci/run-fast-checks.sh
+python scripts/flow/inspect_repo_flow.py --repo OMT-Global/flow --issues
 ```
 
+The inspector requires explicit mutation flags and explicit output/assignment
+paths. Review the proposed writes in the default report before following the
+[apply examples](docs/flow-inspector.md#apply-reviewed-writes).
+
 ## Bootstrap Relationship
 
 `flow` defines the operating protocol. `bootstrap` projects the relevant repo-local pieces into OMT-Global repositories through `project.bootstrap.yaml`, managed templates, labels, workflows, and GitHub policy. Update policy here first, then let bootstrap reconcile downstream repos deliberately.

docs/flow-inspector.md

@@ -0,0 +1,85 @@
+# Flow inspector operator guide
+
+The Flow inspector classifies live GitHub issues and pull requests, chooses the
+next actor, and reports proposed state, lane, and repair-assignment changes. Its
+default mode is read-only: it does not edit GitHub labels or assignment state,
+and it does not write a report unless an output path is supplied.
+
+## Inspect without mutation
+
+```sh
+python scripts/flow/inspect_repo_flow.py \
+  --repo OMT-Global/flow \
+  --issues
+```
+
+Use `--json` for the complete report on stdout or configure an explicit,
+atomic file output:
+
+```sh
+python scripts/flow/inspect_repo_flow.py \
+  --repo OMT-Global/flow \
+  --issues \
+  --json-out /tmp/flow-inspection.json
+```
+
+Each report says `mode: read-only` and includes `proposedWrites`. A check
+rollup is green only when at least one check is present and every observed check
+completed successfully. Empty, pending, neutral, skipped, cancelled, malformed,
+or unknown evidence cannot produce a green classification.
+
+If the host has a maintenance gate, configure it explicitly:
+
+```sh
+python scripts/flow/inspect_repo_flow.py \
+  --repo OMT-Global/flow \
+  --maintenance-gate /opt/omt/check_maintenance_gate.sh
+```
+
+No repository, workspace, report directory, assignment store, or maintenance
+script path is built into the inspector.
+
+## Apply reviewed writes
+
+These commands mutate external or local state. First run the matching read-only
+inspection and review `proposedWrites`.
+
+Reconcile GitHub state and lane labels:
+
+```sh
+python scripts/flow/inspect_repo_flow.py \
+  --repo OMT-Global/flow \
+  --issues \
+  --apply-labels \
+  --label-limit 10
+```
+
+Reconciliation adds the desired state/lane and removes every stale label in the
+same mutually exclusive `state:` or `lane:` family. Other label families are
+left untouched.
+
+Dispatch repair candidates to an explicit assignment store:
+
+```sh
+python scripts/flow/inspect_repo_flow.py \
+  --repo OMT-Global/flow \
+  --dispatch-repairs \
+  --dispatch-limit 5 \
+  --assignments /var/lib/omt/pr-repair-assignments.json
+```
+
+Assignment updates hold an exclusive sidecar lock for the read/modify/write
+transaction, write a temporary file in the destination directory, flush it,
+and atomically replace the destination. Existing repository/PR assignments are
+deduplicated while the lock is held.
+
+## Verification
+
+```sh
+python -m py_compile scripts/flow/inspector_core.py scripts/flow/inspect_repo_flow.py
+python -m unittest discover -s tests -p 'test_flow_inspector.py' -v
+python scripts/flow/inspect_repo_flow.py --help
+```
+
+Never use `--apply-labels` or `--dispatch-repairs` for a smoke test. Live
+mutation testing is a human decision point and must be explicitly authorized.