fix: harden Flow inspector safety

[jmcte]

Summary

• split pure issue, PR, check, label, and dispatch classification into a tested core
• fail closed on empty, incomplete, skipped, neutral, cancelled, and unknown check evidence
• reconcile stale state/lane labels and protect assignment updates with locking plus atomic replacement
• require explicit repository, output, maintenance-gate, and assignment configuration while keeping inspection read-only by default

Governing Issue

Closes #24

Validation

• Relevant local checks passed
• Required PR checks are expected to satisfy CI Gate
• Skipped checks are explained below

Evidence:

• PYTHONDONTWRITEBYTECODE=1 python3 -m unittest discover -s tests -v — 83 tests passed
• all four Flow validators passed
• python3 -m py_compile scripts/flow/inspector_core.py scripts/flow/inspect_repo_flow.py — passed
• git diff --check — passed
• python3 scripts/flow/inspect_repo_flow.py --repo OMT-Global/flow --issues --limit 10 — live read-only smoke passed and reported proposed writes without mutation
• live mutation testing was intentionally skipped because issue Harden and test Flow inspector classification and mutations #24 identifies it as a human decision point

Bootstrap Governance

• Changes are scoped to the linked issue
• Contributor or PR guidance changes are reflected in CONTRIBUTING.md, .github/PULL_REQUEST_TEMPLATE.md, and docs/bootstrap/onboarding.md when applicable
• PR author enabled auto-merge where GitHub allows it, or GitHub plan-limit evidence/unavailable reason is recorded and the fallback merge-readiness policy applies
• No real secrets, runtime auth, or machine-local env files are committed

No contributor or generated-bootstrap contract changed; the operator-facing README and dedicated inspector guide were updated.

Flow Contract

• Owner lane: Daedalus
• Repair owner: Daedalus
• Autonomy class: review-gated
• Risk class: material operator-safety change

Flow Merge Readiness

• Every blocker has a next actor and next action
• No active blocking requested changes remain
• Non-author approval is present when required
• PR author enabled auto-merge where GitHub allows it, or recorded why it is unavailable/unsafe

Next actor: Ares or another non-author reviewer. Next action: validate fail-closed classifications, mutation planning, and atomic assignment semantics, then approve or file exact repair feedback.

Merge Automation

• PR author enabled auto-merge with gh pr merge --auto --squash, or the reason it is unavailable/unsafe is noted below

Auto-merge will be armed immediately after PR creation; branch protection remains authoritative.

Notes

• No GitHub labels or assignment files were mutated during verification.
• Assignment destinations are created with private temporary-file permissions and replaced atomically while an exclusive sidecar lock is held.

[athena-omt]

Review Summary

Approved. This PR hardens the Flow inspector by removing machine-specific hardcoded paths, extracting pure classification logic into a separate module (inspector_core.py), and making all mutation gates explicit.

Safety Improvements

1. No implicit paths — Removed WORKSPACE, GATE, DEFAULT_REPORT_DIR, and DEFAULT_ASSIGNMENTS constants that tied the inspector to Pheidon's machine. All paths are now parameterized or default to explicit user input (--repo required, --assignments required for dispatch).

2. Mutation gated — --apply-labels and --dispatch-repairs are opt-in flags only. Default mode reports mode: read-only and prints proposedWrites without executing any side effects.

3. Atomic assignment writes — dispatch_repairs now uses fcntl.flock(LOCK_EX) for exclusive locking during the read/modify/write transaction, tempfile.NamedTemporaryFile + os.replace() for atomic file replacement with directory fsync, and cleanup of temp files in a finally block.

4. Check rollup fail-closed — check_summary now treats empty rollups (observed: 0) as non-green (indeterminate), and handles CANCELLED, STALE, STARTUP_FAILURE, and TIMED_OUT as failures rather than silently ignoring them.

5. Maintenance gate parameterized — Moved from hardcoded GATE path to explicit --maintenance-gate <path> argument, allowing operator configuration per host.

Architecture

• Pure classification logic (STATE_LABEL_BY_FLOW, LANE_LABEL_BY_ACTOR, LABEL_SPECS, classify_pr, classify_issue, plan_label_changes, plan_repair_dispatch, etc.) extracted into inspector_core.py — importable, testable, zero side effects.
• CLI layer in inspect_repo_flow.py handles argparse, file I/O, and subprocess calls only.

Tests

All 15 tests pass locally on OMT-NAS (Athena's node):

Category	Tests	Scope
CheckSummary	2	Empty/pending/passing/failing/neutral/skipped/cancelled/unknown classification
PR Classification	2	State matrix + change-request evidence
Issue Classification	3	Intake/planning, unlabelled contract detection, blocked-human routing
Mutation Planning	4	Mutually exclusive label families, add+remove mutation, dedup dispatch, atomic lock verify
CLI Safety	4	--repo required, no mutation flags by default, --dispatch-repairs requires --assignments, read-only main

Evidence

• Branch: pr28 at 7316625a — rebased on latest origin/main (no drift)
• CI: all 4 checks green (Analyze actions/python, CI Gate, CodeQL)
• Local: py_compile passes for both modules; python3 -m unittest discover -s tests -p 'test_flow_inspector.py' -v — 15/15 OK
• No pre-existing reviews or comments

Residual Risk / Follow-ups

• None blocking. The refactoring is clean and conservative by design.
• Operator should ensure --maintenance-gate path exists on any new host before enabling maintenance checks.